@remnic/core 9.3.653 → 9.3.655

package/src/access-mcp.ts

@@ -3220,6 +3220,13 @@ export class EngramMcpServer {
             const resolved = await this.service.getWritableStorageForNamespace(namespace, effectivePrincipal);
             return resolved.storage;
           },
+          // Catalog write touch (issue #1499 sweep): a contradiction merge writes
+          // a new memory directly to the resolved namespace storage, bypassing the
+          // extraction write path. Record it so QMD maintenance / writtenSince
+          // don't miss the write. Best-effort and failure-tolerant.
+          onMergedMemoryWritten: (namespace, storageDir) => {
+            this.service.recordCatalogWrite(namespace, storageDir);
+          },
         });
       }
       case "engram.contradiction_scan_run":

package/src/access-service.ts

@@ -7348,6 +7348,18 @@ export class EngramAccessService {
     return this.orchestrator.storage;
   }
 
+  /**
+   * Best-effort catalog write touch delegate (issue #1499 sweep). HTTP/MCP
+   * surfaces resolve a per-namespace storage and write through it directly (e.g.
+   * a contradiction merge), bypassing the extraction write path that owns
+   * `markCatalogWrite`. They call this to record the write so a (possibly
+   * dynamic) namespace's `lastWriteAt` stays accurate and QMD maintenance does
+   * not miss it. Fire-and-forget and failure-tolerant on the orchestrator side.
+   */
+  recordCatalogWrite(namespace?: string, storageDir?: string): void {
+    this.orchestrator.recordCatalogWrite(namespace, storageDir);
+  }
+
   get configRef(): PluginConfig {
     return this.orchestrator.config;
   }

package/src/cli.ts

@@ -4155,6 +4155,103 @@ export function registerCli(
           console.log("\nOK");
         });
 
+      namespacesCmd
+        .command("rebuild")
+        .description(
+          "Rebuild the namespace catalog from disk (issue #1499). Scans configured + dynamic namespace roots safely and rewrites <memoryDir>/state/namespaces.jsonl",
+        )
+        .option("--dry-run", "Show the rebuilt catalog without writing it")
+        .option("--apply", "Write the rebuilt catalog to disk")
+        .option("--json", "Emit the rebuild result as JSON")
+        .action(async (optionsRaw: unknown) => {
+          const options =
+            optionsRaw && typeof optionsRaw === "object"
+              ? (optionsRaw as { dryRun?: boolean; apply?: boolean; json?: boolean })
+              : {};
+          // Default to a non-destructive dry run unless --apply is given.
+          // Reject contradictory flags rather than silently choosing one.
+          if (options.dryRun === true && options.apply === true) {
+            throw new Error("Pass only one of --dry-run or --apply, not both.");
+          }
+          const dryRun = options.apply !== true;
+
+          if (!orchestrator.namespaceCatalog.enabled) {
+            const note =
+              "Namespace catalog is inert: it only runs when namespacesEnabled is true and namespaceCatalogEnabled is not false.";
+            if (options.json === true) {
+              // Include `applied: false` so the inert JSON payload carries the SAME
+              // shape as the enabled path (cursor Low — NFDBM). An inert catalog
+              // rewrote nothing, so a `--apply` did NOT apply; automation that keys
+              // on `applied` must not misread a missing field as a completed rebuild.
+              console.log(
+                JSON.stringify(
+                  { dryRun, enabled: false, applied: false, records: [], skipped: [], note },
+                  null,
+                  2,
+                ),
+              );
+            } else {
+              console.log(note);
+            }
+            // Exit-code parity with the enabled path (cursor Medium — NFb5W): an
+            // inert catalog rewrote NOTHING, so a `--apply` (dryRun=false) did NOT
+            // apply. The enabled path sets `exitCode = 1` whenever a non-dry-run
+            // rebuild reports `applied: false`; an inert `--apply` is exactly that
+            // case, so exit-code-only automation must see a non-zero exit rather
+            // than read a no-op apply as a completed rebuild. A `--dry-run` (or the
+            // default dry run) inert call stays exit 0 — it never promised to write.
+            if (!dryRun) {
+              process.exitCode = 1;
+            }
+            return;
+          }
+
+          const result = await orchestrator.namespaceCatalog.rebuildFromDisk({ dryRun });
+
+          if (options.json === true) {
+            console.log(JSON.stringify({ enabled: true, ...result }, null, 2));
+            // Mirror the non-JSON failure signal (round 6, codex P2 — NEFoa): an
+            // `--apply` that could not acquire the lock returns `applied: false`
+            // and rewrote nothing, so automation must see a non-zero exit even in
+            // JSON mode rather than treating a no-op apply as a successful rebuild.
+            if (!dryRun && result.applied === false) {
+              process.exitCode = 1;
+            }
+            return;
+          }
+
+          console.log("=== Namespace Catalog Rebuild ===\n");
+          console.log(`mode: ${dryRun ? "dry-run" : "apply"}`);
+          console.log(`namespaces: ${result.records.length}`);
+          for (const record of result.records) {
+            console.log(
+              `${record.namespace}\n  kind: ${record.kind}\n  storage: ${record.storageDir}\n  discovered-by: ${record.discoveredBy}`,
+            );
+          }
+
+          if (result.skipped.length > 0) {
+            console.log("\nSkipped / ambiguous roots:");
+            for (const skip of result.skipped) {
+              console.log(`- ${skip.token} (${skip.reason})${skip.detail ? `: ${skip.detail}` : ""}`);
+            }
+          }
+
+          if (dryRun) {
+            console.log("\nDRY RUN");
+          } else if (result.applied) {
+            console.log("\nOK");
+          } else {
+            // An --apply that could not acquire the cross-process rebuild lock
+            // ran compute-only and did NOT rewrite the catalog (NBn3n/NBsGG).
+            // Report the non-mutation explicitly and exit non-zero so scripts
+            // and operators retry rather than assume the rebuild persisted.
+            console.log(
+              "\nNOT APPLIED: another rebuild holds the lock; the catalog was NOT rewritten. Retry shortly.",
+            );
+            process.exitCode = 1;
+          }
+        });
+
       cmd
         .command("export")
         .description("Export Remnic memory to JSON, Markdown bundle, or SQLite")
