@remnic/core 9.3.718 → 9.3.720

package/src/lifecycle/tombstones.ts

@@ -40,7 +40,7 @@
 //   - Semantic tier (4) ships dark, off by default (rule 48).
 // ---------------------------------------------------------------------------
 
-import { serializeMutations } from "../utils/serialize-mutations.js";
+import { serializeMutations, withHeldFileLock } from "../utils/serialize-mutations.js";
 
 /** Why a tombstone was emitted. */
 export type TombstoneReason =
@@ -129,6 +129,20 @@ export interface TombstoneStoreOptions {
    * skipped entirely.
    */
   semanticSimilarity?: (a: string, b: string) => number;
+  /**
+   * Cross-process write-lock timings for the tombstone JSONL mutation lock
+   * (issue #1639). The secure-store append is a read-merge-write (read
+   * encrypted → decrypt → concat → re-encrypt → atomic rename), so two
+   * Remnic processes appending concurrently can each read the same contents
+   * and the last writer drops the other's entry — breaking the
+   * non-resurrection invariant. The lock serializes the mutation across
+   * processes. When omitted, defaults that fit the short tombstone critical
+   * section (mirroring the summary-snapshot lock): staleMs 30s, maxWaitMs 5s,
+   * heartbeatMs floor(staleMs/3).
+   */
+  readonly lockStaleMs?: number;
+  readonly lockMaxWaitMs?: number;
+  readonly lockHeartbeatMs?: number;
 }
 
 /** Injected file I/O — the StorageManager wires its secure-store-aware
@@ -261,7 +275,33 @@ export class TombstoneStore {
     private readonly namespace: string,
     private readonly options: TombstoneStoreOptions,
     private readonly io: TombstoneFileIo,
-  ) {}
+  ) {
+    this.lockStaleMs = this.options.lockStaleMs ?? 30_000;
+    this.lockMaxWaitMs = this.options.lockMaxWaitMs ?? 5_000;
+    this.lockHeartbeatMs =
+      this.options.lockHeartbeatMs ?? Math.max(100, Math.floor(this.lockStaleMs / 3));
+  }
+
+  /**
+   * Resolved cross-process write-lock timings (issue #1639). Defaults mirror
+   * the summary-snapshot lock: a tombstone append critical section is
+   * sub-second, so a stale lock older than 30s is a crashed holder; bounded
+   * acquisition gives up after 5s and strict-fails rather than clobbering a
+   * concurrent writer (which would reintroduce the lost-write race this lock
+   * closes).
+   */
+  private readonly lockStaleMs: number;
+  private readonly lockMaxWaitMs: number;
+  private readonly lockHeartbeatMs: number;
+
+  /**
+   * Sibling advisory lockfile: `<tombstones>.jsonl` → `<tombstones>.lock`.
+   * Shared by append, revoke, and rebuild so every JSONL mutation serializes
+   * against the others across processes (issue #1639: "shared with rebuilds").
+   */
+  private get lockPath(): string {
+    return this.filePath.replace(/\.jsonl$/i, "") + ".lock";
+  }
 
   /** Lazy load + build the in-memory index. Idempotent. */
   async load(): Promise<void> {
@@ -473,10 +513,48 @@ export class TombstoneStore {
 
   private serializeAppend(entry: TombstoneEntry): Promise<void> {
     const line = JSON.stringify(entry) + "\n";
-    // serializeMutations recovers after rejection (rule 40): a failed append
-    // surfaces to THIS caller but the next append is not poisoned.
+    // serializeMutations (in-process, rule 40 rejection recovery) wraps the
+    // cross-process lock: within one process appends are queued, and across
+    // processes the advisory lockfile serializes the read-merge-write so two
+    // Remnic processes appending concurrently cannot drop each other's entry
+    // (issue #1639). Under the lock we re-sync the in-memory index against
+    // disk first, so indexEntry builds on the peer's just-appended entries.
     return serializeMutations(`tombstone:${this.filePath}`, () =>
-      this.io.append(this.filePath, line),
+      this.withWriteLock(async () => {
+        await this.ensureFreshAgainstDisk();
+        await this.io.append(this.filePath, line);
+      }),
+    );
+  }
+
+  /**
+   * Acquire the cross-process tombstone write lock and run `task` under it
+   * (issue #1639). Strict-fail on acquisition timeout: the secure-store append
+   * is a read-merge-write, so a best-effort unlocked run would clobber a
+   * concurrent writer — reintroducing the lost-write race this lock closes.
+   * The thrown error surfaces to the caller (rule 34: never silently drop);
+   * rebuild recovers the tombstone on the next maintenance cycle.
+   *
+   * In-process callers are already serialized by serializeMutations (one key
+   * for append/revoke/rebuild), so this lock only contends across processes —
+   * the single-process daemon (default deployment) acquires it immediately.
+   */
+  private withWriteLock<T>(task: () => Promise<T>): Promise<T> {
+    return withHeldFileLock(
+      this.lockPath,
+      {
+        staleMs: this.lockStaleMs,
+        maxWaitMs: this.lockMaxWaitMs,
+        heartbeatMs: this.lockHeartbeatMs,
+      },
+      async (acquired) => {
+        if (!acquired) {
+          throw new Error(
+            "could not acquire tombstone write lock (contention timeout or filesystem error)",
+          );
+        }
+        return task();
+      },
     );
   }
 
@@ -595,72 +673,81 @@ export class TombstoneStore {
    * Returns the count of tombstone entries written.
    */
   async rebuild(retiredMemories: ReadonlyArray<RetiredMemoryRecord>): Promise<number> {
-    // Preserve existing revocations (all namespaces — ids are globally
-    // unique) so a rebuild does not silently un-revoke.
-    const existingRevocations = this.entries.filter((e) => e.kind === "revocation");
-    // Preserve tombstone entries from OTHER namespaces when the backing file
-    // is shared (issue #1579 thread Oc2MJ). rebuild rewrites the entire file;
-    // without preserving foreign entries, rebuilding namespace A would
-    // silently delete namespace B's tombstones, allowing resurrection in B.
-    const foreignTombstones = this.entries.filter(
-      (e) => e.kind === "tombstone" && e.namespace !== this.namespace,
-    );
-    // Reuse existing tombstone ids for source-equivalent entries so a prior
-    // revocation (which references the tombstone id) survives rebuild — minting
-    // fresh ids would orphan the revocation and silently un-revoke the content.
-    // Issue #1579 thread Oci-T: key the reuse map by (sourceMemoryId,
-    // supersessionKey), not just sourceMemoryId. A retired fact with multiple
-    // structured-attribute keys emits one record per key (see
-    // collectRetiredMemoriesForRebuild); keying only by sourceMemoryId made
-    // every rebuilt record share one id, so a revocation of key A silently
-    // revoked key B (over-revoke) — or, if a prior single-key tombstone was
-    // revoked, the new multi-key records all inherited a revoked id and
-    // silently un-blocked (orphan). Including the supersession-key
-    // discriminator keeps each keyed tombstone's id (and thus its revocation)
-    // independent. Records without a supersession key fall back to a stable
-    // empty-string discriminator so they still reuse by sourceMemoryId alone.
-    const existingBySource = new Map<string, string>();
-    for (const e of this.entries) {
-      if (e.kind === "tombstone") {
-        existingBySource.set(`${e.sourceMemoryId}\u{0000}${e.supersessionKey ?? ""}`, e.id);
-      }
-    }
-    const rebuilt: TombstoneEntry[] = retiredMemories.map((m) => ({
-      id:
-        existingBySource.get(`${m.memoryId}\u{0000}${m.supersessionKey ?? ""}`) ??
-        newTombstoneId(),
-      kind: "tombstone" as const,
-      reason: m.reason,
-      sourceMemoryId: m.memoryId,
-      contentHash: m.contentHash ?? this.options.hashContent(m.rawContent),
-      normalizedText: this.options.normalizeText(m.rawContent),
-      ...(m.entityRef ? { entityRef: m.entityRef } : {}),
-      ...(m.supersessionKey ? { supersessionKey: m.supersessionKey } : {}),
-      namespace: this.namespace,
-      createdAt: m.createdAt,
-      createdBy: m.createdBy,
-    }));
-    // Sort deterministically (rule 38): createdAt, then id for stability.
-    rebuilt.sort((a, b) =>
-      a.createdAt === b.createdAt
-        ? a.id < b.id ? -1 : a.id > b.id ? 1 : 0
-        : a.createdAt < b.createdAt ? -1 : 1,
-    );
-    const all = [...rebuilt, ...existingRevocations, ...foreignTombstones].sort((a, b) =>
-      a.createdAt === b.createdAt
-        ? a.id < b.id ? -1 : a.id > b.id ? 1 : 0
-        : a.createdAt < b.createdAt ? -1 : 1,
-    );
-    const serialized = all.map((e) => JSON.stringify(e)).join("\n") + (all.length > 0 ? "\n" : "");
-    await serializeMutations(`tombstone-rebuild:${this.filePath}`, () =>
-      this.io.write(this.filePath, serialized),
+    // The full read-merge-write runs UNDER the cross-process lock (issue #1639,
+    // cursor/codex review): we ensureFreshAgainstDisk() first so the in-memory
+    // index reflects any peer append/revoke that landed while we waited for the
+    // lock, THEN compute the payload. Rebuild rewrites the entire JSONL, so a
+    // payload built from a stale this.entries would overwrite a peer's just-
+    // written entry and resurrect a retired fact — the exact invariant this
+    // store exists to enforce. serializeMutations (in-process) wraps the
+    // cross-process lock; the key is unified with append/revoke so they cannot
+    // interleave in-process either.
+    const rebuiltCount = await serializeMutations(`tombstone:${this.filePath}`, () =>
+      this.withWriteLock(async () => {
+        await this.ensureFreshAgainstDisk();
+        // Preserve existing revocations (all namespaces — ids are globally
+        // unique) so a rebuild does not silently un-revoke.
+        const existingRevocations = this.entries.filter((e) => e.kind === "revocation");
+        // Preserve tombstone entries from OTHER namespaces when the backing
+        // file is shared (issue #1579 thread Oc2MJ). rebuild rewrites the
+        // entire file; without preserving foreign entries, rebuilding
+        // namespace A would silently delete namespace B's tombstones, allowing
+        // resurrection in B.
+        const foreignTombstones = this.entries.filter(
+          (e) => e.kind === "tombstone" && e.namespace !== this.namespace,
+        );
+        // Reuse existing tombstone ids for source-equivalent entries so a prior
+        // revocation (which references the tombstone id) survives rebuild —
+        // minting fresh ids would orphan the revocation and silently un-revoke.
+        // Issue #1579 thread Oci-T: key the reuse map by (sourceMemoryId,
+        // supersessionKey). See the append path above for the full rationale.
+        const existingBySource = new Map<string, string>();
+        for (const e of this.entries) {
+          if (e.kind === "tombstone") {
+            existingBySource.set(`${e.sourceMemoryId}\u{0000}${e.supersessionKey ?? ""}`, e.id);
+          }
+        }
+        const rebuilt: TombstoneEntry[] = retiredMemories.map((m) => ({
+          id:
+            existingBySource.get(`${m.memoryId}\u{0000}${m.supersessionKey ?? ""}`) ??
+            newTombstoneId(),
+          kind: "tombstone" as const,
+          reason: m.reason,
+          sourceMemoryId: m.memoryId,
+          contentHash: m.contentHash ?? this.options.hashContent(m.rawContent),
+          normalizedText: this.options.normalizeText(m.rawContent),
+          ...(m.entityRef ? { entityRef: m.entityRef } : {}),
+          ...(m.supersessionKey ? { supersessionKey: m.supersessionKey } : {}),
+          namespace: this.namespace,
+          createdAt: m.createdAt,
+          createdBy: m.createdBy,
+        }));
+        // Sort deterministically (rule 38): createdAt, then id for stability.
+        rebuilt.sort((a, b) =>
+          a.createdAt === b.createdAt
+            ? a.id < b.id ? -1 : a.id > b.id ? 1 : 0
+            : a.createdAt < b.createdAt ? -1 : 1,
+        );
+        const all = [...rebuilt, ...existingRevocations, ...foreignTombstones].sort((a, b) =>
+          a.createdAt === b.createdAt
+            ? a.id < b.id ? -1 : a.id > b.id ? 1 : 0
+            : a.createdAt < b.createdAt ? -1 : 1,
+        );
+        const serialized =
+          all.map((e) => JSON.stringify(e)).join("\n") + (all.length > 0 ? "\n" : "");
+        await this.io.write(this.filePath, serialized);
+        // Update the in-memory index under the same lock so it stays consistent
+        // with the file we just wrote (no window for a lookup to see a stale
+        // index that misses a just-rebuilt entry).
+        this.resetIndex();
+        for (const entry of all) this.indexEntry(entry);
+        this.corruptedLines = 0;
+        this.loaded = true;
+        this.markWritten();
+        return rebuilt.length;
+      }),
     );
-    this.resetIndex();
-    for (const entry of all) this.indexEntry(entry);
-    this.corruptedLines = 0;
-    this.loaded = true;
-    this.markWritten();
-    return rebuilt.length;
+    return rebuiltCount;
   }
 }
 

package/src/operator-toolkit.ts

@@ -24,6 +24,11 @@ import {
   type EvalHarnessStatus,
 } from "./evals.js";
 import { analyzeGraphHealth, type GraphHealthReport } from "./graph.js";
+import {
+  resolveAccessSetupCapabilities,
+  resolveCapabilities,
+  resolveGraphConstructionCapabilities,
+} from "./capabilities.js";
 import {
   analyzeSessionIntegrity,
   applySessionRepair,
@@ -412,7 +417,12 @@ export interface BenchmarkRecallOptions {
 export interface OperatorRepairOptions {
   config: Pick<
     PluginConfig,
-    "memoryDir" | "entityGraphEnabled" | "timeGraphEnabled" | "causalGraphEnabled"
+    | "memoryDir"
+    | "entityGraphEnabled"
+    | "timeGraphEnabled"
+    | "causalGraphEnabled"
+    | "multiGraphMemoryEnabled"
+    | "graphWriteSessionAdjacencyEnabled"
   >;
   apply?: boolean;
   dryRun?: boolean;
@@ -904,6 +914,9 @@ async function buildOperatorConfigReviewReport(input: {
   config: PluginConfig;
 }): Promise<OperatorConfigReviewReport> {
   const { now, configStatus, config } = input;
+  // Resolve recall-operation gates once so this diagnostic reads capabilities,
+  // not scattered config flags (#1566 Cluster C — rerank is a mixed-op flag).
+  const caps = resolveCapabilities(config);
   const findings: OperatorConfigReviewFinding[] = [];
   const searchBackend = config.searchBackend ?? "qmd";
   const workspaceBootstrapFiles = [
@@ -920,7 +933,7 @@ async function buildOperatorConfigReviewReport(input: {
     config.memoryOsPreset !== "local-llm-heavy" &&
     config.queryAwareIndexingEnabled === false &&
     config.verbatimArtifactsEnabled === false &&
-    config.rerankEnabled === false
+    !caps.rerank
   ) {
     findings.push(buildConfigReviewFinding({
       key: "balanced_preset",
@@ -1855,8 +1868,10 @@ function summarizeSecurityMitigations(
     | "recallAuditAnomalyRapidFireLimit"
   >,
 ): OperatorDoctorCheck {
-  const budgetEnabled = config.recallCrossNamespaceBudgetEnabled === true;
-  const anomalyEnabled = config.recallAuditAnomalyDetectionEnabled === true;
+  // Resolve access-setup gates once (#1566 Cluster B).
+  const accessCaps = resolveAccessSetupCapabilities(config);
+  const budgetEnabled = accessCaps.recallCrossNamespaceBudget;
+  const anomalyEnabled = accessCaps.recallAuditAnomalyDetection;
 
   if (!budgetEnabled && !anomalyEnabled) {
     return {
@@ -2338,10 +2353,12 @@ export async function runOperatorRepair(options: OperatorRepairOptions): Promise
   const sessionRepairApply = await applySessionRepair({
     plan: sessionRepairPlan,
   });
+  // Resolve graph-construction gates once for this diagnostic (#1566 Cluster A).
+  const graphCaps = resolveGraphConstructionCapabilities(options.config);
   const graphHealth = await analyzeGraphHealth(options.config.memoryDir, {
-    entityGraphEnabled: options.config.entityGraphEnabled,
-    timeGraphEnabled: options.config.timeGraphEnabled,
-    causalGraphEnabled: options.config.causalGraphEnabled,
+    entityGraphEnabled: graphCaps.entityGraph,
+    timeGraphEnabled: graphCaps.timeGraph,
+    causalGraphEnabled: graphCaps.causalGraph,
     includeRepairGuidance: true,
   });
   return {

package/src/orchestration/tier-migration-coordinator.ts

@@ -0,0 +1,286 @@
+/**
+ * Tier migration coordinator — extracted from the orchestrator (issue #1526).
+ *
+ * Owns the hot/cold tier-migration lifecycle for a single cycle:
+ *   - gating (config flags, in-flight guard, min-interval throttle)
+ *   - budget selection (compounding override or config default)
+ *   - candidate scanning across hot + cold storage
+ *   - promotion/demotion execution via TierMigrationExecutor
+ *   - status recording through TierMigrationStatusStore
+ *
+ * The orchestrator constructs one instance and delegates the three public
+ * entrypoints (`runTierMigrationCycle`, `runTierMigrationNow`,
+ * `getTierMigrationStatus`) to it. Storage is passed per-call so extraction
+ * (which writes to a namespace-scoped storage) and maintenance/manual (which
+ * use the default storage) share one coordinator.
+ *
+ * Behavior-preserving move from orchestrator.ts. No logic changes — the
+ * orchestrator keeps thin delegating methods so existing call sites and
+ * tests that exercise the public API continue to work.
+ */
+
+import path from "node:path";
+
+// StorageManager type comes from the package barrel (type-only) so this
+// module does not add a direct storage.ts import (#1533 ratchet).
+import type { StorageManager } from "../index.js";
+import type { SearchBackend } from "../search/port.js";
+import { TierMigrationExecutor } from "../tier-migration.js";
+import { decideTierTransition, type MemoryTier } from "../tier-routing.js";
+import {
+  TierMigrationStatusStore,
+  type TierMigrationCycleSummary,
+  type TierMigrationStatusSnapshot,
+} from "../recall-state.js";
+import {
+  type CompoundingEngine,
+  defaultTierMigrationCycleBudget,
+} from "../compounding/engine.js";
+import {
+  applyUtilityPromotionRuntimePolicy,
+  type UtilityRuntimeValues,
+} from "../utility-runtime.js";
+import type { PluginConfig, MemoryFile } from "../types.js";
+import { log } from "../logger.js";
+
+/** Dependencies injected by the orchestrator. All stable references or live
+ *  accessors (the orchestrator reassigns `qmd` to NoopSearchBackend and
+ *  `utilityRuntimeValues` after async init, so those arrive as getters). */
+export interface TierMigrationCoordinatorDeps {
+  config: PluginConfig;
+  /** Live accessor — the orchestrator reassigns this.qmd to NoopSearchBackend
+   *  after construction when the collection is missing. */
+  getQmd: () => SearchBackend;
+  tierMigrationStatus: TierMigrationStatusStore;
+  /** Live accessor — loaded asynchronously during init, null before that. */
+  getUtilityRuntimeValues: () => UtilityRuntimeValues | null;
+  /** Live accessor — undefined when compounding is disabled. */
+  getCompounding: () => CompoundingEngine | undefined;
+  /** Constructs the cold-tier StorageManager for a given parent memory dir.
+   *  Injected so this module owns no direct storage.ts import (#1533). */
+  createColdStorage: (parentDir: string) => StorageManager;
+}
+
+/**
+ * Coordinates a single tier-migration cycle. Owns the in-flight guard and
+ * last-run timestamp that previously lived as private orchestrator fields.
+ */
+export class TierMigrationCoordinator {
+  private inFlight = false;
+  private lastRunAtMs = 0;
+
+  constructor(private readonly deps: TierMigrationCoordinatorDeps) {}
+
+  /** Whether a migration cycle is currently executing (diagnostics). */
+  isInFlight(): boolean {
+    return this.inFlight;
+  }
+
+  /** Latest status snapshot (delegates to the status store). */
+  getStatus(): TierMigrationStatusSnapshot {
+    return this.deps.tierMigrationStatus.get();
+  }
+
+  /**
+   * Run one tier-migration cycle. Behavior-preserving move of the
+   * orchestrator's former `runTierMigrationCycle`.
+   */
+  async runCycle(
+    storage: StorageManager,
+    trigger: "extraction" | "maintenance" | "manual",
+    options?: {
+      dryRun?: boolean;
+      limitOverride?: number;
+      force?: boolean;
+    },
+  ): Promise<TierMigrationCycleSummary> {
+    const { config, tierMigrationStatus } = this.deps;
+    const dryRun = options?.dryRun === true;
+    const persistSkipped = options?.force === true || trigger === "manual";
+    if (!config.qmdTierMigrationEnabled && options?.force !== true) {
+      const skipped: TierMigrationCycleSummary = {
+        trigger,
+        scanned: 0,
+        migrated: 0,
+        promoted: 0,
+        demoted: 0,
+        limit: 0,
+        dryRun,
+        skipped: "tier_migration_disabled",
+      };
+      if (persistSkipped) await tierMigrationStatus.recordCycle(skipped);
+      return skipped;
+    }
+    if (
+      trigger === "maintenance" &&
+      !config.qmdTierAutoBackfillEnabled &&
+      options?.force !== true
+    ) {
+      const skipped: TierMigrationCycleSummary = {
+        trigger,
+        scanned: 0,
+        migrated: 0,
+        promoted: 0,
+        demoted: 0,
+        limit: 0,
+        dryRun,
+        skipped: "maintenance_backfill_disabled",
+      };
+      if (persistSkipped) await tierMigrationStatus.recordCycle(skipped);
+      return skipped;
+    }
+    if (this.inFlight) {
+      const skipped: TierMigrationCycleSummary = {
+        trigger,
+        scanned: 0,
+        migrated: 0,
+        promoted: 0,
+        demoted: 0,
+        limit: 0,
+        dryRun,
+        skipped: "migration_in_flight",
+      };
+      if (persistSkipped) await tierMigrationStatus.recordCycle(skipped);
+      return skipped;
+    }
+
+    const budgetTrigger = trigger === "manual" ? "maintenance" : trigger;
+    const budget =
+      this.deps.getCompounding()?.tierMigrationCycleBudget(budgetTrigger) ??
+      defaultTierMigrationCycleBudget(config, budgetTrigger);
+    const limit =
+      options?.limitOverride !== undefined
+        ? Math.max(0, Math.floor(options.limitOverride))
+        : budget.limit;
+    const nowMs = Date.now();
+    if (
+      options?.force !== true &&
+      nowMs - this.lastRunAtMs < budget.minIntervalMs
+    ) {
+      const skipped: TierMigrationCycleSummary = {
+        trigger,
+        scanned: 0,
+        migrated: 0,
+        promoted: 0,
+        demoted: 0,
+        limit,
+        dryRun,
+        skipped: "min_interval",
+      };
+      if (persistSkipped) await tierMigrationStatus.recordCycle(skipped);
+      return skipped;
+    }
+
+    const policy = applyUtilityPromotionRuntimePolicy(
+      {
+        enabled: config.qmdTierMigrationEnabled,
+        demotionMinAgeDays: config.qmdTierDemotionMinAgeDays,
+        demotionValueThreshold: config.qmdTierDemotionValueThreshold,
+        promotionValueThreshold: config.qmdTierPromotionValueThreshold,
+      },
+      this.deps.getUtilityRuntimeValues(),
+    );
+
+    this.inFlight = true;
+    try {
+      const coldStorage = this.deps.createColdStorage(
+        path.join(storage.dir, "cold"),
+      );
+      const [hotMemories, coldMemories] = await Promise.all([
+        storage.readAllMemories(),
+        coldStorage.readAllMemories(),
+      ]);
+      const now = new Date();
+      const scanLimit = Math.max(0, Math.floor(budget.scanLimit));
+      const hotScanLimit = Math.min(
+        hotMemories.length,
+        Math.ceil(scanLimit * 0.75),
+      );
+      const coldScanLimit = Math.min(
+        coldMemories.length,
+        Math.max(0, scanLimit - hotScanLimit),
+      );
+      const toTimestamp = (memory: MemoryFile): number =>
+        Date.parse(memory.frontmatter.updated ?? memory.frontmatter.created);
+      const hotCandidates = hotMemories
+        .map((memory) => ({ memory, tier: "hot" as MemoryTier }))
+        .sort((a, b) => toTimestamp(a.memory) - toTimestamp(b.memory))
+        .slice(0, hotScanLimit);
+      const coldCandidates = coldMemories
+        .map((memory) => ({ memory, tier: "cold" as MemoryTier }))
+        .sort((a, b) => toTimestamp(b.memory) - toTimestamp(a.memory))
+        .slice(0, coldScanLimit);
+      const candidates = [...hotCandidates, ...coldCandidates];
+
+      const migration = new TierMigrationExecutor({
+        storage,
+        qmd: this.deps.getQmd(),
+        hotCollection: config.qmdCollection,
+        coldCollection:
+          config.qmdColdCollection ?? `${config.qmdCollection}-cold`,
+        autoEmbed: config.qmdAutoEmbedEnabled,
+      });
+
+      let migrated = 0;
+      let promoted = 0;
+      let demoted = 0;
+      for (const candidate of candidates) {
+        if (migrated >= limit) break;
+        const decision = decideTierTransition(
+          candidate.memory,
+          candidate.tier,
+          policy,
+          now,
+        );
+        if (!decision.changed) continue;
+
+        if (!dryRun) {
+          const res = await migration.migrateMemory({
+            memory: candidate.memory,
+            fromTier: candidate.tier,
+            toTier: decision.nextTier,
+            reason: `${trigger}:${decision.reason}`,
+          });
+          if (!res.changed) continue;
+        }
+        migrated += 1;
+        if (decision.nextTier === "cold") demoted += 1;
+        if (decision.nextTier === "hot") promoted += 1;
+      }
+
+      if (!dryRun) this.lastRunAtMs = Date.now();
+      log.debug(
+        `tier migration cycle completed: trigger=${trigger} scanned=${candidates.length} migrated=${migrated} limit=${limit}${dryRun ? " dryRun=true" : ""}`,
+      );
+      const summary: TierMigrationCycleSummary = {
+        trigger,
+        scanned: candidates.length,
+        migrated,
+        promoted,
+        demoted,
+        limit,
+        dryRun,
+      };
+      const shouldPersistCycle = trigger === "manual" || migrated > 0;
+      if (shouldPersistCycle) await tierMigrationStatus.recordCycle(summary);
+      return summary;
+    } catch (err) {
+      this.lastRunAtMs = Date.now();
+      log.warn(`tier migration cycle failed (${trigger}, fail-open): ${err}`);
+      const failed: TierMigrationCycleSummary = {
+        trigger,
+        scanned: 0,
+        migrated: 0,
+        promoted: 0,
+        demoted: 0,
+        limit,
+        dryRun,
+        errorCount: 1,
+      };
+      await tierMigrationStatus.recordCycle(failed);
+      return failed;
+    } finally {
+      this.inFlight = false;
+    }
+  }
+}