@remnic/core 10.0.12 → 10.0.14

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;
+}

package/src/console/trace.ts

@@ -32,6 +32,7 @@ import path from "node:path";
 import readline from "node:readline";
 import { createReadStream } from "node:fs";
 import type { Writable } from "node:stream";
+import { sleepAbortable } from "../utils/sleep.js";
 
 import { renderFrame } from "./tui.js";
 import type { ConsoleStateSnapshot } from "./state.js";
@@ -465,43 +466,11 @@ function normalizeSpeed(speed: number | undefined): number {
 }
 
 /**
- * Abortable sleep used by `replayTrace` between frames.
- *
- * Codex P2 (PR #732): unlike a plain `setTimeout` wrapper, this
- * variant REJECTS with `AbortError` when `signal` fires (or is
- * already aborted on entry). That gives callers a way to
- * *distinguish* timer-expiry from signal-driven early exit, instead
- * of silently resolving on both. The replay loop catches the
- * `AbortError` and exits cleanly so Ctrl-C does not have to wait for
- * the current inter-frame `setTimeout` (capped at 60s) to elapse.
- *
- * Resolves only on timer expiry. Rejects with `AbortError` (DOMException-
- * shaped: `name === "AbortError"`) on abort. Exported so callers in
- * tests and adjacent modules can reuse the same primitive.
+ * Abortable sleep used by `replayTrace` between frames: resolves on timer
+ * expiry, rejects with `AbortError` on abort so Ctrl-C exits without waiting
+ * out the inter-frame delay. Shared implementation lives in utils/sleep.js.
  */
