@remnic/core 9.69.45 → 9.69.47

package/src/cli/memory-browse-commands.ts

@@ -0,0 +1,77 @@
+/**
+ * Memory-store browse command group (issue #2978) — extracted from cli.ts
+ * so the surface file stays at its structural ceiling (same seam as
+ * cli/recall-navigation-commands.ts). `remnic browse ls|tree|find` runs
+ * through EngramAccessService.memoryStoreBrowse — the same single
+ * implementation MCP and HTTP call, sharing one renderer.
+ */
+
+import type { Orchestrator } from "../orchestrator.js";
+import type { CliCommand } from "../cli.js";
+import { EngramAccessService } from "../access-service.js";
+import type { BrowseVerb } from "../memory-browse.js";
+
+export function registerMemoryBrowseCommands(cmd: CliCommand, orchestrator: Orchestrator): void {
+  const run = async (args: unknown[], verb: BrowseVerb) => {
+    const options = (args[args.length - 1] ?? {}) as Record<string, unknown>;
+    // `browse find <pattern>` takes the pattern as a positional arg; the
+    // options object sits at the END of commander's action args.
+    const pattern = typeof args[0] === "string" && args[0].length > 0
+      ? args[0]
+      : typeof options.pattern === "string"
+        ? options.pattern
+        : "";
+    if (verb === "find" && pattern.trim().length === 0) {
+      console.error("usage: browse <ls|tree|find> [path] [--pattern <glob>] [--depth <n>] [--namespace <ns>] [--json]");
+      process.exitCode = 1;
+      return;
+    }
+    const depth = verb === "tree" && options.depth !== undefined ? Number(options.depth) : undefined;
+    if (depth !== undefined && (!Number.isFinite(depth) || !Number.isInteger(depth) || depth < 1 || depth > 4)) {
+      console.error("--depth must be an integer between 1 and 4");
+      process.exitCode = 1;
+      return;
+    }
+    const service = new EngramAccessService(orchestrator);
+    try {
+      const result = await service.memoryStoreBrowse({
+        verb,
+        ...(typeof args[0] === "string" && args[0].length > 0 ? { path: args[0] } : {}),
+        ...(depth !== undefined ? { depth } : {}),
+        ...(verb === "find" ? { pattern } : {}),
+        ...(typeof options.namespace === "string" && options.namespace.length > 0 ? { namespace: options.namespace } : {}),
+      });
+      if (options.json === true) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(result.rendered);
+      }
+      if (!result.ok) process.exitCode = 1;
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exitCode = 1;
+    }
+  };
+
+  cmd
+    .command("browse ls [path]")
+    .description("List children of a store path in your namespace (issue #2978)")
+    .option("--namespace <ns>", "Namespace to scope the browse to")
+    .option("--json", "JSON output (entries + counts + truncated flag)")
+    .action(async (...args: unknown[]) => run(args, "ls"));
+
+  cmd
+    .command("browse tree [path]")
+    .description("Depth-limited store tree under one path (issue #2978)")
+    .option("--depth <n>", "Expansion depth, 1-4 (default 1)")
+    .option("--namespace <ns>", "Namespace to scope the browse to")
+    .option("--json", "JSON output (entries + counts + truncated flag)")
+    .action(async (...args: unknown[]) => run(args, "tree"));
+
+  cmd
+    .command("browse find <pattern>")
+    .description("Deterministic name/path glob or substring lookup (issue #2978)")
+    .option("--namespace <ns>", "Namespace to scope the browse to")
+    .option("--json", "JSON output (entries + counts + truncated flag)")
+    .action(async (...args: unknown[]) => run(args, "find"));
+}

package/src/cli.ts

@@ -14,7 +14,7 @@ import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 import { utcDayRange } from "./transcript.js";
 import { padEndDisplay, truncateGraphemeSafe } from "./whitespace.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
