@remnic/core 9.69.75 → 9.69.77

package/src/config.ts

@@ -43,6 +43,7 @@ import {
   parseStandingBlockFreshDays,
   parseStandingBlockMaxChars,
 } from "./standing-memory-block.js";
+import { parseDirectorySidecarsEnabled } from "./directory-sidecars.js";
 import { parseRecognitionIndexMaxEntries, parseRecallRecognitionTier } from "./recall-recognition-tier.js";
 import { parseRecallConcurrencyConfig } from "./recall-concurrency-config.js";
 import { parseExtractionFields } from "./extraction-span-config.js";
@@ -1962,12 +1963,10 @@ 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),
+    directorySidecarsEnabled: parseDirectorySidecarsEnabled(cfg.directorySidecarsEnabled),
     // Full-index recognition tier (issue #2975). Default false; nothing on the
     // recall path reads these keys until the wiring slice lands.
     recallRecognitionTier: parseRecallRecognitionTier(cfg.recallRecognitionTier),
@@ -3128,7 +3127,7 @@ export function parseConfig(
     recallEnrichmentDeadlineMs:
       typeof cfg.recallEnrichmentDeadlineMs === "number"
         ? Math.max(0, Math.floor(cfg.recallEnrichmentDeadlineMs))
-        : 25_000,
+        : 60_000,
     recallPipeline: recallPipelineConfig.pipeline,
     recallMmrEnabled: cfg.recallMmrEnabled !== false,
     recallMmrLambda:

package/src/directory-sidecars-config.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import {
+  applyDirectorySidecarDrillDown,
+  isDirectorySidecarsEnabledForDir,
+  setDirectorySidecarsEnabledForDir,
+} from "./directory-sidecars.js";
+
+test("#3088 parseConfig directorySidecarsEnabled is off by default and opt-in only", () => {
+  assert.equal(parseConfig({}).directorySidecarsEnabled, false);
+  assert.equal(parseConfig({ directorySidecarsEnabled: "false" }).directorySidecarsEnabled, false);
+  assert.equal(parseConfig({ directorySidecarsEnabled: true }).directorySidecarsEnabled, true);
+});
+
+test("#3088 sidecar enable walks up from namespace storage roots", () => {
+  const root = "/tmp/remnic-sidecar-root";
+  const nested = `${root}/namespaces/team-a`;
+  setDirectorySidecarsEnabledForDir(root, true);
+  assert.equal(isDirectorySidecarsEnabledForDir(nested), true);
+  setDirectorySidecarsEnabledForDir(nested, false);
+  assert.equal(isDirectorySidecarsEnabledForDir(nested), false);
+  assert.equal(isDirectorySidecarsEnabledForDir("/tmp/other-memory"), false);
+});
+
+test("#3088 drill-down skips when authorized namespace set is empty", async () => {
+  const hits = [{ path: "facts/a.md", snippet: "hello", score: 1 }];
+  const out = await applyDirectorySidecarDrillDown("/tmp/memory", "hello", hits, {
+    enabled: true,
+    namespaces: [],
+  });
+  assert.deepEqual(out, hits);
+});

package/src/directory-sidecars.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { mkdir, readdir, readFile, stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -10,6 +10,7 @@ import {
   DIRECTORY_SIDECAR_MARKER,
   NEIGHBORHOOD_ABSTRACT_LABEL,
   applyDirectorySidecarDrillDown,
+  directorySidecarAncestry,
   findDirectorySidecarsForQuery,
   loadDirectorySidecar,
   parseDirectorySidecarsEnabled,
@@ -498,3 +499,37 @@ test("drill-down prefers the most specific matching directory", async () => {
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+test("#3007 sidecar ancestry refuses a symlinked memory root", () => {
+  const root = store();
+  try {
+    const facts = path.join(root, "facts");
+    mkdirSync(facts);
+    const linked = path.join(root, "linked-root");
+    symlinkSync(root, linked);
+    assert.deepEqual(directorySidecarAncestry(linked, "facts/2026-01-01/fact.md"), []);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("#3090 sidecar ancestry refuses a symlink above the category root", async () => {
+  const root = store();
+  try {
+    const outside = path.join(root, "outside");
+    mkdirSync(path.join(outside, "alpha", "facts", "2026-01-01"), { recursive: true });
+    writeFileSync(path.join(outside, "alpha", "facts", "2026-01-01", "fact.md"), "x");
+    mkdirSync(path.join(root, "namespaces"));
+    symlinkSync(outside, path.join(root, "namespaces", "alpha"));
+    const report = await refreshDirectorySidecarsAfterWrite(
+      root,
+      "namespaces/alpha/facts/2026-01-01/fact.md",
+      true,
+    );
+    assert.deepEqual(report, { written: [], removed: [] });
+    assert.equal(existsSync(path.join(outside, "alpha", "facts", "overview.md")), false);
+    assert.equal(existsSync(path.join(outside, "alpha", "facts", "2026-01-01", "overview.md")), false);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/directory-sidecars.ts

@@ -70,6 +70,22 @@ export function parseDirectorySidecarsEnabled(raw: unknown): boolean {
   return coerceBooleanLike(raw, "directorySidecarsEnabled") === true;
 }
 
+const sidecarEnabledByDir = new Map<string, boolean>();
+
+export function setDirectorySidecarsEnabledForDir(memoryDir: string, enabled: boolean): void {
+  sidecarEnabledByDir.set(path.resolve(memoryDir), enabled === true);
+}
+
+export function isDirectorySidecarsEnabledForDir(memoryDir: string): boolean {
+  let dir = path.resolve(memoryDir);
+  for (;;) {
+    if (sidecarEnabledByDir.has(dir)) return sidecarEnabledByDir.get(dir) === true;
+    const parent = path.dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}
+
 /** Basenames never treated as child memories (ours plus OKF's reserved ones). */
 const RESERVED_CHILD_BASENAMES: Readonly<Record<string, true>> = Object.freeze({
   ...OKF_RESERVED_BASENAMES,
@@ -321,10 +337,21 @@ function childAbstractsFromDisk(dir: string): Map<string, string> {
  */
 export function directorySidecarAncestry(memoryDir: string, changedPath: string): string[] {
   const root = path.resolve(memoryDir);
+  if (!isRealDirectory(root)) return [];
   const abs = path.isAbsolute(changedPath) ? path.resolve(changedPath) : path.resolve(root, changedPath);
   const rel = path.relative(root, abs);
   if (rel.startsWith("..") || path.isAbsolute(rel)) return [];
   const parts = rel.split(path.sep).filter(Boolean);
+  let cursor = root;
+  for (let i = 0; i < parts.length; i++) {
+    cursor = path.join(cursor, parts[i] ?? "");
+    try {
+      if (lstatSync(cursor).isSymbolicLink()) return [];
+    } catch {
+      if (i === parts.length - 1) break;
+      return [];
+    }
+  }
   const dirParts = isRealDirectory(abs) ? parts : parts.slice(0, -1);
   let categoryAt = -1;
   if (dirParts[0] === "namespaces" && dirParts.length >= 3 && CATEGORY_ROOTS.has(dirParts[2] ?? "")) {
@@ -335,7 +362,9 @@ export function directorySidecarAncestry(memoryDir: string, changedPath: string)
   if (categoryAt === -1) return [];
   const dirs: string[] = [];
   for (let i = dirParts.length; i > categoryAt; i--) {
-    dirs.push(path.join(root, ...dirParts.slice(0, i)));
+    const dir = path.join(root, ...dirParts.slice(0, i));
+    if (!isRealDirectory(dir)) return [];
+    dirs.push(dir);
   }
   return dirs;
 }
@@ -512,13 +541,18 @@ export async function applyDirectorySidecarDrillDown<T extends DirectorySidecarH
   memoryDir: string,
   query: string,
   hits: readonly T[],
-  options: { enabled?: boolean; namespace?: string } = {},
+  options: { enabled?: boolean; namespace?: string; namespaces?: readonly string[] } = {},
 ): Promise<T[]> {
-  if (options.enabled !== true) return [...hits];
-  const matches = await findDirectorySidecarsForQuery(memoryDir, query, {
-    namespace: options.namespace,
-    refresh: false,
-  });
+  if (options.enabled !== true) return hits as T[];
+  const namespaces = options.namespaces;
+  if (namespaces !== undefined && namespaces.length === 0) return hits as T[];
+  const scopes = namespaces && namespaces.length > 0 ? namespaces : [options.namespace];
+  const matchLists = await Promise.all(
+    scopes.map((namespace) =>
+      findDirectorySidecarsForQuery(memoryDir, query, { namespace, refresh: false }),
+    ),
+  );
+  const matches = matchLists.flat();
   const fresh = matches.filter((match) => match.fresh && match.abstract.length > 0);
   if (fresh.length === 0) return [...hits];
   return hits.map((hit) => {

package/src/orchestration/recall-internal.ts

@@ -165,7 +165,7 @@ export class RecallInternalCoordinator {
     const recallSectionDeadlineMs = this.deps.config.recallCoreDeadlineMs ?? 75_000;
     const recallOuterTimeoutMs = this.deps.config.recallOuterTimeoutMs ?? 75_000;
     const enrichmentSectionDeadlineMs =
-      this.deps.config.recallEnrichmentDeadlineMs ?? 25_000;
+      this.deps.config.recallEnrichmentDeadlineMs ?? 60_000;
     // Wrap entire recall body in try/finally so profiling trace is always closed,
     // even on unexpected exceptions (e.g., throwIfRecallAborted, phase-1 errors).
     try {

package/src/orchestration/recall-recognition-search.test.ts

@@ -15,6 +15,7 @@ import test from "node:test";
 import { saveRecognitionIndex, type RecognitionIndex } from "../recall-recognition-tier.js";
 import {
   fetchQmdMemoryResultsWithRecognitionSwap,
+  recognitionHitScore,
   type RecognitionSearchDeps,
 } from "./recall-recognition-search.js";
 import type { QmdSearchResult } from "../types.js";
@@ -30,6 +31,13 @@ function indexOf(ids: string[]): RecognitionIndex {
   };
 }
 
+test("#3117 recognition hit scores stay on the retrieval 0-1 scale", () => {
+  assert.equal(recognitionHitScore(0), 1);
+  assert.ok(recognitionHitScore(1) < 1);
+  assert.ok(recognitionHitScore(1) > recognitionHitScore(2));
+  assert.ok(recognitionHitScore(99) > 0);
+});
+
 async function tmpDir(): Promise<string> {
   return mkdtemp(path.join(os.tmpdir(), "remnic-recognition-search-"));
 }

package/src/orchestration/recall-recognition-search.ts

@@ -133,6 +133,10 @@ export async function fetchQmdMemoryResultsWithRecognitionSwap(
   );
 }
 
+export function recognitionHitScore(rankOffset: number): number {
+  return 1 / (1 + rankOffset);
+}
+
 async function hitsFromIds(
   namespace: string,
   storage: RecognitionStorage,
@@ -152,7 +156,7 @@ async function hitsFromIds(
       docid: `${namespace}:${rel}`,
       namespace,
       path: rel,
-      score: ids.length - offset,
+      score: recognitionHitScore(offset),
       snippet: descriptionById.get(id) ?? id,
     });
   }

package/src/orchestration/recall-search-pipeline.ts

@@ -22,6 +22,7 @@ import { abortError } from "../abort-error.js";
 import { type CapabilitySet, type GraphConstructionCapabilitySet, resolveCapabilities, resolveConversationContextCapabilities, resolveGraphConstructionCapabilities, resolveIndexingCapabilities, resolveMemoryLifecycleCapabilities, resolveNamespaceCapabilities, resolvePipelineProcessingCapabilities, resolveQmdCapabilities, resolveRecallEnhancementCapabilities } from "../capabilities.js";
 import { EmbeddingFallback } from "../embedding-fallback.js";
 import { StorageManager } from "../index.js";
+import { applyDirectorySidecarDrillDown, isDirectorySidecarsEnabledForDir } from "../directory-sidecars.js";
 import { inferIntentFromText, intentCompatibilityScore } from "../intent.js";
 import { log } from "../logger.js";
 import { NamespaceStorageRouter } from "../namespaces/storage.js";
@@ -314,7 +315,7 @@ export class RecallSearchPipelineCoordinator {
       320,
       Math.max(fetchLimit, qmdFetchLimit * 5),
     );
-    const qmdRecallBudgetMs = this.deps.config.recallEnrichmentDeadlineMs ?? 25_000;
+    const qmdRecallBudgetMs = this.deps.config.recallEnrichmentDeadlineMs ?? 60_000;
     const qmdRecallBudgetEnabled = qmdRecallBudgetMs > 0;
     const startedAtMs = Date.now();
     let lastPrimaryResultCount = 0;
@@ -342,9 +343,6 @@ export class RecallSearchPipelineCoordinator {
     const debugSearchOptions = backendHonorsQmdSearchSignals
       ? resolvedSearchOptions
       : undefined;
-    // Cross-lingual recall (#2197): lexical tiers cannot match a query whose
-    // dominant script differs from the corpus's, whatever the page fill.
-    // Supplement with the embedding-fallback tier ONCE, before widening.
     const crossScriptVectorHits = options.crossScript
       ? await this.searchEmbeddingFallback(prompt, fetchLimit)
       : [];
@@ -517,7 +515,7 @@ export class RecallSearchPipelineCoordinator {
       if (filteredResults.length >= qmdFetchLimit) {
         const capped = filteredResults.slice(0, qmdFetchLimit);
         await emitDebugSnapshot(capped, fetchLimit);
-        return capped;
+        return await applyDirectorySidecarDrillDown(this.deps.storage?.dir ?? "", prompt, capped, { enabled: Boolean(this.deps.storage?.dir) && isDirectorySidecarsEnabledForDir(this.deps.storage.dir), namespaces: options.namespacesEnabled ? options.recallNamespaces ?? [] : undefined });
       }
       if (filteredResults.length > bestFiltered.length) {
         bestFiltered = filteredResults;
@@ -526,7 +524,7 @@ export class RecallSearchPipelineCoordinator {
       // hits). Keep widening until the backend itself underfills the page.
       if (primaryResults.length < fetchLimit) {
         await emitDebugSnapshot(filteredResults, fetchLimit);
-        return filteredResults;
+        return await applyDirectorySidecarDrillDown(this.deps.storage?.dir ?? "", prompt, filteredResults, { enabled: Boolean(this.deps.storage?.dir) && isDirectorySidecarsEnabledForDir(this.deps.storage.dir), namespaces: options.namespacesEnabled ? options.recallNamespaces ?? [] : undefined });
       }
       if (fetchLimit >= maxFetchLimit) {
         break;
@@ -538,7 +536,7 @@ export class RecallSearchPipelineCoordinator {
 
     const capped = bestFiltered.slice(0, qmdFetchLimit);
     await emitDebugSnapshot(capped, fetchLimit);
-    return capped;
+    return await applyDirectorySidecarDrillDown(this.deps.storage?.dir ?? "", prompt, capped, { enabled: Boolean(this.deps.storage?.dir) && isDirectorySidecarsEnabledForDir(this.deps.storage.dir), namespaces: options.namespacesEnabled ? options.recallNamespaces ?? [] : undefined });
   }
 
   async searchEmbeddingFallback(

package/src/orchestrator.ts

@@ -143,6 +143,7 @@ import { WorkspaceOpsCoordinator } from "./orchestration/workspace-ops.js";
 import { NamespaceReadFanoutCoordinator } from "./orchestration/namespace-read-fanout.js";
 import { selfDeps } from "./orchestration/self-deps.js";
 import { RecallEntryCoordinator } from "./orchestration/recall-entry.js";
+import { setDirectorySidecarsEnabledForDir } from "./directory-sidecars.js";
 import { SessionContextCoordinator, type SessionFlushOptions } from "./orchestration/session-context.js";
 import { drainRecallWrites, trackRecallWrite } from "./orchestration/recall-background-writes.js";
 import { XrayCaptureQueue } from "./orchestration/xray-capture-queue.js";
@@ -1971,6 +1972,13 @@ export class Orchestrator {
   async initialize(): Promise<void> {
     this.extractionQueueCoordinator.resumeAccepting();
     await this.orchestratorInitCoordinator.initialize();
+    {
+      const memoryDir = this.storage?.dir;
+      if (typeof memoryDir === "string" && memoryDir.length > 0) {
+        const { directorySidecarsEnabled } = this.config;
+        setDirectorySidecarsEnabledForDir(memoryDir, directorySidecarsEnabled);
+      }
+    }
     if (isDependencyPropagationEnabled(this.config)) {
       this._dependencyPropagationRecovery = this.dependencyPropagationDelivery
         .recover()

package/src/qmd.ts

@@ -70,7 +70,7 @@ export interface QmdClientOptions {
   qmdSubprocessStrategy?: QmdSubprocessStrategy;
   /** Override automatic qmd fallback probes; defaults to known install paths. */
   qmdFallbackPaths?: string[];
-  /** Per-call daemon search timeout in ms; default 8000. Issue #1335. */
+  /** Per-call daemon search timeout in ms; default 60000. Issue #1335/#3098. */
   qmdDaemonTimeoutMs?: number;
 }
 
@@ -152,9 +152,9 @@ export type { QmdStatusReport } from "./qmd-status.js";
 
 const QMD_TIMEOUT_MS = 30_000;
 // Daemon timeout for search calls. Keep under RECALL_TIMEOUT_MS (75s) so a slow
-// daemon fails fast. Default only — override via `qmdDaemonTimeoutMs` (#1335).
-// Keep ≥ 5s for normal post-load searches to complete reliably.
-const QMD_DAEMON_TIMEOUT_MS = 8_000;
+// daemon fails fast. Default only — override via `qmdDaemonTimeoutMs` (#1335/#3098).
+// 60s covers multi-GB cold indexes that 8s missed; operators can still set 8s.
+const QMD_DAEMON_TIMEOUT_MS = 60_000;
 const QMD_UPDATE_BACKOFF_MS = 15 * 60 * 1000; // 15m
 const QMD_EMBED_BACKOFF_MS = 60 * 60 * 1000; // 60m
 const QMD_CLI_WARN_THROTTLE_MS = 15 * 60 * 1000; // 15m

package/src/recall-budget-config.test.ts

@@ -8,7 +8,7 @@ test("parseConfig applies recall timeout and qmd recall cache defaults", () => {
 
   assert.equal(config.recallOuterTimeoutMs, 75_000);
   assert.equal(config.recallCoreDeadlineMs, 75_000);
-  assert.equal(config.recallEnrichmentDeadlineMs, 25_000);
+  assert.equal(config.recallEnrichmentDeadlineMs, 60_000);
   assert.equal(config.qmdRecallCacheTtlMs, 60_000);
   assert.equal(config.qmdRecallCacheStaleTtlMs, 10 * 60_000);
   assert.equal(config.qmdRecallCacheMaxEntries, 128);

package/src/storage.ts

@@ -248,8 +248,7 @@ import {
   sealedWriteToLegacyArgs,
   type SealedMemoryEnvelope,
 } from "./write-envelope.js";
-// stripCitation import removed: legacy rebuild fallback was replaced by a
-// skip-with-warning strategy (Finding 1 — Uhol).  See ensureFactHashIndexAuthoritative.
+import { isDirectorySidecarsEnabledForDir, refreshDirectorySidecarsAfterWrite } from "./directory-sidecars.js";
 type SharedVersionKind = "memory-status" | "artifact-write" | "cold-write" | "memory-corpus" | "entity-mutation";
 
 type OfflineSyncDigestCacheEntry = {
@@ -3973,25 +3972,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return { id, tombstoneBlocked, ...(fm.blockedBy ? { blockedBy: fm.blockedBy } : {}), memory: { path: filePath, frontmatter: fm, content: sanitized.text } };
   }
 
-  /**
-   * Sealed-envelope write entry point (issue #1989 PR2).
-   *
-   * Byte-identity with `writeMemory` is BY DELEGATION: the envelope-owned
-   * fields are unpacked into the exact `writeMemory` arguments a legacy
-   * caller would have passed, so the persisted output is produced by the
-   * same code path. The composer's `persistedBody` was assembled with the
-   * same `assemblePersistedBody` helper `writeMemory` uses, so fingerprints
-   * derived from the envelope match the stored body (§13).
-   *
-   * Differences from a raw `writeMemory` call are REJECTIONS, not silent
-   * changes: the composer enforces tag/attribute caps, strict validAt, and
-   * plain-object attributes that the legacy path never validated.
-   *
-   * `envelope.ttl` maps to `expiresAt` verbatim; converting duration
-   * expressions (`"90d"`) to instants remains the access layer's job (PR3).
-   * `envelope.sourceReason` is access-layer metadata with no frontmatter
-   * field and is deliberately not persisted here.
-   */
+  /** Sealed-envelope write entry point (issue #1989 PR2). */
   async writeSealedMemory(envelope: SealedMemoryEnvelope, extras: SealedWriteExtras = {}) {
     if (!isSealedMemoryEnvelope(envelope)) {
       throw new Error(
@@ -3999,7 +3980,17 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       );
     }
     const { category, content, options } = sealedWriteToLegacyArgs(envelope, extras);
-    return this.writeMemory(category, content, options as WriteMemoryOptions);
+    const result = await this.writeMemory(category, content, options as WriteMemoryOptions);
+    try {
+      await refreshDirectorySidecarsAfterWrite(
+        this.dir,
+        result.memory?.path ?? "",
+        isDirectorySidecarsEnabledForDir(this.dir),
+      );
+    } catch (err) {
+      log.warn(`directory sidecar refresh failed after write: ${err}`);
+    }
+    return result;
   }
 
   async hasFactContentHash(content: string): Promise<boolean> {

package/src/types.ts

@@ -996,12 +996,12 @@ export interface PluginConfig
   recallDirectAnswerEnabled: boolean;
   /** Recall state views (issue #1952): label current/historical/transition on change-intent queries. Default false. */
   recallStateViews: boolean;
-  /** Standing memory block (issue #2971): byte-stable pinned-memory index injected before per-turn recall; parsed now, injection lands in a later slice. Default false. */
+  /** Standing memory block (issue #2971). Default false. */
   recallStandingBlock: boolean;
-  /** Days a memory stays in the standing block's full-text fresh band. Default 14. */
   standingBlockFreshDays: number;
-  /** Hard character budget for the standing memory block. Default 2048. */
   standingBlockMaxChars: number;
+  /** Directory sidecars (issue #3088). Default false. */
+  directorySidecarsEnabled: boolean;
   /**
    * Disclosure auto-escalation policy (issue #677 PR 4/4).  `"auto"`
    * escalates chunk → section when top-K confidence falls below