@remnic/core 1.1.14 → 1.1.16

package/src/access-http.test.ts

@@ -223,3 +223,292 @@ test("HTTP review show hides namespace denial as pair_not_found", async () => {
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+test("HTTP offline snapshot forwards namespace and transfer options", async () => {
+  const calls: Array<{
+    namespace: string | undefined;
+    principal: string | undefined;
+    includeTranscripts: boolean | undefined;
+    includeContent: boolean | undefined;
+  }> = [];
+  const service = {
+    offlineSyncSnapshot: async (options: {
+      namespace?: string;
+      principal?: string;
+      includeTranscripts?: boolean;
+      includeContent?: boolean;
+    }) => {
+      calls.push({
+        namespace: options.namespace,
+        principal: options.principal,
+        includeTranscripts: options.includeTranscripts,
+        includeContent: options.includeContent,
+      });
+      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/snapshot?namespace=team&include_transcripts=false&content=false`,
+      { headers: { authorization: "Bearer test-token" } },
+    );
+    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,
+      includeContent: false,
+    }]);
+  } finally {
+    await server.stop();
+  }
+});
+
+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 = {
+    offlineSyncSnapshot: async () => {
+      calls += 1;
+      return {};
+    },
+  } 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}/engram/v1/offline-sync/snapshot?include_transcripts=maybe`,
+      { headers: { authorization: "Bearer test-token" } },
+    );
+    const body = await response.json() as { error?: string; code?: string };
+
+    assert.equal(response.status, 400);
+    assert.match(body.error ?? "", /include_transcripts must be one of: true, false/);
+    assert.equal(body.code, "input_error");
+    assert.equal(calls, 0);
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP offline apply validates and forwards changesets", async () => {
+  const calls: Array<{
+    namespace: string | undefined;
+    principal: string | undefined;
+    changeset: unknown;
+  }> = [];
+  const changeset = {
+    format: "remnic.offline-sync.changeset.v1",
+    schemaVersion: 1,
+    createdAt: new Date("2026-05-21T00:00:00Z").toISOString(),
+    sourceId: "laptop:test",
+    includeTranscripts: true,
+    changes: [],
+  };
+  const service = {
+    offlineSyncApply: async (options: {
+      namespace?: string;
+      principal?: string;
+      changeset: unknown;
+    }) => {
+      calls.push({
+        namespace: options.namespace,
+        principal: options.principal,
+        changeset: options.changeset,
+      });
+      return {
+        namespace: options.namespace ?? "default",
+        appliedUpserts: 0,
+        appliedDeletes: 0,
+        skipped: 0,
+        conflicts: [],
+        currentFiles: [],
+      };
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    principal: "writer",
+    adminConsoleEnabled: false,
+  });
+
+  const status = await server.start();
+  try {
+    const response = await fetch(`http://127.0.0.1:${status.port}/remnic/v1/offline-sync/apply`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ namespace: "team", changeset }),
+    });
+    const body = await response.json() as { namespace?: string; appliedUpserts?: number };
+
+    assert.equal(response.status, 200);
+    assert.equal(body.namespace, "team");
+    assert.equal(body.appliedUpserts, 0);
+    assert.deepEqual(calls, [{
+      namespace: "team",
+      principal: "writer",
+      changeset,
+    }]);
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP offline apply requires a changeset", async () => {
+  let calls = 0;
+  const service = {
+    offlineSyncApply: async () => {
+      calls += 1;
+      return {};
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    principal: "writer",
+    adminConsoleEnabled: false,
+  });
+
+  const status = await server.start();
+  try {
+    const response = await fetch(`http://127.0.0.1:${status.port}/engram/v1/offline-sync/apply`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ namespace: "team" }),
+    });
+    const body = await response.json() as { code?: string; details?: Array<{ field?: string; message?: string }> };
+
+    assert.equal(response.status, 400);
+    assert.equal(body.code, "validation_error");
+    assert.equal(body.details?.[0]?.field, "changeset");
+    assert.equal(calls, 0);
+
+    const nullResponse = await fetch(`http://127.0.0.1:${status.port}/engram/v1/offline-sync/apply`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ namespace: "team", changeset: null }),
+    });
+    const nullBody = await nullResponse.json() as { code?: string; details?: Array<{ field?: string; message?: string }> };
+
+    assert.equal(nullResponse.status, 400);
+    assert.equal(nullBody.code, "validation_error");
+    assert.equal(nullBody.details?.[0]?.field, "changeset");
+    assert.equal(nullBody.details?.[0]?.message, "changeset is required");
+    assert.equal(calls, 0);
+  } finally {
+    await server.stop();
+  }
+});