-import { registerMeetingsCommands } from "./cli/meetings-commands.js"; import { registerDeepRecallCommands } from "./cli/deep-recall-commands.js"; import { registerRecallNavigationCommands } from "./cli/recall-navigation-commands.js";
+import { registerMeetingsCommands } from "./cli/meetings-commands.js"; import { registerDeepRecallCommands } from "./cli/deep-recall-commands.js"; import { registerRecallNavigationCommands } from "./cli/recall-navigation-commands.js"; import { registerMemoryBrowseCommands } from "./cli/memory-browse-commands.js";
 import { registerExportOkfCommand, registerOkfCommands } from "./cli/okf-commands.js";
 import { registerSkillsCommands } from "./cli/skills-commands.js";
 import { registerResearchStatusCommands } from "./cli/research-status-commands.js";
@@ -6230,7 +6230,7 @@ export function registerCli(
 
       registerResearchStatusCommands(cmd, orchestrator);
 
-      registerCreationLedgerCommands(cmd, orchestrator); registerMeetingsCommands(cmd, orchestrator); registerOkfCommands(cmd, orchestrator); registerDeepRecallCommands(cmd, orchestrator); registerTimelineCommands(cmd, orchestrator); registerRecallNavigationCommands(cmd, orchestrator);
+      registerCreationLedgerCommands(cmd, orchestrator); registerMeetingsCommands(cmd, orchestrator); registerOkfCommands(cmd, orchestrator); registerDeepRecallCommands(cmd, orchestrator); registerTimelineCommands(cmd, orchestrator); registerRecallNavigationCommands(cmd, orchestrator); registerMemoryBrowseCommands(cmd, orchestrator);
 
       cmd
         .command("trust-zone-promote")

package/src/config.ts

@@ -41,6 +41,11 @@ import { expandTildePath } from "./utils/path.js";
 import { coerceBool, coerceBooleanLike, coerceInstallExtension, coerceNumber } from "./connectors/coerce.js";
 import { parseSubjectRuntimeConfig } from "./subject-config.js";
 import { parseRecallStateViews } from "./recall-state-view.js";
+import {
+  parseRecallStandingBlock,
+  parseStandingBlockFreshDays,
+  parseStandingBlockMaxChars,
+} from "./standing-memory-block.js";
 import { parseRecallConcurrencyConfig } from "./recall-concurrency-config.js";
 import { parseExtractionFields } from "./extraction-span-config.js";
 import { parseReplicaPeersConfig } from "./replica-peers-config.js";
@@ -1952,6 +1957,12 @@ export function parseConfig(
     // Recall state views (issue #1952). Default false; exact false/0/"false"
     // disable (parseRecallStateViews → coerceBooleanLike).
     recallStateViews: parseRecallStateViews(cfg.recallStateViews),
+    // Prefix-cache-stable standing memory block (issue #2971). Default
+    // false, and nothing on the recall path reads these keys until the
+    // server wiring slice lands — pre-wiring behavior is byte-identical.
+    recallStandingBlock: parseRecallStandingBlock(cfg.recallStandingBlock),
+    standingBlockFreshDays: parseStandingBlockFreshDays(cfg.standingBlockFreshDays),
+    standingBlockMaxChars: parseStandingBlockMaxChars(cfg.standingBlockMaxChars),
     // Disclosure auto-escalation (issue #677 PR 4/4).  Default `manual`
     // so pre-#677 callers see unchanged behavior.  Reject anything
     // outside the allow-list rather than silently defaulting (CLAUDE.md

package/src/dedup/merge.test.ts

@@ -769,7 +769,6 @@ async function harness(
     registerFactContentHash: async (id: string, hash: string, _expectedContent: string) => {
       calls.hashRegistrations.push({ id, hash });
     },
-    readCasRevision: async (p: string) => (p === targetPath ? casRevision : undefined),
     readCasRevisionStatus: async (p: string): Promise<CasRevisionReadStatus> => {
       if (p !== targetPath) return { status: "absent" };
       if (overrides.receiptStatus === "unavailable") {
@@ -3460,7 +3459,10 @@ async function postEffectsHarness(options: {
         : null,
     // #2807: static token — these fixtures drive the rollback paths, not
     // ownership attribution.
-    readCasRevision: async () => "2026-08-20T00:00:00.000Z",
+    readCasRevisionStatus: async (): Promise<CasRevisionReadStatus> => ({
+      status: "present",
+      revision: "2026-08-20T00:00:00.000Z",
+    }),
   } as unknown as StorageManager;
   const deps = {
     config: parseConfig({ memoryDir: dir }),
@@ -3729,6 +3731,12 @@ test("runMergedTargetPostEffects: a writer committing mid-rebuild keeps its edge
             content: buildGraphEdgeCalls > 0 ? NEWER_BODY : MERGED,
           }
         : null,
+    // #2807: B's mid-rebuild commit mints a NEW token — the identity the
+    // revision guard compares (public `updated` no longer carries it).
+    readCasRevisionStatus: async (): Promise<CasRevisionReadStatus> =>
+      buildGraphEdgeCalls > 0
+        ? { status: "present", revision: "2026-08-22T01:00:00.001Z" }
+        : { status: "present", revision: "2026-08-20T00:00:00.000Z" },
   } as unknown as StorageManager;
   const deps = {
     ...h.deps,
@@ -3800,8 +3808,10 @@ test("runMergedTargetPostEffects: a stale writer's rollback preserves the newer
         : null,
     // #2807: B's mid-rebuild commit mints a NEW token — the identity the
     // revision guard compares (public `updated` no longer carries it).
-    readCasRevision: async () =>
-      buildStarted ? "2026-08-22T01:00:00.001Z" : "2026-08-20T00:00:00.000Z",
+    readCasRevisionStatus: async (): Promise<CasRevisionReadStatus> =>
+      buildStarted
+        ? { status: "present", revision: "2026-08-22T01:00:00.001Z" }
+        : { status: "present", revision: "2026-08-20T00:00:00.000Z" },
   } as unknown as StorageManager;
   const graphConfig = parseConfig({ memoryDir: h.dir });
   const graphIndex = new GraphIndex(h.dir, graphConfig);
@@ -3849,6 +3859,170 @@ test("runMergedTargetPostEffects: a stale writer's rollback preserves the newer
   );
 });
 
+// ── #2837: the revision guard must FAIL CLOSED. The old guard read the
+// receipt fail-open (readCasRevision), so a rewrite whose BOTH sidecar reads
+// were unavailable compared undefined against undefined, passed, and
+// installed replacement edges no receipt ever verified. ────────────────────
+
+test("runMergedTargetPostEffects: both receipt reads unavailable skips the graph rewrite instead of installing unchecked (#2837)", async () => {
+  const h = await postEffectsHarness();
+  const OTHER = "facts/2026-08-19/other.md";
+  const priorEntity: GraphEdge = { from: h.targetRelPath, to: OTHER, type: "entity", weight: 1, label: "entity-billing-service", ts: "2026-08-19T00:00:00.000Z" };
+  await seedGraphFile(h.dir, "entity", [priorEntity]);
+  let built = false;
+  const storage = {
+    dir: h.dir,
+    getMemoryByIdIncludingArchived: async (id: string) =>
+      id === "fact-target"
+        ? {
+            path: path.join(h.dir, h.targetRelPath),
+            frontmatter: { id, category: "fact", entityRef: "entity-billing-service" },
+            content: MERGED,
+          }
+        : null,
+    // The fail-open collapse the OLD guard trusted: an unreadable sidecar
+    // reads as undefined on both sides of the remove-and-rebuild.
+    readCasRevision: async () => undefined,
+    readCasRevisionStatus: async (): Promise<CasRevisionReadStatus> => ({
+      status: "unavailable",
+      reason: "simulated sidecar outage",
+    }),
+  } as unknown as StorageManager;
+  const deps = {
+    ...h.deps,
+    buildGraphEdge: async () => {
+      built = true;
+    },
+  } as unknown as ExtractionPersistDeps;
+  const graphContext = { allMemsForGraph: [], memoryPathById: new Map(), previousPersistedRelPath: "facts/2026-08-18/prev.md" };
+  await runMergedTargetPostEffects(
+    deps,
+    storage,
+    { targetId: "fact-target", mergedContent: MERGED },
+    {
+      category: "fact",
+      incomingContent: INCOMING,
+      incomingConfidence: 0.9,
+      namespace: "default",
+      graphCaps: ALL_GRAPH_CAPS,
+      graphContext,
+      threadIdForEdge: undefined,
+      threadEpisodeIdsForGraph: undefined,
+    },
+  );
+  assert.equal(built, false, "the graph effect must be SKIPPED while receipt identity is unavailable");
+  assert.deepEqual(
+    await readGraphFile(h.dir, "entity"),
+    [priorEntity],
+    "the prior edges survive untouched — nothing was removed for an install that could never be verified",
+  );
+  assert.equal(graphContext.previousPersistedRelPath, "facts/2026-08-18/prev.md", "a skipped rewrite must not advance the adjacency chain");
+});
+
+test("runMergedTargetPostEffects: a receipt that becomes unavailable mid-rebuild rolls the install back (#2837)", async () => {
+  const h = await postEffectsHarness();
+  const OTHER = "facts/2026-08-19/other.md";
+  const priorEntity: GraphEdge = { from: h.targetRelPath, to: OTHER, type: "entity", weight: 1, label: "entity-billing-service", ts: "2026-08-19T00:00:00.000Z" };
+  await seedGraphFile(h.dir, "entity", [priorEntity]);
+  let buildStarted = false;
+  const storage = {
+    dir: h.dir,
+    getMemoryByIdIncludingArchived: async (id: string) =>
+      id === "fact-target"
+        ? {
+            path: path.join(h.dir, h.targetRelPath),
+            frontmatter: { id, category: "fact", entityRef: "entity-billing-service" },
+            content: MERGED,
+          }
+        : null,
+    readCasRevision: async () => undefined,
+    readCasRevisionStatus: async (): Promise<CasRevisionReadStatus> =>
+      buildStarted
+        ? { status: "unavailable", reason: "simulated transient sidecar read failure" }
+        : { status: "present", revision: "2026-08-20T00:00:00.000Z" },
+  } as unknown as StorageManager;
+  const rebuilt: GraphEdge = { from: h.targetRelPath, to: OTHER, type: "entity", weight: 1, label: "entity-billing-service-v3", ts: "2026-08-23T00:00:00.000Z" };
+  const deps = {
+    ...h.deps,
+    buildGraphEdge: async () => {
+      buildStarted = true;
+      await appendEdge(h.dir, { ...rebuilt });
+      return [{ ...rebuilt }];
+    },
+  } as unknown as ExtractionPersistDeps;
+  const graphContext = { allMemsForGraph: [], memoryPathById: new Map(), previousPersistedRelPath: "facts/2026-08-18/prev.md" };
+  await runMergedTargetPostEffects(
+    deps,
+    storage,
+    { targetId: "fact-target", mergedContent: MERGED },
+    {
+      category: "fact",
+      incomingContent: INCOMING,
+      incomingConfidence: 0.9,
+      namespace: "default",
+      graphCaps: ALL_GRAPH_CAPS,
+      graphContext,
+      threadIdForEdge: undefined,
+      threadEpisodeIdsForGraph: undefined,
+    },
+  );
+  assert.deepEqual(
+    await readGraphFile(h.dir, "entity"),
+    [priorEntity],
+    "an unverifiable post-build receipt must roll the remove-and-rebuild back to the prior edges",
+  );
+  assert.equal(graphContext.previousPersistedRelPath, "facts/2026-08-18/prev.md", "a rolled-back rewrite must not advance the adjacency chain");
+});
+test("runMergedTargetPostEffects: a genuinely absent receipt on both reads still installs (#2837)", async () => {
+  const h = await postEffectsHarness();
+  const OTHER = "facts/2026-08-19/other.md";
+  const priorEntity: GraphEdge = { from: h.targetRelPath, to: OTHER, type: "entity", weight: 1, label: "entity-billing-service", ts: "2026-08-19T00:00:00.000Z" };
+  await seedGraphFile(h.dir, "entity", [priorEntity]);
+  const storage = {
+    dir: h.dir,
+    getMemoryByIdIncludingArchived: async (id: string) =>
+      id === "fact-target"
+        ? {
+            path: path.join(h.dir, h.targetRelPath),
+            frontmatter: { id, category: "fact", entityRef: "entity-billing-service" },
+            content: MERGED,
+          }
+        : null,
+    readCasRevision: async () => undefined,
+    readCasRevisionStatus: async (): Promise<CasRevisionReadStatus> => ({ status: "absent" }),
+  } as unknown as StorageManager;
+  const rebuilt: GraphEdge = { from: h.targetRelPath, to: OTHER, type: "entity", weight: 1, label: "entity-billing-service-v3", ts: "2026-08-23T00:00:00.000Z" };
+  const deps = {
+    ...h.deps,
+    buildGraphEdge: async () => {
+      await appendEdge(h.dir, { ...rebuilt });
+      return [{ ...rebuilt }];
+    },
+  } as unknown as ExtractionPersistDeps;
+  const graphContext = { allMemsForGraph: [], memoryPathById: new Map(), previousPersistedRelPath: "facts/2026-08-18/prev.md" };
+  await runMergedTargetPostEffects(
+    deps,
+    storage,
+    { targetId: "fact-target", mergedContent: MERGED },
+    {
+      category: "fact",
+      incomingContent: INCOMING,
+      incomingConfidence: 0.9,
+      namespace: "default",
+      graphCaps: ALL_GRAPH_CAPS,
+      graphContext,
+      threadIdForEdge: undefined,
+      threadEpisodeIdsForGraph: undefined,
+    },
+  );
+  assert.deepEqual(
+    await readGraphFile(h.dir, "entity"),
+    [rebuilt],
+    "a target that never minted a receipt (pre-sidecar legacy) still installs its rebuilt edges",
+  );
+  assert.equal(graphContext.previousPersistedRelPath, h.targetRelPath, "the verified install advances the batch's adjacency chain");
+});
+
 // ── Round N+16 (A): the N+14 surgical rollback leaned on build()'s RETURN
 // value. A build that THROWS mid-append (the entity rows landed, a later
 // append failed) loses that return, and the rollback fell back to the
@@ -4194,11 +4368,12 @@ test("applySemanticMergeAtPersist: a timestamp-less retirement between the conte
   // identity the rollback compares.
   const receipt = h.calls.commitRevisions[0];
   assert.ok(receipt, "the content CAS stamped a receipt");
-  const standingToken = await h.storage.readCasRevision(h.target.path);
-  assert.ok(standingToken, "the retirement minted a new token");
+  const standingStatus = await h.storage.readCasRevisionStatus(h.target.path);
+  assert.ok(standingStatus.status === "present", "the retirement minted a standing receipt");
+  const standingToken = standingStatus.status === "present" ? standingStatus.revision : undefined;
   assert.notEqual(standingToken, receipt, "the timestamp-less retirement retired the CAS's receipt token");
   assert.ok(
-    new Date(standingToken).getTime() > new Date(receipt).getTime(),
+    standingToken !== undefined && new Date(standingToken).getTime() > new Date(receipt).getTime(),
     "the timestamp-less retirement advanced the token strictly past the CAS receipt",
   );
   assert.deepEqual(
@@ -4324,7 +4499,9 @@ test("applySemanticMergeAtPersist: the monotonic receipt survives the metadata p
     T.toISOString(),
     "#2807: the metadata patch stamps business time (mergePatch.updated) verbatim — never a revision",
   );
-  const standingToken = await h.storage.readCasRevision(h.target.path);
+  const standingRead = await h.storage.readCasRevisionStatus(h.target.path);
+  assert.equal(standingRead.status, "present", "the standing receipt is readable after the metadata patches");
+  const standingToken = standingRead.status === "present" ? standingRead.revision : undefined;
   const [aReceipt, bReceipt, cReceipt2] = h.calls.commitRevisions;
   assert.ok(aReceipt && bReceipt && cReceipt2);
   assert.ok(aReceipt < bReceipt && bReceipt < cReceipt2, "A, B, C receipts are unique and strictly increasing");