openclaw-hybrid-memory 2026.5.310 → 2026.6.10

package/cli/commands/manage/register-reflection-pipeline.ts

@@ -2,28 +2,34 @@
  * reflection & dream-cycle commands — split from register-corrections-and-pipeline.ts.
  */
 import { readFileSync, writeFileSync } from "node:fs";
+import type {
+  ContradictionReviewDecision,
+  ContradictionReviewItem,
+} from "../../../backends/facts-db/contradictions.js";
+import { PROJECT_STATE_LWW_KEYS } from "../../../backends/facts-db/contradictions.js";
 import { getCronModelConfig, getDefaultCronModel } from "../../../config.js";
 import { capturePluginError } from "../../../services/error-reporter.js";
-import { cleanupImplicitFeedbackDuplicates, type ExtractImplicitFeedbackProgressSnapshot } from "../../cmd-feedback.js";
 import { getEffectivenessReport, runClosedLoopAnalysis } from "../../../services/feedback-effectiveness.js";
+import {
+  cleanupImplicitFeedbackDuplicates,
+  type ExtractImplicitFeedbackProgressSnapshot,
+  implicitFeedbackCollapseStatus,
+} from "../../cmd-feedback.js";
 import { type CommanderOptsParent, readHybridMemVerbose } from "../../global-verbose.js";
 import { type Chainable, withExit } from "../../shared.js";
 import type { ManageBindings } from "./bindings.js";
-import { PROJECT_STATE_LWW_KEYS } from "../../../backends/facts-db/contradictions.js";
-import type {
-  ContradictionReviewDecision,
-  ContradictionReviewItem,
-} from "../../../backends/facts-db/contradictions.js";
 
 import {
   assessContinuousVerificationResult,
   formatContinuousVerificationAssessmentLine,
   formatExtractImplicitFeedbackProgress,
-  runVerboseFollowUp,
   type RunVerboseFollowUpOptions,
+  runVerboseFollowUp,
 } from "./dream-cycle-followup.js";
 import { runMaintenanceHeartbeat } from "./maintenance-heartbeat.js";
 
+const CONTRADICTION_BUCKET_PREVIEW_TARGET_RATE = 0.8;
+
 function writeContradictionReviewFile(outputPath: string, items: ContradictionReviewItem[]): void {
   const content = `${items.map((item) => JSON.stringify(item)).join("\n")}${items.length > 0 ? "\n" : ""}`;
   writeFileSync(outputPath, content, "utf-8");
@@ -441,9 +447,19 @@ export function registerManageReflectionPipeline(mem: Chainable, b: ManageBindin
                   `stage=scan; batches=${batches}; scanned=${scanned}; collapsed=${collapsed}; includeLegacy=${opts?.includeLegacy === true ? "yes" : "no"}`,
               },
             );
+            const collapseStatus = implicitFeedbackCollapseStatus(scanned, collapsed);
             console.log(
-              `Implicit-feedback collapse complete: scanned ${scanned}, collapsed ${collapsed} ${dryRun ? "(dry-run)" : ""}`,
+              `Implicit-feedback collapse summary: scanned ${scanned}, collapsed ${collapsed}, status=${collapseStatus} ${dryRun ? "(dry-run)" : ""}`,
             );
+            if (!dryRun && collapseStatus === "no_candidates") {
+              console.log(
+                "No implicit-feedback rows matched the collapse scan window. Verify source='implicit-feedback' rows exist and rerun with a wider scan limit.",
+              );
+            } else if (!dryRun && collapseStatus === "no_changes") {
+              console.log(
+                "No near-duplicate rows met the current threshold. Consider `--include-legacy` and/or a lower `--threshold`, then rerun audit health to verify bloat reduction.",
+              );
+            }
             return;
           }
           let res;
