fix(agent): defer finalized receiver SWM cleanup to idle GC

packages/agent/src/dkg-agent-base.ts

@@ -159,6 +159,8 @@ import {
   type SignedAgentDelegation,
 } from './auth/agent-delegation.js';
 import { SyncVerifyWorker } from './sync-verify-worker.js';
+import type { FinalizedSwmCleanupWorker } from './finalized-swm-cleanup-worker.js';
+import type { FinalizedSwmCleanupService } from './finalized-swm-cleanup-service.js';
 import { bindRandomSampling, type RandomSamplingDisabledReason, type RandomSamplingHandle, type RandomSamplingStatus } from './random-sampling-bind.js';
 import { connectToMultiaddr, ensurePeerConnected as ensurePeerConnectedAtom, primeCatchupConnections as primeCatchupConnectionsAtom } from './p2p/peer-connect.js';
 import { Messenger, type SloProtocolStats } from './p2p/messenger.js';
@@ -879,6 +881,24 @@ export class DKGAgentBase {
    */
   static readonly SWM_ACK_QUORUM_TICK_MS = 5_000;
 
+  /**
+   * Finalized-SWM GC slice budgets. The sweep yields once either is spent and
+   * resumes at the next context graph in its rotation, so these trade cleanup
+   * latency against how long one background slice may hold store capacity.
+   * Env-overridable for ops tuning; the service clamps candidates to 16.
+   */
+  static readonly FINALIZED_SWM_CLEANUP_MAX_CANDIDATES =
+    Math.max(1, Number(process.env['DKG_FINALIZED_SWM_CLEANUP_MAX_CANDIDATES']) || 4);
+  static readonly FINALIZED_SWM_CLEANUP_BUDGET_MS =
+    Math.max(1, Number(process.env['DKG_FINALIZED_SWM_CLEANUP_BUDGET_MS']) || 10_000);
+  /**
+   * Delay before re-waking the GC after a sweep yielded on pressure or budget,
+   * or drained part of a known backlog. This is the cadence that actually fires
+   * while the node is draining, so it is the knob ops reach for first.
+   */
+  static readonly FINALIZED_SWM_CLEANUP_RETRY_MS =
+    Math.max(1, Number(process.env['DKG_FINALIZED_SWM_CLEANUP_RETRY_MS']) || 5_000);
+
   /**
    * Phase B — chain-driven VM reconciliation sweep cadence. The periodic sweep
    * is the safety net behind the live `KnowledgeAssetRegisteredToContextGraph`
@@ -964,6 +984,9 @@ export class DKGAgentBase {
   protected messageHandler: MessageHandler | null = null;
   protected chainPoller: ChainEventPoller | null = null;
   protected swmCleanupTimer: ReturnType<typeof setInterval> | null = null;
+  protected finalizedSwmCleanupTimer: ReturnType<typeof setInterval> | null = null;
+  protected finalizedSwmCleanupWorker?: FinalizedSwmCleanupWorker;
+  protected finalizedSwmCleanupService?: FinalizedSwmCleanupService;
   /** Phase B — periodic chain-driven VM reconciliation sweep timer. */
   protected vmReconcileTimer: ReturnType<typeof setInterval> | null = null;
   /** Phase B — unified per-CG coalescing and node-wide admission policy. */

packages/agent/src/dkg-agent-constants.ts

@@ -134,6 +134,14 @@ export const SYNC_MIN_GRAPH_BUDGET_MS = 10_000;
 export const DEBUG_SYNC_PROGRESS = process.env.DKG_DEBUG_SYNC_PROGRESS === '1';
 export const DEFAULT_SWM_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
 export const SWM_CLEANUP_INTERVAL_MS = 15 * 60 * 1000; // run cleanup every 15 minutes
+export const FINALIZED_SWM_CLEANUP_ROOT_PREDICATE =
+  'http://dkg.io/ontology/finalizedSwmCleanupRoot';
+export const FINALIZED_SWM_CLEANUP_TASK_TYPE =
+  'http://dkg.io/ontology/FinalizedSwmCleanupTask';
+export const FINALIZED_SWM_CLEANUP_MARKED_AT_PREDICATE =
+  'http://dkg.io/ontology/finalizedSwmCleanupMarkedAt';
+export const FINALIZED_SWM_CLEANUP_HEAD_FINGERPRINT_PREDICATE =
+  'http://dkg.io/ontology/finalizedSwmCleanupHeadFingerprint';
 export const SYNC_DENIED_RESPONSE = '__DKG_SYNC_DENIED__';
 
 // ── Gossip reconnect ──────────────────────────────────────────────────

packages/agent/src/dkg-agent-swm-substrate.ts

@@ -1654,6 +1654,11 @@ export class SwmSubstrateMethods extends DKGAgentBase {
           markContextGraphMetaDirtyFromQuads: (quads) => {
             this.contextGraphMetaProjection.markDirtyFromQuads(quads);
           },
+          // The SAME map catch-up and the finalized-SWM GC take, so the cleanup
+          // marker write serializes against them on the per-KA key.
+          writeLocks: this.writeLocks,
+          publicSnapshotStore: this.publicSnapshotStore,
+          wakeFinalizedSwmCleanup: () => this.wakeFinalizedSwmCleanup(),
           runtime: this.finalizationRuntime,
         },
       );

packages/agent/src/dkg-agent.ts

@@ -1642,6 +1642,15 @@ export class DKGAgent extends DKGAgentBase {
       clearInterval(this.swmCleanupTimer);
       this.swmCleanupTimer = null;
     }
+    if (this.finalizedSwmCleanupTimer) {
+      clearInterval(this.finalizedSwmCleanupTimer);
+      this.finalizedSwmCleanupTimer = null;
+    }
+    if (this.finalizedSwmCleanupWorker) {
+      await this.finalizedSwmCleanupWorker.close();
+      this.finalizedSwmCleanupWorker = undefined;
+    }
+    this.finalizedSwmCleanupService = undefined;
     if (this.hostModeReconcilerTimer) {
       clearInterval(this.hostModeReconcilerTimer);
       this.hostModeReconcilerTimer = null;