-export function sleepAbortable(
-  ms: number,
-  signal?: AbortSignal,
-): Promise<void> {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(makeAbortError());
-      return;
-    }
-    const timer = setTimeout(() => {
-      if (signal && onAbort) signal.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    let onAbort: (() => void) | null = null;
-    if (signal) {
-      onAbort = () => {
-        clearTimeout(timer);
-        reject(makeAbortError());
-      };
-      signal.addEventListener("abort", onAbort, { once: true });
-    }
-  });
-}
+export { sleepAbortable };
 
 /**
  * Construct an `AbortError`-shaped error. Prefers the standard

package/src/converge-config.ts

@@ -1,3 +1,9 @@
+import {
+  type CaptureWriteLockBackoffLimits,
+  normalizeCaptureWriteLockWaitMs,
+  resolveCaptureWriteLockBackoffLimits,
+} from "./capture-write-lock-backoff.js";
+import { readEnvVar } from "./runtime/env.js";
 import type { ConvergeConfig, ConvergeConflictPolicy } from "./types.js";
 
 export const CONVERGE_CONFLICT_POLICIES = [
@@ -38,6 +44,46 @@ function parsePeerRequestTimeoutMs(value: unknown, label: string): number {
   return normalizeConvergePeerRequestTimeoutMs(value, label);
 }
 
+function parseOptionalCaptureLockMs(value: unknown, label: string): number | undefined {
+  if (value === undefined) return undefined;
+  return normalizeCaptureWriteLockWaitMs(value, label);
+}
+
+/**
+ * Config values win over env. An omitted knob stays omitted here so the
+ * caller can still fall through to the built-in default. Env is read with
+ * the REMNIC_ name and the legacy ENGRAM_ name.
+ */
+function envCaptureLockMs(name: string): number | undefined {
+  const raw = readEnvVar(name);
+  if (raw === undefined) return undefined;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return undefined;
+  if (trimmed.length > 15) {
+    throw new Error(`${name} must be a positive integer number of milliseconds; got ${JSON.stringify(raw)}`);
+  }
+  for (let index = 0; index < trimmed.length; index += 1) {
+    const code = trimmed.charCodeAt(index);
+    if (code < 48 || code > 57) {
+      throw new Error(`${name} must be a positive integer number of milliseconds; got ${JSON.stringify(raw)}`);
+    }
+  }
+  return normalizeCaptureWriteLockWaitMs(Number(trimmed), name);
+}
+
+export function resolveConvergeCaptureWriteLockBackoff(
+  config: ConvergeConfig | undefined
+): CaptureWriteLockBackoffLimits {
+  return resolveCaptureWriteLockBackoffLimits({
+    captureWriteLockInitialDelayMs:
+      config?.captureWriteLockInitialDelayMs ?? envCaptureLockMs("REMNIC_CONVERGE_CAPTURE_LOCK_INITIAL_DELAY_MS"),
+    captureWriteLockMaxDelayMs:
+      config?.captureWriteLockMaxDelayMs ?? envCaptureLockMs("REMNIC_CONVERGE_CAPTURE_LOCK_MAX_DELAY_MS"),
+    captureWriteLockDeadlineMs:
+      config?.captureWriteLockDeadlineMs ?? envCaptureLockMs("REMNIC_CONVERGE_CAPTURE_LOCK_DEADLINE_MS"),
+  });
+}
+
 export function parseConvergeConfig(block: unknown): ConvergeConfig {
   if (block === undefined) {
     return { conflictPolicy: DEFAULT_CONVERGE_CONFLICT_POLICY };
@@ -49,7 +95,14 @@ export function parseConvergeConfig(block: unknown): ConvergeConfig {
   if (prototype !== Object.prototype && prototype !== null) {
     throw new Error("converge must be a plain object");
   }
-  const { conflictPolicy: rawConflictPolicy, peerRequestTimeoutMs, ...unknown } = block as Record<string, unknown>;
+  const {
+    conflictPolicy: rawConflictPolicy,
+    peerRequestTimeoutMs,
+    captureWriteLockInitialDelayMs,
+    captureWriteLockMaxDelayMs,
+    captureWriteLockDeadlineMs,
+    ...unknown
+  } = block as Record<string, unknown>;
   let conflictPolicy: unknown = rawConflictPolicy;
   const unknownKey = Object.keys(unknown)[0];
   if (unknownKey !== undefined) {
@@ -62,11 +115,37 @@ export function parseConvergeConfig(block: unknown): ConvergeConfig {
     typeof conflictPolicy === "string" &&
     CONVERGE_CONFLICT_POLICIES.includes(conflictPolicy as ConvergeConflictPolicy)
   ) {
+    const initialDelayMs = parseOptionalCaptureLockMs(
+      captureWriteLockInitialDelayMs,
+      "converge.captureWriteLockInitialDelayMs"
+    );
+    const maxDelayMs = parseOptionalCaptureLockMs(captureWriteLockMaxDelayMs, "converge.captureWriteLockMaxDelayMs");
+    const deadlineMs = parseOptionalCaptureLockMs(captureWriteLockDeadlineMs, "converge.captureWriteLockDeadlineMs");
+    // Reject an inverted schedule at parse time. Omitted knobs stay omitted
+    // and are filled from defaults only when the acquire runs.
+    if (initialDelayMs !== undefined && maxDelayMs !== undefined && initialDelayMs > maxDelayMs) {
+      throw new Error(
+        `converge.captureWriteLockInitialDelayMs (${initialDelayMs}) must be <= converge.captureWriteLockMaxDelayMs (${maxDelayMs})`
+      );
+    }
+    if (maxDelayMs !== undefined && deadlineMs !== undefined && maxDelayMs > deadlineMs) {
+      throw new Error(
+        `converge.captureWriteLockMaxDelayMs (${maxDelayMs}) must be <= converge.captureWriteLockDeadlineMs (${deadlineMs})`
+      );
+    }
+    if (initialDelayMs !== undefined && deadlineMs !== undefined && initialDelayMs > deadlineMs) {
+      throw new Error(
+        `converge.captureWriteLockInitialDelayMs (${initialDelayMs}) must be <= converge.captureWriteLockDeadlineMs (${deadlineMs})`
+      );
+    }
     return {
       conflictPolicy: conflictPolicy as ConvergeConflictPolicy,
       ...(peerRequestTimeoutMs !== undefined
         ? { peerRequestTimeoutMs: parsePeerRequestTimeoutMs(peerRequestTimeoutMs, "converge.peerRequestTimeoutMs") }
         : {}),
+      ...(initialDelayMs !== undefined ? { captureWriteLockInitialDelayMs: initialDelayMs } : {}),
+      ...(maxDelayMs !== undefined ? { captureWriteLockMaxDelayMs: maxDelayMs } : {}),
+      ...(deadlineMs !== undefined ? { captureWriteLockDeadlineMs: deadlineMs } : {}),
     };
   }