@remnic/core 1.1.28 → 1.1.30

package/src/access-http.ts

@@ -12,6 +12,7 @@ import { validateRequest, type SchemaName, type SchemaTypeFor } from "./access-s
 import {
   OFFLINE_SYNC_APPLY_MAX_BODY_BYTES,
   OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES,
+  OFFLINE_SYNC_SNAPSHOT_BASE_MAX_BODY_BYTES,
 } from "./offline-sync.js";
 import type { RecallDisclosure, RecallPlanMode } from "./types.js";
 import { isRecallDisclosure } from "./types.js";
@@ -125,6 +126,16 @@ function parseTrustZoneFilter(raw: string | null): TrustZoneName | undefined {
   throw new HttpError(400, "zone must be one of quarantine|working|trusted", "invalid_zone_filter");
 }
 
+function summarizeHttpRequest(req: IncomingMessage): string {
+  const method = req.method ?? "UNKNOWN";
+  try {
+    const parsed = new URL(req.url ?? "/", "http://localhost");
+    return `${method} ${parsed.pathname}`;
+  } catch {
+    return `${method} ${(req.url ?? "/").split("?")[0]}`;
+  }
+}
+
 /**
  * Decode a `:peerId` URL path segment, converting malformed percent-encoded
  * input (e.g., `%E0%A4%A`) into a 400 client error rather than letting
@@ -217,6 +228,10 @@ export class EngramAccessHttpServer {
             res.destroy(err as Error);
             return;
           }
+          log.error(
+            `engram access HTTP internal error [${correlationId}] ${summarizeHttpRequest(req)}`,
+            err,
+          );
           this.respondJson(res, 500, { error: "internal_error", code: "internal_error" });
         });
       });
@@ -630,6 +645,27 @@ export class EngramAccessHttpServer {
       return;
     }
 
+    if (
+      req.method === "POST" &&
+      (pathname === "/engram/v1/offline-sync/snapshot" || pathname === "/remnic/v1/offline-sync/snapshot")
+    ) {
+      const body = await this.readValidatedBody(
+        req,
+        "offlineSyncSnapshot",
+        OFFLINE_SYNC_SNAPSHOT_BASE_MAX_BODY_BYTES,
+      );
+      const result = await this.service.offlineSyncSnapshot({
+        namespace: this.resolveNamespace(req, body.namespace),
+        principal: this.resolveRequestPrincipal(req),
+        includeTranscripts: body.includeTranscripts,
+        includeContent: body.includeContent,
+        baseFiles: body.baseFiles,
+        ...(body.baseCapturedAt ? { baseCapturedAt: new Date(body.baseCapturedAt) } : {}),
+      });
+      this.respondJson(res, 200, result);
+      return;
+    }
+
     if (
       req.method === "POST" &&
       (pathname === "/engram/v1/offline-sync/files" || pathname === "/remnic/v1/offline-sync/files")
@@ -717,6 +753,7 @@ export class EngramAccessHttpServer {
         namespace: this.resolveNamespace(req, body.namespace),
         principal: this.resolveRequestPrincipal(req),
         changeset: body.changeset,
+        returnCurrentFiles: body.returnCurrentFiles,
       });
       this.respondJson(res, 200, result);
       return;

package/src/access-schema.ts

@@ -9,8 +9,12 @@ import {
   ACTION_CONFIDENCE_RULE_KINDS,
 } from "./action-confidence.js";
 import { isValidCapsuleSince } from "./transfer/capsule-export.js";
+import { validateArchiveRelativePath } from "./transfer/fs-utils.js";
 import { CAPSULE_ID_PATTERN } from "./transfer/types.js";
-import { OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES } from "./offline-sync.js";
+import {
+  OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES,
+  OFFLINE_SYNC_MAX_MTIME_MS,
+} from "./offline-sync.js";
 
 // ---------------------------------------------------------------------------
 // Error formatting
@@ -369,10 +373,57 @@ export const capsuleListRequestSchema = z
 // Offline sync
 // ---------------------------------------------------------------------------
 
+function isValidOfflineSyncPath(value: string): boolean {
+  try {
+    validateArchiveRelativePath(value, "path");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const offlineSyncPathSchema = z
+  .string()
+  .trim()
+  .min(1, "path must be non-empty")
+  .max(4096)
+  .refine(
+    isValidOfflineSyncPath,
+    "path must be a POSIX relative path without unsafe segments",
+  );
+
+const offlineSyncFileStateSchema = z.object({
+  path: offlineSyncPathSchema,
+  sha256: z.string().regex(/^[a-f0-9]{64}$/i, "sha256 must be a 64-character hex digest"),
+  bytes: z.number().int().min(0),
+  mtimeMs: z.number().finite().min(0).max(OFFLINE_SYNC_MAX_MTIME_MS),
+});
+
+const offlineSyncBaseCapturedAtSchema = z
+  .string()
+  .trim()
+  .min(1, "baseCapturedAt must be non-empty when provided")
+  .max(64)
+  .refine((value) => Number.isFinite(Date.parse(value)), {
+    message: "baseCapturedAt must be a valid ISO 8601 timestamp",
+  });
+
+export const offlineSyncSnapshotRequestSchema = z.object({
+  namespace: namespaceSchema,
+  includeTranscripts: z.boolean().optional(),
+  includeContent: z.boolean().optional(),
+  baseCapturedAt: offlineSyncBaseCapturedAtSchema.optional(),
+  baseFiles: z
+    .array(offlineSyncFileStateSchema)
+    .max(300_000, "baseFiles must contain 300000 or fewer entries")
+    .optional(),
+});
+
 export const offlineSyncApplyRequestSchema = z
   .object({
     namespace: namespaceSchema,
     changeset: z.unknown(),
+    returnCurrentFiles: z.boolean().optional(),
   })
   .refine((value) => value.changeset !== undefined && value.changeset !== null, {
     message: "changeset is required",
@@ -383,14 +434,14 @@ 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))
+    .array(offlineSyncPathSchema)
     .max(5000, "paths must contain 5000 or fewer entries"),
 });
 
 export const offlineSyncFileContentRequestSchema = z.object({
   namespace: namespaceSchema,
   includeTranscripts: z.boolean().optional(),
-  path: z.string().trim().min(1, "path must be non-empty").max(4096),
+  path: offlineSyncPathSchema,
   offset: z.number().int().min(0).optional(),
   length: z.number().int().min(1).max(OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES).optional(),
 });
@@ -461,6 +512,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 OfflineSyncSnapshotRequest = z.infer<typeof offlineSyncSnapshotRequestSchema>;
 export type OfflineSyncFilesRequest = z.infer<typeof offlineSyncFilesRequestSchema>;
 export type OfflineSyncFileContentRequest = z.infer<typeof offlineSyncFileContentRequestSchema>;
 export type ActionConfidenceRequest = z.infer<typeof actionConfidenceRequestSchema>;
@@ -486,6 +538,7 @@ export type SchemaName =
   | "capsuleExport"
   | "capsuleImport"
   | "capsuleList"
+  | "offlineSyncSnapshot"
   | "offlineSyncFiles"
   | "offlineSyncFileContent"
   | "offlineSyncApply"
@@ -508,6 +561,7 @@ export type SchemaTypeFor<N extends SchemaName> =
   : N extends "capsuleExport" ? CapsuleExportRequest
   : N extends "capsuleImport" ? CapsuleImportRequest
   : N extends "capsuleList" ? CapsuleListRequest
+  : N extends "offlineSyncSnapshot" ? OfflineSyncSnapshotRequest
   : N extends "offlineSyncFiles" ? OfflineSyncFilesRequest
   : N extends "offlineSyncFileContent" ? OfflineSyncFileContentRequest
   : N extends "offlineSyncApply" ? OfflineSyncApplyRequest
@@ -531,6 +585,7 @@ const schemas: Record<SchemaName, z.ZodTypeAny> = {
   capsuleExport: capsuleExportRequestSchema,
   capsuleImport: capsuleImportRequestSchema,
   capsuleList: capsuleListRequestSchema,
+  offlineSyncSnapshot: offlineSyncSnapshotRequestSchema,
   offlineSyncFiles: offlineSyncFilesRequestSchema,
   offlineSyncFileContent: offlineSyncFileContentRequestSchema,
   offlineSyncApply: offlineSyncApplyRequestSchema,

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

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
-import { mkdtemp, rm, symlink } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, readFile, rm, symlink, utimes, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -184,3 +185,57 @@ test("offlineSyncFiles reports symlink requested paths as input errors", async (
     await rm(root, { recursive: true, force: true });
   }
 });
+
+test("offlineSyncSnapshot ignores client 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 mtimeMs = 1_700_000_000_000;
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, oldContent);
+    await utimes(filePath, mtimeMs / 1000, mtimeMs / 1000);
+    const baseFile = {
+      path: relPath,
+      sha256: createHash("sha256").update(oldContent).digest("hex"),
+      bytes: oldContent.byteLength,
+      mtimeMs,
+    };
+    await writeFile(filePath, newContent);
+    await utimes(filePath, mtimeMs / 1000, mtimeMs / 1000);
+
+    const { service } = makeService();
+    (service as unknown as {
+      orchestrator: {
+        config: PluginConfig;
+        getStorage(namespace: string): Promise<StorageManager>;
+      };
+    }).orchestrator.getStorage = async () => ({
+      dir: root,
+      async readOfflineSyncFile(targetPath: string) {
+        return readFile(targetPath);
+      },
+      async digestOfflineSyncFile(targetPath: string) {
+        const content = await readFile(targetPath);
+        return {
+          sha256: createHash("sha256").update(content).digest("hex"),
+          bytes: content.byteLength,
+        };
+      },
+    } as unknown as StorageManager);
+
+    const snapshot = await service.offlineSyncSnapshot({
+      namespace: "team",
+      principal: "reader",
+      includeContent: false,
+      baseFiles: [baseFile],
+      baseCapturedAt: new Date(Date.now() + 60_000),
+    });
+
+    assert.equal(snapshot.files[0]?.sha256, createHash("sha256").update(newContent).digest("hex"));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/access-service-offline-file-content.test.ts

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import { EngramAccessInputError, EngramAccessService } from "./access-service.js";
+import { OFFLINE_SYNC_MAX_MTIME_MS } from "./offline-sync.js";
 
 function createOfflineService(): EngramAccessService {
   return new EngramAccessService({
@@ -34,4 +35,20 @@ test("offline apply-file-content reports invalid metadata as input errors", asyn
       error instanceof EngramAccessInputError &&
       /sha256 must be a 64-character sha256/.test(error.message),
   );
+
+  await assert.rejects(
+    () => service.offlineSyncApplyFileContent({
+      includeTranscripts: true,
+      sourceId: "laptop",
+      path: "state/lcm.sqlite",
+      sha256: "a".repeat(64),
+      bytes: 0,
+      mtimeMs: OFFLINE_SYNC_MAX_MTIME_MS + 1,
+      offset: 0,
+      content: Buffer.alloc(0),
+    }),
+    (error) =>
+      error instanceof EngramAccessInputError &&
+      /mtimeMs must be within JavaScript Date range/.test(error.message),
+  );
 });

package/src/access-service.ts

@@ -139,11 +139,13 @@ import {
   applyOfflineSyncFileContentChunk,
   applyOfflineSyncChangeset,
   buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotFromBase,
   buildOfflineSyncSnapshotForPaths,
   readOfflineSyncFileContentChunk,
   type OfflineSyncApplyFileContentChunkResult,
   type OfflineSyncApplyChangesetResult,
   type OfflineSyncFileContentChunk,
+  type OfflineSyncFileState,
   type OfflineSyncSnapshot,
 } from "./offline-sync.js";
 import {
@@ -619,6 +621,8 @@ export interface EngramAccessOfflineSyncSnapshotRequest {
   principal?: string;
   includeTranscripts?: boolean;
   includeContent?: boolean;
+  baseCapturedAt?: Date;
+  baseFiles?: OfflineSyncFileState[];
 }
 
 export interface EngramAccessOfflineSyncFilesRequest {
@@ -655,6 +659,7 @@ export interface EngramAccessOfflineSyncApplyRequest {
   namespace?: string;
   principal?: string;
   changeset: unknown;
+  returnCurrentFiles?: boolean;
 }
 
 export interface EngramAccessOfflineSyncSnapshotResponse extends OfflineSyncSnapshot {
@@ -5602,12 +5607,19 @@ export class EngramAccessService {
     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({
+    const snapshotBuilder = options.includeContent === false && options.baseFiles && options.baseFiles.length > 0
+      ? buildOfflineSyncSnapshotFromBase
+      : buildOfflineSyncSnapshot;
+    const snapshot = await snapshotBuilder({
       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),
     });
     return {
       namespace: resolvedNamespace,
@@ -5702,6 +5714,7 @@ export class EngramAccessService {
         content: options.content,
         includeTranscripts: options.includeTranscripts !== false,
         readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
+        readFileDigest: async ({ filePath }) => storage.digestOfflineSyncFile(filePath),
         writeFile: async ({ filePath, content }) => storage.writeOfflineSyncFile(filePath, content),
         writeStagingFile: async ({ filePath, content }) => storage.writeOfflineSyncStagingFile(filePath, content),
         writeFileChunks: async ({ filePath, chunks }) => storage.writeOfflineSyncFileChunks(filePath, chunks),
@@ -5743,7 +5756,9 @@ export class EngramAccessService {
       const result = await applyOfflineSyncChangeset({
         root: storage.dir,
         changeset: options.changeset,
+        returnCurrentFiles: options.returnCurrentFiles,
         readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
+        readFileDigest: async ({ filePath }) => storage.digestOfflineSyncFile(filePath),
         writeFile: async ({ filePath, content }) => storage.writeOfflineSyncFile(filePath, content),
         deleteFile: async ({ filePath }) => storage.deleteOfflineSyncFile(filePath),
       });

package/src/config.ts

@@ -96,14 +96,14 @@ function parseBoundedPositiveInteger(
 }
 
 function parseQmdSupportedVersion(value: unknown): string {
-  if (value === undefined || value === null) return "2.5.1";
+  if (value === undefined || value === null) return "2.5.3";
   if (typeof value !== "string") {
     throw new Error(`qmdSupportedVersion must be a semantic version string; got ${JSON.stringify(value)}`);
   }
   const normalized = value.trim();
   if (!/^\d+\.\d+\.\d+$/.test(normalized)) {
     throw new Error(
-      `qmdSupportedVersion must be a semantic version string like "2.5.1"; got ${JSON.stringify(value)}`,
+      `qmdSupportedVersion must be a semantic version string like "2.5.3"; got ${JSON.stringify(value)}`,
     );
   }
   return normalized;

package/src/index.ts

@@ -683,13 +683,16 @@ export {
   OFFLINE_SYNC_CHANGESET_FORMAT,
   OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES,
   OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES,
+  OFFLINE_SYNC_SNAPSHOT_BASE_MAX_BODY_BYTES,
   OFFLINE_SYNC_SNAPSHOT_FORMAT,
   OFFLINE_SYNC_STATE_VERSION,
   applyOfflineSyncFileContentChunk,
   applyOfflineSyncChangeset,
   applyOfflineSyncSnapshot,
   buildOfflineSyncChangeset,
+  buildOfflineSyncChangesetFromSnapshot,
   buildOfflineSyncSnapshot,
+  buildOfflineSyncSnapshotFromBase,
   buildOfflineSyncSnapshotForPaths,
   defaultOfflineSyncStatePath,
   fileStatesFromSnapshot,
@@ -698,8 +701,10 @@ export {
   offlineSyncStateFromSnapshot,
   readOfflineSyncFileContentChunk,
   readOfflineSyncState,
+  shouldPreferIncomingOfflineRuntimeFile,
   summarizeOfflineSyncChangeset,
   summarizeOfflineSyncPendingChanges,
+  summarizeOfflineSyncPendingFiles,
   writeOfflineSyncState,
   type OfflineSyncApplyFileContentChunkResult,
   type OfflineSyncApplyChangesetResult,
@@ -707,6 +712,7 @@ export {
   type OfflineSyncChange,
   type OfflineSyncChangeset,
   type OfflineSyncConflict,
+  type OfflineSyncFileDigest,
   type OfflineSyncFileRecord,
   type OfflineSyncFileContentChunk,
   type OfflineSyncFileState,