@@ -8858,6 +8955,13 @@ export function registerCli(
               }
               return orchestrator.getStorageForNamespace(requested || orchestrator.config.defaultNamespace);
             },
+            // Catalog write touch (issue #1499 sweep): a contradiction merge can
+            // write a new memory to a dynamic namespace via the CLI resolve path,
+            // bypassing the extraction write path. Record it so QMD maintenance /
+            // writtenSince don't miss the write. Best-effort and failure-tolerant.
+            onMergedMemoryWritten: (namespace, storageDir) => {
+              orchestrator.recordCatalogWrite(namespace, storageDir);
+            },
           });
           console.log(result.message);
           if (result.affectedIds.length > 0) {

package/src/config.test.ts

@@ -1291,3 +1291,112 @@ test("parseConfig rejects connectors.gmail.pollIntervalMs above maximum (25h)",
     /pollIntervalMs/,
   );
 });
+
+// ── issue #1499 / CLAUDE.md rule #36: namespaceCatalogEnabled opt-out coercion.
+// A string "false"/"0"/"no"/"off" from CLI/env/JSON config must disable the
+// catalog, not stay truthy. Defaults to enabled when absent/unrecognized.
+test("parseConfig namespaceCatalogEnabled defaults to true when absent", () => {
+  assert.equal(parseConfig({}).namespaceCatalogEnabled, true);
+});
+
+test('parseConfig namespaceCatalogEnabled="false" (string) → false (rule #36)', () => {
+  assert.equal(parseConfig({ namespaceCatalogEnabled: "false" }).namespaceCatalogEnabled, false);
+});
+
+test('parseConfig namespaceCatalogEnabled="0" (string) → false', () => {
+  assert.equal(parseConfig({ namespaceCatalogEnabled: "0" }).namespaceCatalogEnabled, false);
+});
+
+test('parseConfig namespaceCatalogEnabled="no"/"off" (strings) → false', () => {
+  assert.equal(parseConfig({ namespaceCatalogEnabled: "no" }).namespaceCatalogEnabled, false);
+  assert.equal(parseConfig({ namespaceCatalogEnabled: "off" }).namespaceCatalogEnabled, false);
+});
+
+test("parseConfig namespaceCatalogEnabled=false (boolean) → false", () => {
+  assert.equal(parseConfig({ namespaceCatalogEnabled: false }).namespaceCatalogEnabled, false);
+});
+
+test('parseConfig namespaceCatalogEnabled="true" (string) → true', () => {
+  assert.equal(parseConfig({ namespaceCatalogEnabled: "true" }).namespaceCatalogEnabled, true);
+});
+
+test("parseConfig namespaceCatalogEnabled present-but-unrecognized → throws (rule #51, codex NI42R)", () => {
+  // A PRESENT but unrecognized value is rejected, not silently defaulted to
+  // enabled — mirrors resolveEmitLegacyTools (CLAUDE.md rule #51: reject invalid
+  // input instead of silently defaulting). Absent still defaults to true.
+  assert.throws(
+    () => parseConfig({ namespaceCatalogEnabled: "maybe" }),
+    /namespaceCatalogEnabled must be a boolean-like value/,
+  );
+  assert.throws(() => parseConfig({ namespaceCatalogEnabled: "flase" }), /boolean-like value/);
+  assert.throws(() => parseConfig({ namespaceCatalogEnabled: 2 }), /boolean-like value/);
+});
+
+test("parseConfig maintenance namespace fanout defaults match hosted-safe policy", () => {
+  const cfg = parseConfig({});
+  assert.equal(cfg.maintenanceNamespaceFanoutEnabled, true);
+  assert.equal(cfg.maintenanceMaxNamespacesPerCycle, 20);
+  assert.equal(cfg.maintenanceIncludeProjectNamespaces, true);
+  assert.equal(cfg.maintenanceIncludeBranchNamespaces, false);
+  assert.equal(cfg.maintenanceIncludeTeamProjectNamespaces, true);
+  assert.equal(cfg.maintenanceNamespaceLockStaleMs, 10 * 60_000);
+});
+
+test("parseConfig accepts nested maintenance namespace fanout config", () => {
+  const cfg = parseConfig({
+    maintenance: {
+      namespaceFanoutEnabled: "false",
+      maxNamespacesPerCycle: "7",
+      includeProjectNamespaces: "off",
+      includeBranchNamespaces: "on",
+      includeTeamProjectNamespaces: "0",
+      namespaceLockStaleMs: "120000",
+    },
+  });
+  assert.equal(cfg.maintenanceNamespaceFanoutEnabled, false);
+  assert.equal(cfg.maintenanceMaxNamespacesPerCycle, 7);
+  assert.equal(cfg.maintenanceIncludeProjectNamespaces, false);
+  assert.equal(cfg.maintenanceIncludeBranchNamespaces, true);
+  assert.equal(cfg.maintenanceIncludeTeamProjectNamespaces, false);
+  assert.equal(cfg.maintenanceNamespaceLockStaleMs, 120_000);
+});
+
+test("parseConfig flat maintenance namespace fanout fields override nested config", () => {
+  const cfg = parseConfig({
+    maintenance: {
+      namespaceFanoutEnabled: false,
+      maxNamespacesPerCycle: 5,
+    },
+    maintenanceNamespaceFanoutEnabled: true,
+    maintenanceMaxNamespacesPerCycle: 8,
+  });
+  assert.equal(cfg.maintenanceNamespaceFanoutEnabled, true);
+  assert.equal(cfg.maintenanceMaxNamespacesPerCycle, 8);
+});
+
+test("parseConfig rejects invalid maintenance namespace fanout values", () => {
+  assert.throws(
+    () => parseConfig({ maintenance: [] }),
+    /maintenance must be a plain object/,
+  );
+  assert.throws(
+    () => parseConfig({ maintenance: "off" }),
+    /maintenance must be a plain object/,
+  );
+  assert.throws(
+    () => parseConfig({ maintenance: [], maintenanceNamespaceFanoutEnabled: false }),
+    /maintenance must be a plain object/,
+  );
+  assert.throws(
+    () => parseConfig({ maintenance: { namespaceFanoutEnabled: "flase" } }),
+    /maintenance\.namespaceFanoutEnabled must be a boolean-like value/,
+  );
+  assert.throws(
+    () => parseConfig({ maintenance: { maxNamespacesPerCycle: 0 } }),
+    /maintenance\.maxNamespacesPerCycle must be a positive integer/,
+  );
+  assert.throws(
+    () => parseConfig({ maintenance: { namespaceLockStaleMs: 1.5 } }),
+    /maintenance\.namespaceLockStaleMs must be a positive integer/,
+  );
+});

