@remnic/core 1.1.15 → 1.1.17

package/dist/mcp-memory-inspector-app.d.ts

@@ -1,4 +1,4 @@
-import { a as EngramAccessRecallResponse } from './access-service-BCMine1s.js';
+import { a as EngramAccessRecallResponse } from './access-service-DZXc7qwR.js';
 import { ActionConfidenceRequest } from './access-schema.js';
 import { RecallXraySnapshot } from './recall-xray.js';
 import { ActionConfidenceResult } from './action-confidence.js';

package/dist/offline-sync.d.ts

@@ -95,6 +95,15 @@ declare function buildOfflineSyncSnapshot(options: {
     now?: Date;
     readFile?: (target: OfflineSyncFileTarget) => Promise<Buffer>;
 }): Promise<OfflineSyncSnapshot>;
+declare function buildOfflineSyncSnapshotForPaths(options: {
+    root: string;
+    sourceId: string;
+    paths: readonly string[];
+    includeContent?: boolean;
+    includeTranscripts?: boolean;
+    now?: Date;
+    readFile?: (target: OfflineSyncFileTarget) => Promise<Buffer>;
+}): Promise<OfflineSyncSnapshot>;
 declare function buildOfflineSyncChangeset(options: {
     root: string;
     sourceId: string;
@@ -133,4 +142,4 @@ declare function offlineSyncStateFromSnapshot(options: {
 declare function normalizeOfflineSyncState(input: unknown): OfflineSyncState;
 declare function fileStatesFromSnapshot(snapshot: OfflineSyncSnapshot): OfflineSyncFileState[];
 
-export { OFFLINE_SYNC_CHANGESET_FORMAT, OFFLINE_SYNC_SNAPSHOT_FORMAT, OFFLINE_SYNC_STATE_VERSION, type OfflineSyncApplyChangesetResult, type OfflineSyncApplySnapshotResult, type OfflineSyncChange, type OfflineSyncChangeset, type OfflineSyncChangesetSummary, type OfflineSyncConflict, type OfflineSyncFileRecord, type OfflineSyncFileState, type OfflineSyncFileTarget, type OfflineSyncFileWriteTarget, type OfflineSyncSnapshot, type OfflineSyncState, applyOfflineSyncChangeset, applyOfflineSyncSnapshot, buildOfflineSyncChangeset, buildOfflineSyncSnapshot, defaultOfflineSyncStatePath, fileStatesFromSnapshot, normalizeOfflineSyncChangeset, normalizeOfflineSyncSnapshot, normalizeOfflineSyncState, offlineSyncStateFromSnapshot, readOfflineSyncState, summarizeOfflineSyncChangeset, writeOfflineSyncState };
+export { OFFLINE_SYNC_CHANGESET_FORMAT, OFFLINE_SYNC_SNAPSHOT_FORMAT, OFFLINE_SYNC_STATE_VERSION, type OfflineSyncApplyChangesetResult, type OfflineSyncApplySnapshotResult, type OfflineSyncChange, type OfflineSyncChangeset, type OfflineSyncChangesetSummary, type OfflineSyncConflict, type OfflineSyncFileRecord, type OfflineSyncFileState, type OfflineSyncFileTarget, type OfflineSyncFileWriteTarget, type OfflineSyncSnapshot, type OfflineSyncState, applyOfflineSyncChangeset, applyOfflineSyncSnapshot, buildOfflineSyncChangeset, buildOfflineSyncSnapshot, buildOfflineSyncSnapshotForPaths, defaultOfflineSyncStatePath, fileStatesFromSnapshot, normalizeOfflineSyncChangeset, normalizeOfflineSyncSnapshot, normalizeOfflineSyncState, offlineSyncStateFromSnapshot, readOfflineSyncState, summarizeOfflineSyncChangeset, writeOfflineSyncState };

package/dist/offline-sync.js

@@ -6,6 +6,7 @@ import {
   applyOfflineSyncSnapshot,
   buildOfflineSyncChangeset,
   buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotForPaths,
   defaultOfflineSyncStatePath,
   fileStatesFromSnapshot,
   normalizeOfflineSyncChangeset,
@@ -15,7 +16,7 @@ import {
   readOfflineSyncState,
   summarizeOfflineSyncChangeset,
   writeOfflineSyncState
-} from "./chunk-GSP6ZKOY.js";
+} from "./chunk-HMZYQPT5.js";
 import "./chunk-P7FMDTKL.js";
 import "./chunk-I6K5FBRQ.js";
 import "./chunk-AGZQD76C.js";
@@ -28,6 +29,7 @@ export {
   applyOfflineSyncSnapshot,
   buildOfflineSyncChangeset,
   buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotForPaths,
   defaultOfflineSyncStatePath,
   fileStatesFromSnapshot,
   normalizeOfflineSyncChangeset,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",

package/src/access-http.test.ts

@@ -286,6 +286,79 @@ test("HTTP offline snapshot forwards namespace and transfer options", async () =
   }
 });
 
+test("HTTP offline files forwards namespace and requested paths", async () => {
+  const calls: Array<{
+    namespace: string | undefined;
+    principal: string | undefined;
+    includeTranscripts: boolean | undefined;
+    paths: string[];
+  }> = [];
+  const service = {
+    offlineSyncFiles: async (options: {
+      namespace?: string;
+      principal?: string;
+      includeTranscripts?: boolean;
+      paths: string[];
+    }) => {
+      calls.push({
+        namespace: options.namespace,
+        principal: options.principal,
+        includeTranscripts: options.includeTranscripts,
+        paths: options.paths,
+      });
+      return {
+        namespace: options.namespace ?? "default",
+        format: "remnic.offline-sync.snapshot.v1",
+        schemaVersion: 1,
+        createdAt: new Date("2026-05-21T00:00:00Z").toISOString(),
+        sourceId: "remote:test",
+        includeTranscripts: options.includeTranscripts !== false,
+        files: [],
+      };
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    principal: "reader",
+    adminConsoleEnabled: false,
+  });
+
+  const status = await server.start();
+  try {
+    const response = await fetch(
+      `http://127.0.0.1:${status.port}/remnic/v1/offline-sync/files`,
+      {
+        method: "POST",
+        headers: {
+          authorization: "Bearer test-token",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          namespace: "team",
+          includeTranscripts: false,
+          paths: ["facts/a.md"],
+        }),
+      },
+    );
+    const body = await response.json() as { namespace?: string; includeTranscripts?: boolean; files?: unknown[] };
+
+    assert.equal(response.status, 200);
+    assert.equal(body.namespace, "team");
+    assert.equal(body.includeTranscripts, false);
+    assert.deepEqual(body.files, []);
+    assert.deepEqual(calls, [{
+      namespace: "team",
+      principal: "reader",
+      includeTranscripts: false,
+      paths: ["facts/a.md"],
+    }]);
+  } finally {
+    await server.stop();
+  }
+});
+
 test("HTTP offline snapshot rejects invalid boolean query values", async () => {
   let calls = 0;
   const service = {

package/src/access-http.ts

@@ -626,6 +626,21 @@ export class EngramAccessHttpServer {
       return;
     }
 
+    if (
+      req.method === "POST" &&
+      (pathname === "/engram/v1/offline-sync/files" || pathname === "/remnic/v1/offline-sync/files")
+    ) {
+      const body = await this.readValidatedBody(req, "offlineSyncFiles");
+      const result = await this.service.offlineSyncFiles({
+        namespace: this.resolveNamespace(req, body.namespace),
+        principal: this.resolveRequestPrincipal(req),
+        includeTranscripts: body.includeTranscripts,
+        paths: body.paths,
+      });
+      this.respondJson(res, 200, result);
+      return;
+    }
+
     if (
       req.method === "POST" &&
       (pathname === "/engram/v1/offline-sync/apply" || pathname === "/remnic/v1/offline-sync/apply")

package/src/access-schema.ts

@@ -378,6 +378,14 @@ export const offlineSyncApplyRequestSchema = z
     path: ["changeset"],
   });
 
+export const offlineSyncFilesRequestSchema = z.object({
+  namespace: namespaceSchema,
+  includeTranscripts: z.boolean().optional(),
+  paths: z
+    .array(z.string().trim().min(1, "path must be non-empty").max(4096))
+    .max(5000, "paths must contain 5000 or fewer entries"),
+});
+
 // ---------------------------------------------------------------------------
 // Action confidence
 // ---------------------------------------------------------------------------
@@ -444,6 +452,7 @@ export type CapsuleExportRequest = z.infer<typeof capsuleExportRequestSchema>;
 export type CapsuleImportRequest = z.infer<typeof capsuleImportRequestSchema>;
 export type CapsuleListRequest = z.infer<typeof capsuleListRequestSchema>;
 export type OfflineSyncApplyRequest = z.infer<typeof offlineSyncApplyRequestSchema>;
+export type OfflineSyncFilesRequest = z.infer<typeof offlineSyncFilesRequestSchema>;
 export type ActionConfidenceRequest = z.infer<typeof actionConfidenceRequestSchema>;
 
 // ---------------------------------------------------------------------------
@@ -467,6 +476,7 @@ export type SchemaName =
   | "capsuleExport"
   | "capsuleImport"
   | "capsuleList"
+  | "offlineSyncFiles"
   | "offlineSyncApply"
   | "actionConfidence";
 
@@ -487,6 +497,7 @@ export type SchemaTypeFor<N extends SchemaName> =
   : N extends "capsuleExport" ? CapsuleExportRequest
   : N extends "capsuleImport" ? CapsuleImportRequest
   : N extends "capsuleList" ? CapsuleListRequest
+  : N extends "offlineSyncFiles" ? OfflineSyncFilesRequest
   : N extends "offlineSyncApply" ? OfflineSyncApplyRequest
   : N extends "actionConfidence" ? ActionConfidenceRequest
   : never;
@@ -508,6 +519,7 @@ const schemas: Record<SchemaName, z.ZodTypeAny> = {
   capsuleExport: capsuleExportRequestSchema,
   capsuleImport: capsuleImportRequestSchema,
   capsuleList: capsuleListRequestSchema,
+  offlineSyncFiles: offlineSyncFilesRequestSchema,
   offlineSyncApply: offlineSyncApplyRequestSchema,
   actionConfidence: actionConfidenceRequestSchema,
 };

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

@@ -1,7 +1,10 @@
 import assert from "node:assert/strict";
+import { mkdtemp, rm, symlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import test from "node:test";
 
-import { EngramAccessService } from "./access-service.js";
+import { EngramAccessInputError, EngramAccessService } from "./access-service.js";
 import type { StorageManager } from "./storage.js";
 import type { PluginConfig } from "./types.js";
 
@@ -121,3 +124,63 @@ test("memoryBrowse resolves namespace storage for read principals", async () =>
   assert.equal(result.count, 0);
   assert.deepEqual(getStorageCalls, ["team"]);
 });
+
+test("offlineSyncFiles reports invalid requested paths as input errors", async () => {
+  const { service } = makeService();
+  (service as unknown as {
+    orchestrator: {
+      config: PluginConfig;
+      getStorage(namespace: string): Promise<StorageManager>;
+    };
+  }).orchestrator.getStorage = async () => ({
+    dir: os.tmpdir(),
+    async readOfflineSyncFile() {
+      throw new Error("should not read invalid paths");
+    },
+  } as unknown as StorageManager);
+
+  await assert.rejects(
+    () =>
+      service.offlineSyncFiles({
+        namespace: "team",
+        principal: "reader",
+        paths: ["../escape"],
+      }),
+    (error: unknown) =>
+      error instanceof EngramAccessInputError &&
+      /paths\[\]: record path contains unsafe segments/.test(error.message),
+  );
+});
+
+test("offlineSyncFiles reports symlink requested paths as input errors", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-files-symlink-"));
+  try {
+    await symlink("/tmp", path.join(root, "linked"));
+    const { service } = makeService();
+    (service as unknown as {
+      orchestrator: {
+        config: PluginConfig;
+        getStorage(namespace: string): Promise<StorageManager>;
+      };
+    }).orchestrator.getStorage = async () => ({
+      dir: root,
+      async readOfflineSyncFile() {
+        throw new Error("should not read symlink paths");
+      },
+    } as unknown as StorageManager);
+
+    await assert.rejects(
+      () =>
+        service.offlineSyncFiles({
+          namespace: "team",
+          principal: "reader",
+          paths: ["linked"],
+        }),
+      (error: unknown) =>
+        error instanceof EngramAccessInputError &&
+        /buildOfflineSyncSnapshotForPaths: record path targets a symlink/.test(error.message),
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/access-service.ts

@@ -138,6 +138,7 @@ import {
 import {
   applyOfflineSyncChangeset,
   buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotForPaths,
   type OfflineSyncApplyChangesetResult,
   type OfflineSyncSnapshot,
 } from "./offline-sync.js";
@@ -616,6 +617,13 @@ export interface EngramAccessOfflineSyncSnapshotRequest {
   includeContent?: boolean;
 }
 
+export interface EngramAccessOfflineSyncFilesRequest {
+  namespace?: string;
+  principal?: string;
+  includeTranscripts?: boolean;
+  paths: string[];
+}
+
 export interface EngramAccessOfflineSyncApplyRequest {
   namespace?: string;
   principal?: string;
@@ -626,6 +634,10 @@ export interface EngramAccessOfflineSyncSnapshotResponse extends OfflineSyncSnap
   namespace: string;
 }
 
+export interface EngramAccessOfflineSyncFilesResponse extends OfflineSyncSnapshot {
+  namespace: string;
+}
+
 export interface EngramAccessOfflineSyncApplyResponse extends OfflineSyncApplyChangesetResult {
   namespace: string;
 }
@@ -5568,6 +5580,38 @@ export class EngramAccessService {
     };
   }
 
+  async offlineSyncFiles(
+    options: EngramAccessOfflineSyncFilesRequest,
+  ): Promise<EngramAccessOfflineSyncFilesResponse> {
+    const resolvedNamespace = this.resolveReadableNamespace(options.namespace, options.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const storageHash = createHash("sha256").update(storage.dir).digest("hex").slice(0, 16);
+    try {
+      const snapshot = await buildOfflineSyncSnapshotForPaths({
+        root: storage.dir,
+        sourceId: `remnic:${resolvedNamespace}:${storageHash}`,
+        paths: options.paths,
+        includeContent: true,
+        includeTranscripts: options.includeTranscripts !== false,
+        readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
+      });
+      return {
+        namespace: resolvedNamespace,
+        ...snapshot,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (
+        message.startsWith("paths[]:") ||
+        message.startsWith("buildOfflineSyncSnapshotForPaths: record path ") ||
+        message.startsWith("offline sync snapshot path is excluded:")
+      ) {
+        throw new EngramAccessInputError(message);
+      }
+      throw error;
+    }
+  }
+
   async offlineSyncApply(
     options: EngramAccessOfflineSyncApplyRequest,
   ): Promise<EngramAccessOfflineSyncApplyResponse> {

package/src/index.ts

@@ -686,6 +686,7 @@ export {
   applyOfflineSyncSnapshot,
   buildOfflineSyncChangeset,
   buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotForPaths,
   defaultOfflineSyncStatePath,
   fileStatesFromSnapshot,
   normalizeOfflineSyncChangeset,

package/src/offline-sync.test.ts

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -9,6 +10,7 @@ import {
   applyOfflineSyncSnapshot,
   buildOfflineSyncChangeset,
   buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotForPaths,
 } from "./offline-sync.js";
 import { isEncryptedFile } from "./secure-store/secure-fs.js";
 import { StorageManager } from "./storage.js";
@@ -38,6 +40,9 @@ test("offline snapshot captures source-of-truth files and excludes private/inter
     await write(root, ".offline-sync/state/local.json", "state");
     await write(root, "state/fact-hashes.txt", "derived");
     await write(root, "state/fact-hashes.ready", "v1");
+    await write(root, "state/lcm.sqlite", "live db");
+    await write(root, "state/lcm.sqlite-shm", "live shm");
+    await write(root, "state/lcm.sqlite-wal", "live wal");
 
     const snapshot = await buildOfflineSyncSnapshot({
       root,
@@ -67,6 +72,51 @@ test("offline snapshot captures source-of-truth files and excludes private/inter
   }
 });
 
+test("offline sync excludes live LCM sqlite artifacts without deleting existing local copies", async () => {
+  const root = await tempDir("remnic-offline-lcm-sqlite");
+  try {
+    await write(root, "facts/a.md", "alpha");
+    await write(root, "state/lcm.sqlite", "live db");
+    await write(root, "state/lcm.sqlite-shm", "live shm");
+    await write(root, "state/lcm.sqlite-wal", "live wal");
+
+    const snapshot = await buildOfflineSyncSnapshot({
+      root,
+      sourceId: "remote",
+      includeContent: true,
+    });
+
+    assert.deepEqual(snapshot.files.map((file) => file.path), ["facts/a.md"]);
+    await assert.rejects(
+      () =>
+        buildOfflineSyncSnapshotForPaths({
+          root,
+          sourceId: "remote",
+          paths: ["state/lcm.sqlite"],
+          includeContent: true,
+        }),
+      /offline sync snapshot path is excluded: state\/lcm\.sqlite/,
+    );
+
+    const oldDb = Buffer.from("old live db");
+    const pull = await applyOfflineSyncSnapshot({
+      root,
+      snapshot,
+      baseFiles: [{
+        path: "state/lcm.sqlite",
+        sha256: createHash("sha256").update(oldDb).digest("hex"),
+        bytes: oldDb.byteLength,
+        mtimeMs: 0,
+      }],
+    });
+
+    assert.equal(pull.deleted, 0);
+    assert.equal(await readUtf8(root, "state/lcm.sqlite"), "live db");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test("offline changeset pushes local edits when the remote is still at the shared base", async () => {
   const remote = await tempDir("remnic-offline-remote");
   const local = await tempDir("remnic-offline-local");
@@ -106,6 +156,130 @@ test("offline changeset pushes local edits when the remote is still at the share
   }
 });
 
+test("offline changeset only carries content for changed local files", async () => {
+  const local = await tempDir("remnic-offline-changeset-content");
+  try {
+    await write(local, "facts/unchanged.md", "same");
+    await write(local, "facts/changed.md", "before");
+    const base = await buildOfflineSyncSnapshot({
+      root: local,
+      sourceId: "remote",
+      includeContent: false,
+    });
+
+    await write(local, "facts/changed.md", "after");
+    await write(local, "facts/empty.md", "");
+    const changeset = await buildOfflineSyncChangeset({
+      root: local,
+      sourceId: "laptop",
+      baseFiles: base.files,
+    });
+
+    assert.deepEqual(
+      changeset.changes.map((change) => change.path),
+      ["facts/changed.md", "facts/empty.md"],
+    );
+    const empty = changeset.changes.find((change) => change.path === "facts/empty.md");
+    assert.equal(empty?.type, "upsert");
+    if (empty?.type === "upsert") {
+      assert.equal(empty.file.contentBase64, "");
+    }
+    assert.equal(JSON.stringify(changeset).includes("same"), false);
+  } finally {
+    await rm(local, { recursive: true, force: true });
+  }
+});
+
+test("offline pull accepts metadata-only snapshots when files are unchanged", async () => {
+  const remote = await tempDir("remnic-offline-metadata-remote");
+  const local = await tempDir("remnic-offline-metadata-local");
+  try {
+    await write(remote, "facts/shared.md", "base");
+    const initial = await buildOfflineSyncSnapshot({
+      root: remote,
+      sourceId: "remote",
+      includeContent: true,
+    });
+    const firstPull = await applyOfflineSyncSnapshot({
+      root: local,
+      snapshot: initial,
+    });
+    const metadataOnly = await buildOfflineSyncSnapshot({
+      root: remote,
+      sourceId: "remote",
+      includeContent: false,
+    });
+
+    const secondPull = await applyOfflineSyncSnapshot({
+      root: local,
+      snapshot: metadataOnly,
+      baseFiles: firstPull.nextBaseFiles,
+    });
+
+    assert.equal(secondPull.conflicts.length, 0);
+    assert.equal(secondPull.upserted, 0);
+    assert.equal(secondPull.skipped, 1);
+  } finally {
+    await rm(remote, { recursive: true, force: true });
+    await rm(local, { recursive: true, force: true });
+  }
+});
+
+test("offline pull applies snapshots with content only for remote-changed files", async () => {
+  const remote = await tempDir("remnic-offline-partial-remote");
+  const local = await tempDir("remnic-offline-partial-local");
+  try {
+    await write(remote, "facts/shared.md", "base");
+    await write(remote, "facts/stable.md", "unchanged");
+    const initial = await buildOfflineSyncSnapshot({
+      root: remote,
+      sourceId: "remote",
+      includeContent: true,
+    });
+    const firstPull = await applyOfflineSyncSnapshot({
+      root: local,
+      snapshot: initial,
+    });
+
+    await write(remote, "facts/shared.md", "remote edit");
+    const metadataOnly = await buildOfflineSyncSnapshot({
+      root: remote,
+      sourceId: "remote",
+      includeContent: false,
+    });
+    const changedContent = await buildOfflineSyncSnapshotForPaths({
+      root: remote,
+      sourceId: "remote",
+      paths: ["facts/shared.md"],
+      includeContent: true,
+    });
+    const contentByPath = new Map(
+      changedContent.files.map((file) => [file.path, file.contentBase64]),
+    );
+    const hydrated = {
+      ...metadataOnly,
+      files: metadataOnly.files.map((file) => {
+        const contentBase64 = contentByPath.get(file.path);
+        return contentBase64 === undefined ? file : { ...file, contentBase64 };
+      }),
+    };
+
+    const secondPull = await applyOfflineSyncSnapshot({
+      root: local,
+      snapshot: hydrated,
+      baseFiles: firstPull.nextBaseFiles,
+    });
+
+    assert.equal(secondPull.upserted, 1);
+    assert.equal(secondPull.conflicts.length, 0);
+    assert.equal(await readUtf8(local, "facts/shared.md"), "remote edit");
+    assert.equal(await readUtf8(local, "facts/stable.md"), "unchanged");
+  } finally {
+    await rm(remote, { recursive: true, force: true });
+    await rm(local, { recursive: true, force: true });
+  }
+});
+
 test("offline pull preserves local edits when both sides changed since the base", async () => {
   const remote = await tempDir("remnic-offline-conflict-remote");
   const local = await tempDir("remnic-offline-conflict-local");