@@ -1142,6 +1158,56 @@ export function registerManageReflectionPipeline(mem: Chainable, b: ManageBindin
             }
           }
           if (res.ambiguous.length > 0) {
+            let unresolvedBuckets: {
+              safeDeterministic: number;
+              possibleEntityReuse: number;
+              olderVerified: number;
+              humanRequired: number;
+              otherManual: number;
+            } | null = null;
+            try {
+              const preview = await ctx.runResolveContradictionsAuto({
+                dryRun: true,
+                targetRate: CONTRADICTION_BUCKET_PREVIEW_TARGET_RATE,
+              });
+              let possibleEntityReuse = 0;
+              let olderVerified = 0;
+              let humanRequired = 0;
+              let otherManual = 0;
+              for (const item of preview.reviewItems) {
+                if (item.possibleOverloadedEntity) {
+                  possibleEntityReuse++;
+                  continue;
+                }
+                const reason = item.suggestedReason.toLowerCase();
+                if (reason.includes("older fact is verified")) {
+                  olderVerified++;
+                  continue;
+                }
+                if (reason.includes("no safe deterministic resolution matched")) {
+                  humanRequired++;
+                  continue;
+                }
+                otherManual++;
+              }
+              unresolvedBuckets = {
+                safeDeterministic: preview.deterministic,
+                possibleEntityReuse,
+                olderVerified,
+                humanRequired,
+                otherManual,
+              };
+            } catch (err) {
+              capturePluginError(err instanceof Error ? err : new Error(String(err)), {
+                subsystem: "cli",
+                operation: "resolve-contradictions-bucket-preview",
+              });
+              const message = err instanceof Error ? err.message : String(err);
+              console.error(
+                `Warning: could not generate unresolved_by_reason bucket preview (${message}). Check database state and rerun if needed.`,
+              );
+            }
+
             const trunc = (s: string | null | undefined, n: number): string => {
               if (s == null || s === "") return "(empty)";
               const t = s.replace(/\s+/g, " ").trim();
@@ -1175,6 +1241,16 @@ export function registerManageReflectionPipeline(mem: Chainable, b: ManageBindin
             if (!verbose && !details && res.ambiguous.length > 10) {
               console.log(`  ...and ${res.ambiguous.length - 10} more`);
             }
+            if (unresolvedBuckets) {
+              console.log("unresolved_by_reason:");
+              console.log(`  safe_deterministic_auto=${unresolvedBuckets.safeDeterministic}`);
+              console.log(`  possible_entity_reuse=${unresolvedBuckets.possibleEntityReuse}`);
+              console.log(`  older_verified=${unresolvedBuckets.olderVerified}`);
+              console.log(`  human_required=${unresolvedBuckets.humanRequired}`);
+              if (unresolvedBuckets.otherManual > 0) {
+                console.log(`  other_manual=${unresolvedBuckets.otherManual}`);
+              }
+            }
             console.log("");
             console.log(
               "What this means: each line is two stored facts with the same entity and key but different values. " +
@@ -1191,6 +1267,37 @@ export function registerManageReflectionPipeline(mem: Chainable, b: ManageBindin
             if (!details) {
               console.log("  3. Easier scan: openclaw hybrid-mem resolve-contradictions --details");
             }
+            let nextStepNumber = 4;
+            if (unresolvedBuckets?.safeDeterministic && unresolvedBuckets.safeDeterministic > 0) {
+              console.log(
+                `  ${nextStepNumber}. Apply deterministic safe bucket (${unresolvedBuckets.safeDeterministic}): openclaw hybrid-mem resolve-contradictions --auto --apply`,
+              );
+              nextStepNumber++;
+            }
+            if (unresolvedBuckets?.possibleEntityReuse && unresolvedBuckets.possibleEntityReuse > 0) {
+              console.log(
+                `  ${nextStepNumber}. Review possible entity-reuse bucket (${unresolvedBuckets.possibleEntityReuse}): inspect entity naming/scope before superseding facts.`,
+              );
+              nextStepNumber++;
+            }
+            if (unresolvedBuckets?.olderVerified && unresolvedBuckets.olderVerified > 0) {
+              console.log(
+                `  ${nextStepNumber}. Review verified-older bucket (${unresolvedBuckets.olderVerified}): verify whether stale verification should be retained or replaced.`,
+              );
+              nextStepNumber++;
+            }
+            if (unresolvedBuckets?.humanRequired && unresolvedBuckets.humanRequired > 0) {
+              console.log(
+                `  ${nextStepNumber}. Review human-required bucket (${unresolvedBuckets.humanRequired}): export and adjudicate with openclaw hybrid-mem resolve-contradictions --auto --dry-run --export-review <path>.`,
+              );
+              nextStepNumber++;
+            }
+            if (unresolvedBuckets?.otherManual && unresolvedBuckets.otherManual > 0) {
+              console.log(
+                `  ${nextStepNumber}. Review other-manual bucket (${unresolvedBuckets.otherManual}): inspect details output and handle pair-specific blockers before rerun.`,
+              );
+              nextStepNumber++;
+            }
             const hasProjectStatePairs = res.ambiguous.some((a) => {
               const newF = factsDb.getById(a.factIdNew);
               const oldF = factsDb.getById(a.factIdOld);
@@ -1201,8 +1308,9 @@ export function registerManageReflectionPipeline(mem: Chainable, b: ManageBindin
             });
             if (hasProjectStatePairs) {
               console.log(
-                "  4. Auto-resolve project-state: openclaw hybrid-mem resolve-contradictions --project-state-lww --dry-run",
+                `  ${nextStepNumber}. Auto-resolve project-state: openclaw hybrid-mem resolve-contradictions --project-state-lww --dry-run`,
               );
+              nextStepNumber++;
             }
           }
         },
@@ -1291,12 +1399,40 @@ export function registerManageReflectionPipeline(mem: Chainable, b: ManageBindin
     .option("--limit <n>", "Max facts to process (default 200)", "200")
     .option("--all", "Process the full pending backlog in one catch-up run (ignores --limit cap)")
     .option("--model <m>", "LLM model (default: cron nano tier)")
+    .option("--adaptive-catch-up", "Enable adaptive enrich-entities pacing (throughput ramp-up + pressure backoff)")
+    .option("--batch-size <n>", "Adaptive catch-up baseline batch size (default 20)", "20")
+    .option("--batch-delay-ms <n>", "Adaptive catch-up baseline delay between batches in ms (default 150)", "150")
+    .option(
+      "--time-budget-sec <n>",
+      "Stop cleanly after this many seconds (adaptive catch-up; checked between facts/batches)",
+    )
+    .option("--target-duration-sec <n>", "Alias for --time-budget-sec")
+    .option("--max-concurrency <n>", "Max parallel LLM extractions per batch when adaptive (default 3)", "3")
+    .option(
+      "--provider-pressure-budget <n>",
+      "Stop after this many cumulative rate-limit/timeout pressure events (adaptive catch-up)",
+    )
+    .option("--json", "Emit structured JSON report (includes issue #1791 telemetry when adaptive)")
     .option("--dry-run", "Only report how many facts need enrichment")
     .option("-v, --verbose", "List candidate fact ids (dry-run) or enriched fact ids and mentions (after run)")
     .action(
       withExit(
         async (
-          opts?: { limit?: string; model?: string; all?: boolean; dryRun?: boolean; verbose?: boolean },
+          opts?: {
+            limit?: string;
+            model?: string;
+            all?: boolean;
+            dryRun?: boolean;
+            verbose?: boolean;
+            adaptiveCatchUp?: boolean;
+            batchSize?: string;
+            batchDelayMs?: string;
+            timeBudgetSec?: string;
+            targetDurationSec?: string;
+            maxConcurrency?: string;
+            providerPressureBudget?: string;
+            json?: boolean;
+          },
           cmd?: CommanderOptsParent,
         ) => {
           const all = !!opts?.all;
@@ -1308,7 +1444,32 @@ export function registerManageReflectionPipeline(mem: Chainable, b: ManageBindin
           const dryRun = !!opts?.dryRun;
           const model = opts?.model;
           const verbose = !!opts?.verbose || readHybridMemVerbose(cmd);
-          let enrichProgress = {
+          const adaptiveCatchUp = !!opts?.adaptiveCatchUp;
+          const batchSize = Number.parseInt(opts?.batchSize ?? "20", 10);
+          const batchDelayMs = Number.parseInt(opts?.batchDelayMs ?? "150", 10);
+          const timeBudgetRaw = opts?.timeBudgetSec ?? opts?.targetDurationSec;
+          const timeBudgetSec =
+            timeBudgetRaw != null && timeBudgetRaw !== "" ? Number.parseInt(timeBudgetRaw, 10) : undefined;
+          const maxConcurrency = Number.parseInt(opts?.maxConcurrency ?? "3", 10);
+          if (timeBudgetSec != null && (!Number.isFinite(timeBudgetSec) || timeBudgetSec < 1)) {
+            throw new Error("--time-budget-sec / --target-duration-sec must be a positive integer (>= 1).");
+          }
+          if (!Number.isFinite(maxConcurrency) || maxConcurrency < 1) {
+            throw new Error("--max-concurrency must be a positive integer (>= 1).");
+          }
+          const providerPressureBudgetRaw = opts?.providerPressureBudget;
+          const providerPressureBudget =
+            providerPressureBudgetRaw != null && providerPressureBudgetRaw !== ""
+              ? Number.parseInt(providerPressureBudgetRaw, 10)
+              : undefined;
+          if (
+            providerPressureBudget != null &&
+            (!Number.isFinite(providerPressureBudget) || providerPressureBudget < 1)
+          ) {
+            throw new Error("--provider-pressure-budget must be a positive integer (>= 1).");
+          }
+          const jsonMode = !!opts?.json;
+          let enrichProgress: import("../../../services/entity-enrichment-cli.js").EntityEnrichmentProgress = {
             processed: 0,
             total: 0,
             factsEnriched: 0,
@@ -1321,7 +1482,14 @@ export function registerManageReflectionPipeline(mem: Chainable, b: ManageBindin
             rejected: 0,
             duplicates: 0,
             rejectReasons: {},
+            effectiveBatchSize: adaptiveCatchUp ? batchSize : undefined,
+            effectiveDelayMs: adaptiveCatchUp ? batchDelayMs : undefined,
           };
+          if (adaptiveCatchUp && !jsonMode) {
+            console.log(
+              `Entity enrichment adaptive catch-up enabled: baseline batch=${batchSize}, delayMs=${batchDelayMs}.`,
+            );
+          }
           let res;
           try {
             res = await runMaintenanceHeartbeat(
@@ -1334,14 +1502,28 @@ export function registerManageReflectionPipeline(mem: Chainable, b: ManageBindin
                   dryRun,
                   model,
                   verbose,
+                  adaptiveCatchUp,
+                  batchSize,
+                  batchDelayMs,
+                  timeBudgetSec,
+                  maxConcurrency,
+                  providerPressureBudget,
                   onProgress: (next) => {
                     enrichProgress = next;
                     heartbeat.heartbeat();
                   },
+                  onAdaptivePacing: (next) => {
+                    if (verbose) {
+                      console.debug(
+                        `entity-enrichment-cli: adaptive pacing ${next.reason}; batch ${next.previousBatchSize}→${next.batchSize}, delay ${next.previousDelayMs}ms→${next.delayMs}ms, pressure=${next.batchPressureSignals}, transient=${next.batchTransientFailures}, rateLimited=${next.batchRateLimited}`,
+                      );
+                    }
+                  },
                 }),
               {
                 progressSupplier: () =>
-                  `stage=entity-enrichment; mode=${all ? "all" : "bounded"}; processed=${enrichProgress.processed}/${enrichProgress.total}; enriched=${enrichProgress.factsEnriched}; accepted=${enrichProgress.accepted}; rejected=${enrichProgress.rejected}; remaining=${enrichProgress.remainingTotal}; eta_runs=${enrichProgress.estimatedRunsRemaining}; dryRun=${dryRun ? "yes" : "no"}`,
+                  `stage=entity-enrichment; mode=${all ? "all" : "bounded"}; processed=${enrichProgress.processed}/${enrichProgress.total}; enriched=${enrichProgress.factsEnriched}; accepted=${enrichProgress.accepted}; rejected=${enrichProgress.rejected}; llmFailures=${enrichProgress.llmFailures ?? 0}; remaining=${enrichProgress.remainingTotal}; eta_runs=${enrichProgress.estimatedRunsRemaining}; batch=${enrichProgress.effectiveBatchSize ?? "static"}; delay_ms=${enrichProgress.effectiveDelayMs ?? "static"}; concurrency=${enrichProgress.effectiveConcurrency ?? "static"}; stop=${enrichProgress.stopReason ?? "running"}; dryRun=${dryRun ? "yes" : "no"}`,
+                jsonMode: jsonMode === true,
               },
             );
           } catch (err) {
@@ -1357,6 +1539,34 @@ export function registerManageReflectionPipeline(mem: Chainable, b: ManageBindin
           const estimatedRunsRemaining =
             res.estimatedRunsRemaining ?? (mode === "all" ? 0 : Math.ceil(remainingTotal / Math.max(1, limit)));
           const limitLabel = mode === "all" ? "all" : String(res.effectiveLimit ?? limit);
+          const hasPartialFailure = res.llmFailures && res.llmFailures > 0;
+          const exitCode = hasPartialFailure ? 2 : 0;
+          const exitReason = hasPartialFailure ? "partial_llm_failures" : "success";
+          const jsonReport = {
+            dryRun,
+            mode,
+            limit: limitLabel,
+            pendingBefore: pendingTotal,
+            pendingBatch: res.pending,
+            processed: res.processed,
+            enriched: res.factsEnriched,
+            remaining: remainingTotal,
+            estimatedRunsRemaining,
+            stopReason: res.stopReason ?? "completed",
+            llmFailures: res.llmFailures ?? 0,
+            adaptiveSummary: res.adaptiveSummary,
+            telemetry: res.telemetry,
+            rejectReasons: res.rejectReasons,
+            exitCode,
+            exitReason,
+          };
+          if (jsonMode) {
+            console.log(JSON.stringify(jsonReport, null, 2));
+            if (hasPartialFailure) {
+              process.exitCode = 2;
+            }
+            return;
+          }
           if (res.pendingByTier) {
             console.log(
               `Entity enrichment backlog by tier: hot=${res.pendingByTier.hot}, warm=${res.pendingByTier.warm}, structural=${res.pendingByTier.structural}, cold=${res.pendingByTier.cold}, unknown=${res.pendingByTier.unknown}`,
@@ -1380,9 +1590,15 @@ export function registerManageReflectionPipeline(mem: Chainable, b: ManageBindin
               for (const id of res.pendingFactIds) console.log(`  ${id}`);
             }
           } else {
+            const llmFailuresSuffix = res.llmFailures ? ` llmFailures=${res.llmFailures}` : "";
             console.log(
-              `Entity enrichment: processed=${res.processed} enriched=${res.factsEnriched} mentions=${res.mentions} accepted=${res.accepted} rejected=${res.rejected} duplicates=${res.duplicates}, batch=${res.pending}, pending-before-run=${pendingTotal}, remaining=${remainingTotal}, mode=${mode}, limit=${limitLabel}.`,
+              `Entity enrichment: processed=${res.processed} enriched=${res.factsEnriched} mentions=${res.mentions} accepted=${res.accepted} rejected=${res.rejected} duplicates=${res.duplicates}${llmFailuresSuffix}, batch=${res.pending}, pending-before-run=${pendingTotal}, remaining=${remainingTotal}, mode=${mode}, limit=${limitLabel}.`,
             );
+            if (res.llmFailures && res.llmFailures > 0) {
+              console.warn(
+                `Warning: ${res.llmFailures} fact${res.llmFailures === 1 ? "" : "s"} skipped due to LLM extraction failures (exit code 2).`,
+              );
+            }
             if (mode !== "all") {
               console.log(`Estimated runs remaining at current limit: ${estimatedRunsRemaining}`);
             }
@@ -1406,6 +1622,24 @@ export function registerManageReflectionPipeline(mem: Chainable, b: ManageBindin
                 console.log(`  ${reason}: ${count}`);
               }
             }
+            if (res.stopReason === "time_budget") {
+              console.log(
+                `Entity enrichment stopped: time budget reached (processed=${res.processed}, remaining=${remainingTotal}).`,
+              );
+            }
+            if (res.telemetry) {
+              console.log(`Entity enrichment adaptive telemetry: ${JSON.stringify(res.telemetry)}`);
+            } else if (res.adaptiveSummary) {
+              console.log(`Entity enrichment adaptive summary: ${JSON.stringify(res.adaptiveSummary)}`);
+            }
+            if (res.stopReason === "provider_budget") {
+              console.log(
+                `Entity enrichment stopped: provider pressure budget reached (rate limits/timeouts; processed=${res.processed}, remaining=${remainingTotal}).`,
+              );
+            }
+            if (res.llmFailures && res.llmFailures > 0) {
+              process.exitCode = 2;
+            }
           }
         },
       ),