@remnic/core 1.1.31 → 9.3.516

package/src/access-service-namespace.test.ts

@@ -186,27 +186,25 @@ test("offlineSyncFiles reports symlink requested paths as input errors", async (
   }
 });
 
-test("offlineSyncSnapshot ignores client capture time for server fast-base scans", async () => {
+test("offlineSyncSnapshot does not trust client base capture time for server fast-base scans", async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-snapshot-client-clock-"));
   try {
     const relPath = "facts/a.md";
     const filePath = path.join(root, relPath);
-    const oldContent = Buffer.from("alpha");
-    const newContent = Buffer.from("bravo");
+    const content = Buffer.from("alpha");
     const mtimeMs = 1_700_000_000_000;
     await mkdir(path.dirname(filePath), { recursive: true });
-    await writeFile(filePath, oldContent);
+    await writeFile(filePath, content);
     await utimes(filePath, mtimeMs / 1000, mtimeMs / 1000);
     const baseFile = {
       path: relPath,
-      sha256: createHash("sha256").update(oldContent).digest("hex"),
-      bytes: oldContent.byteLength,
+      sha256: createHash("sha256").update(content).digest("hex"),
+      bytes: content.byteLength,
       mtimeMs,
     };
-    await writeFile(filePath, newContent);
-    await utimes(filePath, mtimeMs / 1000, mtimeMs / 1000);
 
     const { service } = makeService();
+    let digestReads = 0;
     (service as unknown as {
       orchestrator: {
         config: PluginConfig;
@@ -218,6 +216,7 @@ test("offlineSyncSnapshot ignores client capture time for server fast-base scans
         return readFile(targetPath);
       },
       async digestOfflineSyncFile(targetPath: string) {
+        digestReads += 1;
         const content = await readFile(targetPath);
         return {
           sha256: createHash("sha256").update(content).digest("hex"),
@@ -234,7 +233,8 @@ test("offlineSyncSnapshot ignores client capture time for server fast-base scans
       baseCapturedAt: new Date(Date.now() + 60_000),
     });
 
-    assert.equal(snapshot.files[0]?.sha256, createHash("sha256").update(newContent).digest("hex"));
+    assert.equal(digestReads, 1);
+    assert.deepEqual(snapshot.files, [baseFile]);
   } finally {
     await rm(root, { recursive: true, force: true });
   }

package/src/access-service-project-tag.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { EngramAccessService } from "./access-service.js";
+import { projectTagProjectId } from "./coding/coding-namespace.js";
+import type { CodingContext } from "./types.js";
+
+test("projectTag auto-resolution uses the shared project tag canonicalizer", async () => {
+  const contexts = new Map<string, CodingContext>();
+  const service = new EngramAccessService({
+    config: {
+      memoryDir: "/tmp/remnic-access-service-project-tag-test",
+      recallCrossNamespaceBudgetEnabled: false,
+      recallCrossNamespaceBudgetWindowMs: 60_000,
+      recallCrossNamespaceBudgetSoftLimit: 10,
+      recallCrossNamespaceBudgetHardLimit: 30,
+      codingMode: {
+        projectScope: true,
+      },
+    },
+    getCodingContextForSession: (sessionKey: string) => contexts.get(sessionKey) ?? null,
+    setCodingContextForSession: (sessionKey: string, context: CodingContext) => {
+      contexts.set(sessionKey, context);
+    },
+  } as any);
+
+  await (service as any).maybeAttachCodingContext("session-a", {
+    projectTag: "Blend/Supply",
+  });
+
+  const projectId = projectTagProjectId("Blend/Supply");
+  assert.deepEqual(contexts.get("session-a"), {
+    projectId,
+    branch: null,
+    rootPath: projectId,
+    defaultBranch: null,
+  });
+});

package/src/access-service.ts

@@ -7,6 +7,7 @@ import { AccessIdempotencyStore, hashAccessIdempotencyPayload } from "./access-i
 import { AccessAuditAdapter, type AccessAuditConfig, type AccessAuditResult } from "./access-audit.js";
 import type { AnomalyDetectorResult } from "./recall-audit-anomaly.js";
 import { resolveGitContext } from "./coding/git-context.js";
+import { projectTagProjectId } from "./coding/coding-namespace.js";
 import { WorkStorage } from "./work/storage.js";
 import {
   exportWorkBoardMarkdown,
@@ -809,6 +810,7 @@ export interface EngramAccessObserveResponse {
 export interface EngramAccessLcmSearchRequest {
   query: string;
   sessionKey?: string;
+  sessionPrefix?: string;
   namespace?: string;
   limit?: number;
   authenticatedPrincipal?: string;
@@ -1721,11 +1723,11 @@ export class EngramAccessService {
     if (this.orchestrator.getCodingContextForSession(sessionKey)) return;
     // projectTag takes priority over cwd.
     if (typeof options.projectTag === "string" && options.projectTag.trim().length > 0) {
-      const tag = options.projectTag.trim();
+      const projectId = projectTagProjectId(options.projectTag);
       this.orchestrator.setCodingContextForSession(sessionKey, {
-        projectId: `tag:${tag}`,
+        projectId,
         branch: null,
-        rootPath: `tag:${tag}`,
+        rootPath: projectId,
         defaultBranch: null,
       });
       return;
@@ -3910,10 +3912,14 @@ export class EngramAccessService {
     const lcmSessionKey = request.sessionKey && namespace !== this.orchestrator.config.defaultNamespace
       ? `${namespace}:${request.sessionKey}`
       : request.sessionKey;
+    const lcmSessionPrefix = request.sessionPrefix && namespace !== this.orchestrator.config.defaultNamespace
+      ? `${namespace}:${request.sessionPrefix}`
+      : request.sessionPrefix;
     const rawResults = await this.orchestrator.lcmEngine.searchContextFull(
       request.query,
       limit,
       lcmSessionKey,
+      lcmSessionPrefix,
     );
 
     const results = rawResults.map((r: { session_id: string; content: string; turn_index: number }) => ({
@@ -4611,13 +4617,8 @@ export class EngramAccessService {
     const resolvedNs = this.resolveReadableNamespace(namespace, principal);
     const namespaceFilter = resolvedNs !== this.orchestrator.config.defaultNamespace ? resolvedNs : undefined;
 
-    const results = collection === "global"
-      ? (await this.orchestrator.qmd.searchGlobal(query, maxResults)).filter((r) =>
-          namespaceFilter
-            ? r.path.includes(`/namespaces/${namespaceFilter}/`) ||
-              (!r.path.includes("/namespaces/") && namespaceFilter === this.orchestrator.config.defaultNamespace)
-            : true,
-        )
+    const results = collection === "global" && !namespaceFilter
+      ? await this.orchestrator.qmd.searchGlobal(query, maxResults)
       : await this.orchestrator.searchAcrossNamespaces({
           query,
           namespaces: namespaceFilter ? [namespaceFilter] : undefined,
@@ -5610,7 +5611,7 @@ export class EngramAccessService {
   }
 
   async offlineSyncSnapshot(
-    options: EngramAccessOfflineSyncSnapshotRequest = {},
+    options: EngramAccessOfflineSyncSnapshotRequest & { signal?: AbortSignal } = {},
   ): Promise<EngramAccessOfflineSyncSnapshotResponse> {
     const resolvedNamespace = this.resolveReadableNamespace(options.namespace, options.principal);
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
@@ -5622,12 +5623,11 @@ export class EngramAccessService {
       root: storage.dir,
       sourceId: `remnic:${resolvedNamespace}:${storageHash}`,
       ...(options.baseFiles && options.baseFiles.length > 0 ? { baseFiles: options.baseFiles } : {}),
-      // Client clocks are not authoritative for server-side ctime reuse. A
-      // future client timestamp can hide same-size, preserved-mtime rewrites.
       includeContent: options.includeContent !== false,
       includeTranscripts: options.includeTranscripts !== false,
       readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
       readFileDigest: async ({ filePath }) => storage.digestOfflineSyncFile(filePath),
+      signal: options.signal,
     });
     return {
       namespace: resolvedNamespace,
@@ -5636,7 +5636,7 @@ export class EngramAccessService {
   }
 
   async offlineSyncSnapshotStream(
-    options: Omit<EngramAccessOfflineSyncSnapshotRequest, "baseCapturedAt" | "baseFiles"> = {},
+    options: Omit<EngramAccessOfflineSyncSnapshotRequest, "baseCapturedAt" | "baseFiles"> & { signal?: AbortSignal } = {},
   ): Promise<EngramAccessOfflineSyncSnapshotStreamResponse> {
     const resolvedNamespace = this.resolveReadableNamespace(options.namespace, options.principal);
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
@@ -5654,6 +5654,7 @@ export class EngramAccessService {
         includeTranscripts: options.includeTranscripts !== false,
         readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
         readFileDigest: async ({ filePath }) => storage.digestOfflineSyncFile(filePath),
+        signal: options.signal,
       }),
     };
   }

package/src/active-recall.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdtemp, readFile } from "node:fs/promises";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -452,6 +452,34 @@ test("active recall transcript persistence sanitizes agent and session path segm
   assert.match(raw, /"sessionKey":"session\/\.\.\/\.\.\/escape"/);
 });
 
+test("active recall transcript persistence failures do not abort generated summaries", async () => {
+  const transcriptFile = path.join(
+    await mkdtemp(path.join(os.tmpdir(), "active-recall-transcript-file-")),
+    "not-a-directory",
+  );
+  await writeFile(transcriptFile, "existing file", "utf8");
+  const engine = createActiveRecallEngine(
+    {
+      async recall() {
+        return "Primary recall";
+      },
+      async generateSummary() {
+        return { text: "useful summary", modelUsed: "gpt-5.5" };
+      },
+    },
+    baseConfig({
+      persistTranscripts: true,
+      transcriptDir: transcriptFile,
+    }),
+  );
+
+  const result = await engine.run(baseInput());
+
+  assert.equal(result.summary, "useful summary");
+  assert.equal(result.modelUsed, "gpt-5.5");
+  assert.equal(result.transcriptPath, null);
+});
+
 test("active recall transcript persistence encodes bare dot path segments", async () => {
   const transcriptDir = await mkdtemp(path.join(os.tmpdir(), "active-recall-transcript-"));
   const engine = createActiveRecallEngine(

package/src/active-recall.ts

@@ -436,13 +436,17 @@ export function createActiveRecallEngine(
         transcriptPath: null,
       };
       if (config.persistTranscripts) {
-        result.transcriptPath = await appendActiveRecallTranscript(
-          config.transcriptDir,
-          input,
-          config,
-          result,
-          queryBundle,
-        );
+        try {
+          result.transcriptPath = await appendActiveRecallTranscript(
+            config.transcriptDir,
+            input,
+            config,
+            result,
+            queryBundle,
+          );
+        } catch {
+          result.transcriptPath = null;
+        }
       }
 
       if (cacheEnabled) {

package/src/adapters/claude-code.ts

@@ -11,9 +11,13 @@ import { headerValue, type AdapterContext, type EngramAdapter, type ResolvedIden
  * For HTTP REST (non-MCP) requests, detection relies on User-Agent or
  * user-configured X-Engram-Client-Id header in .claude.json headers.
  *
- * Namespace/principal can be set by configuring custom headers in
+ * Namespace can be set by configuring custom headers in
  * .claude.json or .mcp.json:
- *   "headers": { "X-Engram-Namespace": "my-project", "X-Engram-Principal": "my-team" }
+ *   "headers": { "X-Engram-Namespace": "my-project" }
+ *
+ * Principal overrides are intentionally handled only by the HTTP server's
+ * trustPrincipalHeader gate. Adapters must not independently trust
+ * X-Engram-Principal.
  */
 export class ClaudeCodeAdapter implements EngramAdapter {
   readonly id = "claude-code";
@@ -37,20 +41,15 @@ export class ClaudeCodeAdapter implements EngramAdapter {
     // MCP session ID (standard MCP header, server-assigned)
     const mcpSessionId = headerValue(context.headers, "mcp-session-id");
 
-    // Principal: explicit header > default
-    const principal = headerValue(context.headers, "x-engram-principal")
-      || "claude-code";
-
     // Namespace: explicit header > default
     const namespace = headerValue(context.headers, "x-engram-namespace")
       || "claude-code";
 
     return {
       namespace,
-      principal,
+      principal: "claude-code",
       sessionKey: mcpSessionId ?? context.sessionKey,
       adapterId: this.id,
     };
   }
 }
-

package/src/adapters/codex.ts

@@ -11,7 +11,11 @@ import { headerValue, type AdapterContext, type EngramAdapter, type ResolvedIden
  * http_headers in ~/.codex/config.toml:
  *   [mcp_servers.engram]
  *   url = "http://localhost:4318/mcp"
- *   http_headers = { "X-Engram-Namespace" = "my-project", "X-Engram-Principal" = "codex-agent" }
+ *   http_headers = { "X-Engram-Namespace" = "my-project" }
+ *
+ * Principal overrides are intentionally handled only by the HTTP server's
+ * trustPrincipalHeader gate. Adapters must not independently trust
+ * X-Engram-Principal.
  *
  * Codex also sends a custom "sandbox_state" RPC notification after
  * init with sandbox policy info (read-only/writable paths).
@@ -38,20 +42,15 @@ export class CodexAdapter implements EngramAdapter {
     // MCP session ID (standard MCP header, server-assigned)
     const mcpSessionId = headerValue(context.headers, "mcp-session-id");
 
-    // Principal: explicit header > default
-    const principal = headerValue(context.headers, "x-engram-principal")
-      || "codex";
-
     // Namespace: explicit header > default
     const namespace = headerValue(context.headers, "x-engram-namespace")
       || "codex";
 
     return {
       namespace,
-      principal,
+      principal: "codex",
       sessionKey: mcpSessionId ?? context.sessionKey,
       adapterId: this.id,
     };
   }
 }
-

package/src/adapters/hermes.ts

@@ -47,18 +47,14 @@ export class HermesAdapter implements EngramAdapter {
   resolveIdentity(context: AdapterContext): ResolvedIdentity {
     const sessionId = headerValue(context.headers, "x-hermes-session-id");
 
-    const principal = headerValue(context.headers, "x-engram-principal")
-      || "hermes-agent";
-
     const namespace = headerValue(context.headers, "x-engram-namespace")
       || "hermes";
 
     return {
       namespace,
-      principal,
+      principal: "hermes-agent",
       sessionKey: sessionId ?? context.sessionKey,
       adapterId: this.id,
     };
   }
 }
-

package/src/adapters/registry.test.ts

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { AdapterRegistry } from "./registry.js";
+import type { AdapterContext, EngramAdapter } from "./types.js";
+
+test("adapter registry falls back to explicit request identity when no adapter matches", () => {
+  const registry = new AdapterRegistry([]);
+
+  assert.deepEqual(
+    registry.resolve({
+      headers: {},
+      namespace: " project-a ",
+      principal: " user-1 ",
+      sessionKey: "session-1",
+    }),
+    {
+      namespace: "project-a",
+      principal: "user-1",
+      sessionKey: "session-1",
+      adapterId: "explicit",
+    },
+  );
+});
+
+test("adapter registry requires complete explicit identity fallback", () => {
+  const registry = new AdapterRegistry([]);
+
+  assert.equal(registry.resolve({ headers: {}, sessionKey: "session-1" }), null);
+  assert.equal(registry.resolve({ headers: {}, namespace: "project-a" }), null);
+  assert.equal(registry.resolve({ headers: {}, principal: "user-1" }), null);
+});
+
+test("adapter registry prefers matching adapters over explicit fallback", () => {
+  const adapter: EngramAdapter = {
+    id: "test-adapter",
+    matches(context: AdapterContext) {
+      return context.headers["x-test"] === "yes";
+    },
+    resolveIdentity() {
+      return {
+        namespace: "adapter-namespace",
+        principal: "adapter-principal",
+        adapterId: "test-adapter",
+      };
+    },
+  };
+
+  const registry = new AdapterRegistry([adapter]);
+
+  assert.deepEqual(
+    registry.resolve({
+      headers: { "x-test": "yes" },
+      namespace: "explicit-namespace",
+      principal: "explicit-principal",
+    }),
+    {
+      namespace: "adapter-namespace",
+      principal: "adapter-principal",
+      adapterId: "test-adapter",
+    },
+  );
+});

package/src/adapters/registry.ts

@@ -31,6 +31,16 @@ export class AdapterRegistry {
         return adapter.resolveIdentity(context);
       }
     }
+    const namespace = context.namespace?.trim();
+    const principal = context.principal?.trim();
+    if (namespace && principal) {
+      return {
+        namespace,
+        principal,
+        sessionKey: context.sessionKey,
+        adapterId: "explicit",
+      };
+    }
     return null;
   }
 

package/src/adapters/replit.ts

@@ -16,8 +16,10 @@ import { headerValue, type AdapterContext, type EngramAdapter, type ResolvedIden
  *   Header Name: X-Engram-Client-Id
  *   Header Value: replit
  *
- * Optionally also set X-Engram-Namespace and X-Engram-Principal for
- * project/user scoping.
+ * Optionally also set X-Engram-Namespace for project scoping. Principal
+ * overrides are intentionally handled only by the HTTP server's
+ * trustPrincipalHeader gate. Adapters must not independently trust
+ * X-Engram-Principal.
  */
 export class ReplitAdapter implements EngramAdapter {
   readonly id = "replit";
@@ -38,18 +40,14 @@ export class ReplitAdapter implements EngramAdapter {
   resolveIdentity(context: AdapterContext): ResolvedIdentity {
     const mcpSessionId = headerValue(context.headers, "mcp-session-id");
 
-    const principal = headerValue(context.headers, "x-engram-principal")
-      || "replit-agent";
-
     const namespace = headerValue(context.headers, "x-engram-namespace")
       || "replit";
 
     return {
       namespace,
-      principal,
+      principal: "replit-agent",
       sessionKey: mcpSessionId ?? context.sessionKey,
       adapterId: this.id,
     };
   }
 }
-

package/src/adapters/types.ts

@@ -13,6 +13,10 @@ export interface AdapterContext {
   clientInfo?: { name: string; version?: string };
   /** Explicit session key from request args */
   sessionKey?: string;
+  /** Explicit namespace from already-validated request args */
+  namespace?: string;
+  /** Explicit principal from already-validated request args */
+  principal?: string;
 }
 
 export interface ResolvedIdentity {
@@ -45,7 +49,26 @@ export function headerValue(
   headers: Record<string, string | string[] | undefined>,
   key: string,
 ): string | undefined {
-  const raw = headers[key];
+  const exactValue = normalizeHeaderValue(headers[key]);
+  if (exactValue !== undefined) {
+    return exactValue;
+  }
+
+  const normalizedKey = key.toLowerCase();
+  for (const [headerKey, raw] of Object.entries(headers)) {
+    if (headerKey.toLowerCase() !== normalizedKey) {
+      continue;
+    }
+    const value = normalizeHeaderValue(raw);
+    if (value !== undefined) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+function normalizeHeaderValue(raw: string | string[] | undefined): string | undefined {
   const value = Array.isArray(raw) ? raw[0] : raw;
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
 }

package/src/behavior-signals.ts

@@ -64,7 +64,7 @@ export function dedupeBehaviorSignalsByMemoryAndHash(
   const seen = new Set<string>();
   const out: BehaviorSignalEvent[] = [];
   for (const signal of signals) {
-    const key = `${signal.memoryId}:${signal.signalHash}`;
+    const key = `${signal.namespace}:${signal.memoryId}:${signal.signalHash}`;
     if (seen.has(key)) continue;
     seen.add(key);
     out.push(signal);

package/src/binary-lifecycle/backend.ts

@@ -41,11 +41,23 @@ export class FilesystemBackend implements BinaryStorageBackend {
     if (!basePath || basePath.trim().length === 0) {
       throw new Error("FilesystemBackend requires a non-empty basePath");
     }
-    this.basePath = basePath;
+    this.basePath = path.resolve(basePath);
+  }
+
+  private resolveRemotePath(remotePath: string): string {
+    if (path.isAbsolute(remotePath)) {
+      throw new Error(`FilesystemBackend remotePath must be relative: ${JSON.stringify(remotePath)}`);
+    }
+    const resolved = path.resolve(this.basePath, remotePath);
+    const relative = path.relative(this.basePath, resolved);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+      throw new Error(`FilesystemBackend remotePath escapes basePath: ${JSON.stringify(remotePath)}`);
+    }
+    return resolved;
   }
 
   async upload(localPath: string, remotePath: string): Promise<string> {
-    const dest = path.join(this.basePath, remotePath);
+    const dest = this.resolveRemotePath(remotePath);
     const destDir = path.dirname(dest);
     await fsp.mkdir(destDir, { recursive: true });
     await fsp.copyFile(localPath, dest);
@@ -53,7 +65,7 @@ export class FilesystemBackend implements BinaryStorageBackend {
   }
 
   async exists(remotePath: string): Promise<boolean> {
-    const dest = path.join(this.basePath, remotePath);
+    const dest = this.resolveRemotePath(remotePath);
     try {
       await fsp.access(dest, fs.constants.F_OK);
       return true;
@@ -63,7 +75,7 @@ export class FilesystemBackend implements BinaryStorageBackend {
   }
 
   async delete(remotePath: string): Promise<void> {
-    const dest = path.join(this.basePath, remotePath);
+    const dest = this.resolveRemotePath(remotePath);
     try {
       await fsp.unlink(dest);
     } catch (err: unknown) {