package/src/access-http.ts

@@ -588,6 +588,75 @@ export class EngramAccessHttpServer {
       return;
     }
 
+    if (
+      req.method === "GET" &&
+      (pathname === "/engram/v1/offline-sync/snapshot" || pathname === "/remnic/v1/offline-sync/snapshot")
+    ) {
+      const includeTranscriptsRaw = parsed.searchParams.get("include_transcripts");
+      const includeContentRaw = parsed.searchParams.get("content");
+      if (
+        includeTranscriptsRaw !== null &&
+        includeTranscriptsRaw !== "true" &&
+        includeTranscriptsRaw !== "false"
+      ) {
+        throw new EngramAccessInputError(
+          `include_transcripts must be one of: true, false (got: ${includeTranscriptsRaw})`,
+        );
+      }
+      if (
+        includeContentRaw !== null &&
+        includeContentRaw !== "true" &&
+        includeContentRaw !== "false"
+      ) {
+        throw new EngramAccessInputError(
+          `content must be one of: true, false (got: ${includeContentRaw})`,
+        );
+      }
+      const namespaceParam = parsed.searchParams.get("namespace");
+      const result = await this.service.offlineSyncSnapshot({
+        namespace: this.resolveNamespace(
+          req,
+          namespaceParam && namespaceParam.length > 0 ? namespaceParam : undefined,
+        ),
+        principal: this.resolveRequestPrincipal(req),
+        includeTranscripts: includeTranscriptsRaw !== "false",
+        includeContent: includeContentRaw !== "false",
+      });
+      this.respondJson(res, 200, result);
+      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")
+    ) {
+      const body = await this.readValidatedBody(req, "offlineSyncApply");
+      this.ensureWriteRateLimitAvailable();
+      const result = await this.service.offlineSyncApply({
+        namespace: this.resolveNamespace(req, body.namespace),
+        principal: this.resolveRequestPrincipal(req),
+        changeset: body.changeset,
+      });
+      this.recordWriteRateLimitHit();
+      this.respondJson(res, 200, result);
+      return;
+    }
+
     if (req.method === "POST" && pathname === "/engram/v1/recall/explain") {
       const body = await this.readValidatedBody(req, "recallExplain");
       const response = await this.service.recallExplain({

package/src/access-schema.ts

@@ -364,6 +364,28 @@ export const capsuleListRequestSchema = z
     namespace: namespaceSchema,
   });
 
+// ---------------------------------------------------------------------------
+// Offline sync
+// ---------------------------------------------------------------------------
+
+export const offlineSyncApplyRequestSchema = z
+  .object({
+    namespace: namespaceSchema,
+    changeset: z.unknown(),
+  })
+  .refine((value) => value.changeset !== undefined && value.changeset !== null, {
+    message: "changeset is required",
+    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
 // ---------------------------------------------------------------------------
@@ -429,6 +451,8 @@ export type DaySummaryRequest = z.infer<typeof daySummaryRequestSchema>;
 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>;
 
 // ---------------------------------------------------------------------------
@@ -452,6 +476,8 @@ export type SchemaName =
   | "capsuleExport"
   | "capsuleImport"
   | "capsuleList"
+  | "offlineSyncFiles"
+  | "offlineSyncApply"
   | "actionConfidence";
 
 export type SchemaTypeFor<N extends SchemaName> =
@@ -471,6 +497,8 @@ 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;
 
@@ -491,6 +519,8 @@ 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

@@ -135,6 +135,13 @@ import {
   defaultCapsulesDir,
   type CapsuleListEntry,
 } from "./capsule-cli.js";
+import {
+  applyOfflineSyncChangeset,
+  buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotForPaths,
+  type OfflineSyncApplyChangesetResult,
+  type OfflineSyncSnapshot,
+} from "./offline-sync.js";
 import {
   evaluateActionConfidence,
   type ActionConfidenceInput,
@@ -603,6 +610,38 @@ export interface EngramAccessCapsuleListResponse {
   capsules: CapsuleListEntry[];
 }
 
+export interface EngramAccessOfflineSyncSnapshotRequest {
+  namespace?: string;
+  principal?: string;
+  includeTranscripts?: boolean;
+  includeContent?: boolean;
+}
+
+export interface EngramAccessOfflineSyncFilesRequest {
+  namespace?: string;
+  principal?: string;
+  includeTranscripts?: boolean;
+  paths: string[];
+}
+
+export interface EngramAccessOfflineSyncApplyRequest {
+  namespace?: string;
+  principal?: string;
+  changeset: unknown;
+}
+
+export interface EngramAccessOfflineSyncSnapshotResponse extends OfflineSyncSnapshot {
+  namespace: string;
+}
+
+export interface EngramAccessOfflineSyncFilesResponse extends OfflineSyncSnapshot {
+  namespace: string;
+}
+
+export interface EngramAccessOfflineSyncApplyResponse extends OfflineSyncApplyChangesetResult {
+  namespace: string;
+}
+
 export type EngramAccessActionConfidenceRequest = ActionConfidenceInput;
 export type EngramAccessActionConfidenceResponse = ActionConfidenceResult;
 
@@ -5522,6 +5561,87 @@ export class EngramAccessService {
     return { namespace: resolvedNamespace, capsulesDir, capsules };
   }
 
+  async offlineSyncSnapshot(
+    options: EngramAccessOfflineSyncSnapshotRequest = {},
+  ): Promise<EngramAccessOfflineSyncSnapshotResponse> {
+    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);
+    const snapshot = await buildOfflineSyncSnapshot({
+      root: storage.dir,
+      sourceId: `remnic:${resolvedNamespace}:${storageHash}`,
+      includeContent: options.includeContent !== false,
+      includeTranscripts: options.includeTranscripts !== false,
+      readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
+    });
+    return {
+      namespace: resolvedNamespace,
+      ...snapshot,
+    };
+  }
+
+  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> {
+    const resolvedNamespace = this.resolveWritableNamespace(
+      options.namespace,
+      undefined,
+      options.principal,
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    try {
+      const result = await applyOfflineSyncChangeset({
+        root: storage.dir,
+        changeset: options.changeset,
+        readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
+        writeFile: async ({ filePath, content }) => storage.writeOfflineSyncFile(filePath, content),
+        deleteFile: async ({ filePath }) => storage.deleteOfflineSyncFile(filePath),
+      });
+      return {
+        namespace: resolvedNamespace,
+        ...result,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.startsWith("offline sync")) {
+        throw new EngramAccessInputError(message);
+      }
+      throw error;
+    }
+  }
+
   // ── Dreams pipeline telemetry surfaces (issue #678 PR 3+4) ──────────────
 
   /**

package/src/index.ts

@@ -674,6 +674,40 @@ export {
   type SyncState,
 } from "./sync/index.js";
 
+// ---------------------------------------------------------------------------
+// Offline Sync
+// ---------------------------------------------------------------------------
+
+export {
+  OFFLINE_SYNC_CHANGESET_FORMAT,
+  OFFLINE_SYNC_SNAPSHOT_FORMAT,
+  OFFLINE_SYNC_STATE_VERSION,
+  applyOfflineSyncChangeset,
+  applyOfflineSyncSnapshot,
+  buildOfflineSyncChangeset,
+  buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotForPaths,
+  defaultOfflineSyncStatePath,
+  fileStatesFromSnapshot,
+  normalizeOfflineSyncChangeset,
+  normalizeOfflineSyncSnapshot,
+  offlineSyncStateFromSnapshot,
+  readOfflineSyncState,
+  summarizeOfflineSyncChangeset,
+  writeOfflineSyncState,
+  type OfflineSyncApplyChangesetResult,
+  type OfflineSyncApplySnapshotResult,
+  type OfflineSyncChange,
+  type OfflineSyncChangeset,
+  type OfflineSyncConflict,
+  type OfflineSyncFileRecord,
+  type OfflineSyncFileState,
+  type OfflineSyncFileTarget,
+  type OfflineSyncFileWriteTarget,
+  type OfflineSyncSnapshot,
+  type OfflineSyncState,
+} from "./offline-sync.js";
+
 // ---------------------------------------------------------------------------
 // Memory Extension Host (#382)
 // ---------------------------------------------------------------------------