package/src/config.ts

@@ -384,6 +384,95 @@ function resolveEmitLegacyTools(configValue: unknown): boolean {
   return true;
 }
 
+/**
+ * Resolve the `namespaceCatalogEnabled` opt-out (issue #1499). A boolean-like
+ * value ("false"/"0"/"no"/"off" etc.) is honored; a PRESENT but unrecognized
+ * value ("flase", 2) is REJECTED rather than silently defaulting to enabled
+ * (CLAUDE.md rule #51 — reject invalid input instead of silently defaulting),
+ * mirroring `resolveEmitLegacyTools`. Defaults to enabled only when absent.
+ */
+function resolveNamespaceCatalogEnabled(configValue: unknown): boolean {
+  const ACCEPTED = "true/false/1/0/yes/no/on/off";
+  if (configValue !== undefined && configValue !== null) {
+    const coerced = coerceBooleanLike(configValue);
+    if (coerced === undefined) {
+      throw new Error(
+        `namespaceCatalogEnabled must be a boolean-like value (${ACCEPTED}); got ${JSON.stringify(configValue)}`,
+      );
+    }
+    return coerced;
+  }
+  return true;
+}
+
+function readNestedConfig(
+  cfg: Record<string, unknown>,
+  blockName: string,
+  key: string,
+): unknown {
+  const block = validateNestedConfigBlock(cfg, blockName);
+  if (!block) return undefined;
+  return block[key];
+}
+
+function validateNestedConfigBlock(
+  cfg: Record<string, unknown>,
+  blockName: string,
+): Record<string, unknown> | undefined {
+  const block = cfg[blockName];
+  if (block === undefined || block === null) return undefined;
+  if (typeof block !== "object" || Array.isArray(block)) {
+    throw new Error(`${blockName} must be a plain object`);
+  }
+  return block as Record<string, unknown>;
+}
+
+function readFlatOrNestedConfig(
+  cfg: Record<string, unknown>,
+  flatKey: string,
+  blockName: string,
+  nestedKey: string,
+): unknown {
+  return cfg[flatKey] !== undefined
+    ? cfg[flatKey]
+    : readNestedConfig(cfg, blockName, nestedKey);
+}
+
+function resolveBooleanConfig(
+  value: unknown,
+  defaultValue: boolean,
+  keyName: string,
+): boolean {
+  if (value === undefined || value === null) return defaultValue;
+  const coerced = coerceBool(value);
+  if (coerced === undefined) {
+    throw new Error(
+      `${keyName} must be a boolean-like value (true/false/1/0/yes/no/on/off); got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+function resolvePositiveIntegerConfig(
+  value: unknown,
+  defaultValue: number,
+  keyName: string,
+): number {
+  if (value === undefined || value === null) return defaultValue;
+  const coerced = coerceNumber(value);
+  if (
+    coerced === undefined ||
+    !Number.isFinite(coerced) ||
+    !Number.isInteger(coerced) ||
+    coerced < 1
+  ) {
+    throw new Error(
+      `${keyName} must be a positive integer; got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
 export function isOpenaiApiKeyDisabled(value: unknown): boolean {
   return value === false || (typeof value === "string" && value.trim().toLowerCase() === "false");
 }
@@ -747,6 +836,7 @@ export function parseConfig(raw: unknown): PluginConfig {
   } else {
     cfg = baseCfg;
   }
+  validateNestedConfigBlock(cfg, "maintenance");
 
   const modelSource =
     cfg.modelSource === "gateway" ? "gateway" : "plugin";
@@ -1461,6 +1551,66 @@ export function parseConfig(raw: unknown): PluginConfig {
         ? Math.max(1, Math.floor(cfg.crossSignalsSemanticTimeoutMs))
         : 4000;
   const recallPipelineConfig = buildRecallPipelineConfig(cfg);
+  const maintenanceNamespaceFanoutEnabled = resolveBooleanConfig(
+    readFlatOrNestedConfig(
+      cfg,
+      "maintenanceNamespaceFanoutEnabled",
+      "maintenance",
+      "namespaceFanoutEnabled",
+    ),
+    true,
+    "maintenance.namespaceFanoutEnabled",
+  );
+  const maintenanceMaxNamespacesPerCycle = resolvePositiveIntegerConfig(
+    readFlatOrNestedConfig(
+      cfg,
+      "maintenanceMaxNamespacesPerCycle",
+      "maintenance",
+      "maxNamespacesPerCycle",
+    ),
+    20,
+    "maintenance.maxNamespacesPerCycle",
+  );
+  const maintenanceIncludeProjectNamespaces = resolveBooleanConfig(
+    readFlatOrNestedConfig(
+      cfg,
+      "maintenanceIncludeProjectNamespaces",
+      "maintenance",
+      "includeProjectNamespaces",
+    ),
+    true,
+    "maintenance.includeProjectNamespaces",
+  );
+  const maintenanceIncludeBranchNamespaces = resolveBooleanConfig(
+    readFlatOrNestedConfig(
+      cfg,
+      "maintenanceIncludeBranchNamespaces",
+      "maintenance",
+      "includeBranchNamespaces",
+    ),
+    false,
+    "maintenance.includeBranchNamespaces",
+  );
+  const maintenanceIncludeTeamProjectNamespaces = resolveBooleanConfig(
+    readFlatOrNestedConfig(
+      cfg,
+      "maintenanceIncludeTeamProjectNamespaces",
+      "maintenance",
+      "includeTeamProjectNamespaces",
+    ),
+    true,
+    "maintenance.includeTeamProjectNamespaces",
+  );
+  const maintenanceNamespaceLockStaleMs = resolvePositiveIntegerConfig(
+    readFlatOrNestedConfig(
+      cfg,
+      "maintenanceNamespaceLockStaleMs",
+      "maintenance",
+      "namespaceLockStaleMs",
+    ),
+    10 * 60_000,
+    "maintenance.namespaceLockStaleMs",
+  );
 
   return {
     openaiApiKey: apiKey,
@@ -2525,6 +2675,12 @@ export function parseConfig(raw: unknown): PluginConfig {
     qmdMaintenanceEnabled: cfg.qmdMaintenanceEnabled !== false,
     qmdMaintenanceDebounceMs:
       typeof cfg.qmdMaintenanceDebounceMs === "number" ? cfg.qmdMaintenanceDebounceMs : 30_000,
+    maintenanceNamespaceFanoutEnabled,
+    maintenanceMaxNamespacesPerCycle,
+    maintenanceIncludeProjectNamespaces,
+    maintenanceIncludeBranchNamespaces,
+    maintenanceIncludeTeamProjectNamespaces,
+    maintenanceNamespaceLockStaleMs,
     qmdAutoEmbedEnabled: cfg.qmdAutoEmbedEnabled === true,
     qmdEmbedMinIntervalMs:
       typeof cfg.qmdEmbedMinIntervalMs === "number" ? cfg.qmdEmbedMinIntervalMs : 60 * 60_000,
@@ -2588,6 +2744,14 @@ export function parseConfig(raw: unknown): PluginConfig {
 
     // v3.0 namespaces (default off)
     namespacesEnabled: cfg.namespacesEnabled === true,
+    // Namespace catalog (issue #1499): default ON, but only does anything when
+    // namespacesEnabled is also true (the catalog is inert otherwise). Operators
+    // opt out with namespaceCatalogEnabled: false. Boolean-like opt-outs from
+    // CLI/env/JSON ("false", "0", "no", "off") are honored (CLAUDE.md rule #36);
+    // a PRESENT but unrecognized value ("flase", 2) is REJECTED rather than
+    // silently defaulting to enabled (CLAUDE.md rule #51); default to enabled
+    // only when the value is absent.
+    namespaceCatalogEnabled: resolveNamespaceCatalogEnabled(cfg.namespaceCatalogEnabled),
     // NOTE: namespace identifiers are intentionally NOT sanitized here — the
     // codebase rejects unsafe namespaces at the point of use (see
     // codex-materialize-runner and NamespaceStorageRouter / resolveNamespaceDir),