@remnic/core 9.69.87 → 9.69.89

package/src/offline-sync-exclude-globs.ts

@@ -55,4 +55,116 @@ export const DEFAULT_OFFLINE_SYNC_EXCLUDE_GLOBS: readonly string[] = [
   // a crash-orphan can never be enumerated into a snapshot; the leading `**/`
   // matches the root-level dir (zero segments) and any nested placement.
   "**/.remnic-offline-decrypt-*/**",
+  // Embedding-index transaction leftovers (issue #3146, PR #3148). The
+  // identity-replacement backup (`embeddings.pre-replace.tmp`) can hold a
+  // full obsolete generation and `embeddings.staging.tmp-*` holds a
+  // partially staged one; both are node-local recovery state that must
+  // never be enumerated into a snapshot. The demoted legacy recovery file
+  // (`embeddings.json.pre-migration.tmp-*`) is likewise node-local.
+  "**/state/embeddings.pre-replace.tmp/**",
+  "**/state/embeddings.staging.tmp-*/**",
+  "**/state/embeddings.json.pre-migration.tmp-*",
+  "**/namespaces/*/state/embeddings.pre-replace.tmp/**",
+  "**/namespaces/*/state/embeddings.staging.tmp-*/**",
+  "**/namespaces/*/state/embeddings.json.pre-migration.tmp-*",
 ];
+
+
+const DEFAULT_OFFLINE_SYNC_EXCLUDE_REGEXPS: readonly RegExp[] =
+  DEFAULT_OFFLINE_SYNC_EXCLUDE_GLOBS.map((glob) => globToRegExp(glob));
+
+/**
+ * Precompiled-once default-exclude check for the snapshot enumeration hot
+ * path (Kilo review, PR #1793). Moved here from offline-sync.ts with the
+ * glob list so the two can never drift (issue #1995).
+ */
+export function matchesOfflineSyncDefaultExclude(relPosix: string): boolean {
+  for (const regexp of DEFAULT_OFFLINE_SYNC_EXCLUDE_REGEXPS) {
+    if (regexp.test(relPosix)) return true;
+  }
+  return false;
+}
+
+export function globToRegExp(glob: string): RegExp {
+  if (typeof glob !== "string" || glob.length === 0) {
+    throw new Error("offlineSyncExcludes entry must be a non-empty string");
+  }
+  if (glob.includes("\0")) {
+    throw new Error("offlineSyncExcludes entry must not contain NUL bytes");
+  }
+  let source = "";
+  for (let i = 0; i < glob.length; i += 1) {
+    const ch = glob[i];
+    if (ch === "*") {
+      if (glob[i + 1] === "*") {
+        // `**` is cross-segment wherever it appears:
+        //   leading `**/`  -> zero or more whole segments
+        //   `/**` at end   -> everything under the directory
+        //   `a/**/b`       -> any depth between segments
+        // (Cursor review on PR #1793: trailing `scratch/**` must match
+        // nested `scratch/a/b.md`, matching the offline-mode guide.)
+        if (glob[i + 2] === "/") {
+          source += "(?:.*/)?";
+          i += 2;
+          continue;
+        }
+        source += ".*";
+        i += 1;
+        continue;
+      }
+      source += "[^/]*";
+      continue;
+    }
+    if (ch === "?") {
+      source += "[^/]";
+      continue;
+    }
+    if (ch === "/") {
+      source += "/";
+      continue;
+    }
+    source += ch.replace(/[\\^$.+()|{}\[\]]/g, "\\$&");
+  }
+  return new RegExp(`^${source}$`);
+}
+
+export function compileOfflineSyncExcludeGlobs(
+  globs: readonly unknown[],
+): RegExp[] {
+  const out: RegExp[] = [];
+  for (const entry of globs) {
+    if (typeof entry !== "string" || entry.length === 0) {
+      throw new Error("offlineSyncExcludes must contain only non-empty strings");
+    }
+    out.push(globToRegExp(entry));
+  }
+  return out;
+}
+
+/**
+ * Validate the operator-supplied offline-sync exclude list (#1786).
+ * Rejects loudly instead of silently defaulting (CLAUDE.md rule 39):
+ * a misspelled key value must fail config parse, not be ignored.
+ * Lives next to the glob compiler so config.ts only carries the call.
+ */
+export function parseOfflineSyncExcludes(raw: unknown): string[] {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw)) {
+    throw new Error(
+      `offlineSyncExcludes must be an array of non-empty glob strings; got ${typeof raw}`,
+    );
+  }
+  for (const entry of raw) {
+    if (typeof entry !== "string" || entry.trim().length === 0) {
+      throw new Error(
+        "offlineSyncExcludes must contain only non-empty glob strings",
+      );
+    }
+  }
+  const globs = raw.map((entry) => (entry as string).trim());
+  // Compile-check every glob now so a bad pattern fails at parse time
+  // rather than mid-sync. compileOfflineSyncExcludeGlobs throws with a
+  // per-entry message.
+  compileOfflineSyncExcludeGlobs(globs);
+  return globs;
+}

package/src/offline-sync-file-io.ts

@@ -76,3 +76,51 @@ export async function plainFileDigest(filePath: string): Promise<string> {
   }
   return hash.digest("hex");
 }
+
+import { lstat, utimes } from "node:fs/promises";
+import { isCensusMtimeMs } from "./census-validation.js";
+import { resolveSafeArchiveTarget, type SafeArchiveRoot } from "./transfer/fs-utils.js";
+
+/** Sync-internal directory spooling partial uploads and coordination state. */
+export const SYNC_INTERNAL_DIR = ".offline-sync";
+
+export const OFFLINE_SYNC_FAST_BASE_MTIME_TOLERANCE_MS = 1_000;
+
+export function assertNonNegativeFinite(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new Error(`${field} must be a non-negative finite number`);
+  }
+  return value;
+}
+
+export function assertOfflineSyncMtimeMs(value: unknown, field: string): number {
+  const mtimeMs = assertNonNegativeFinite(value, field);
+  if (!isCensusMtimeMs(mtimeMs)) {
+    throw new Error(`${field} must be within JavaScript Date range`);
+  }
+  return mtimeMs;
+}
+
+export async function setSafeFileMtime(
+  root: SafeArchiveRoot,
+  relPath: string,
+  mtimeMs: number | undefined,
+): Promise<boolean> {
+  if (mtimeMs === undefined) return true;
+  const target = await resolveSafeArchiveTarget(root, relPath);
+  const targetStat = await lstat(target).catch((error: unknown) => {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  });
+  if (!targetStat) return false;
+  if (targetStat.isSymbolicLink()) {
+    throw new Error(`offline sync target is a symlink: ${relPath}`);
+  }
+  const targetMtimeMs = assertOfflineSyncMtimeMs(mtimeMs, "mtimeMs");
+  if (Math.abs(targetStat.mtimeMs - targetMtimeMs) <= OFFLINE_SYNC_FAST_BASE_MTIME_TOLERANCE_MS) {
+    return true;
+  }
+  const mtime = new Date(targetMtimeMs);
+  await utimes(target, mtime, mtime);
+  return true;
+}

package/src/offline-sync-runtime-state.ts

@@ -0,0 +1,48 @@
+// Runtime-state generation rules for offline sync (issue #1786, #3146).
+// Extracted from offline-sync.ts so the god-file line-count ratchet does not
+// grow when the rules gain entries; behavior is unchanged.
+
+export const EMBEDDING_SHARD_FILE_PATTERN = /^shard-\d{4}\.json$/;
+
+export function isCanonicalRuntimeStatePath(parts: string[]): boolean {
+  if (parts[0] === "state") return true;
+  return parts[0] === "namespaces" && parts.length >= 4 && parts[2] === "state";
+}
+
+const REMOTE_AUTHORITATIVE_RUNTIME_STATE_FILES = new Set([
+  ".artifact-write-version.log",
+  ".memory-status-version.log",
+  "buffer.json",
+  "embeddings.json",
+  "index_time.json",
+  "last_intent.json",
+  "last_qmd_recall.json",
+  "last_recall.json",
+  "lcm.sqlite-shm",
+  "lcm.sqlite-wal",
+  "memory-lifecycle-ledger.jsonl",
+  "recall_impressions.jsonl",
+]);
+
+const ABSENT_INCOMING_RUNTIME_DELETE_FILES = new Set([
+  "lcm.sqlite-shm",
+  "lcm.sqlite-wal",
+]);
+
+// Sharded embedding index (#3146): remote-authoritative like embeddings.json.
+function isRemoteAuthoritativeRuntimeShard(basename: string, parts: string[]): boolean {
+  return EMBEDDING_SHARD_FILE_PATTERN.test(basename) && parts[parts.length - 2] === "embeddings";
+}
+
+export function shouldPreferIncomingOfflineRuntimeFile(relPosix: string): boolean {
+  const parts = relPosix.split("/");
+  const basename = parts[parts.length - 1] ?? "";
+  return isCanonicalRuntimeStatePath(parts) &&
+    (REMOTE_AUTHORITATIVE_RUNTIME_STATE_FILES.has(basename) || isRemoteAuthoritativeRuntimeShard(basename, parts));
+}
+
+export function shouldDeleteAbsentIncomingOfflineRuntimeFile(relPosix: string): boolean {
+  const parts = relPosix.split("/");
+  const basename = parts[parts.length - 1] ?? "";
+  return isCanonicalRuntimeStatePath(parts) && ABSENT_INCOMING_RUNTIME_DELETE_FILES.has(basename);
+}

package/src/offline-sync-snapshot-stream.ts

@@ -0,0 +1,99 @@
+// Streaming offline-sync snapshot builder (PR #3148 round 5). Extracted from
+// access-service.ts so the god-file line-count ratchet does not grow: the
+// stream carries whole-generation omission metadata alongside the file walk,
+// so a filtered embedding generation is announced instead of looking deleted.
+import { createHash } from "node:crypto";
+import type {
+  OfflineSyncDeletionRevision,
+  OfflineSyncFileRecord,
+  OfflineSyncSnapshot,
+} from "./offline-sync.js";
+import {
+  filterOfflineSyncDeletionRevisions,
+  OFFLINE_SYNC_SNAPSHOT_FORMAT,
+  iterateOfflineSyncSnapshotFileRecords,
+} from "./offline-sync.js";
+import {
+  computeOmittedEmbeddingGenerationPaths,
+  embeddingGenerationMembership,
+} from "./offline-sync-embedding-generation.js";
+import type { OfflineSyncExcludeFile, OfflineSyncFileTarget } from "./offline-sync-file-io.js";
+import { matchesOfflineSyncDefaultExclude } from "./offline-sync-exclude-globs.js";
+import type { OfflineSyncFileDigest } from "./offline-sync.js";
+
+export interface OfflineSyncSnapshotStreamBuildOptions {
+  root: string;
+  namespace: string;
+  includeContent: boolean;
+  includeTranscripts: boolean;
+  userExcludeRegexps?: readonly RegExp[];
+  excludeFile: OfflineSyncExcludeFile;
+  readFile: (target: OfflineSyncFileTarget) => Promise<Buffer>;
+  readFileDigest: (target: OfflineSyncFileTarget) => Promise<OfflineSyncFileDigest>;
+  deletions: readonly OfflineSyncDeletionRevision[];
+  signal?: AbortSignal;
+}
+
+export type OfflineSyncSnapshotStreamBuild = Omit<OfflineSyncSnapshot, "files"> & {
+  namespace: string;
+  files: AsyncIterable<OfflineSyncFileRecord>;
+};
+
+/**
+ * Build the streamed snapshot response: whole-generation omission computed
+ * with the SAME filters the walk uses and announced in the header, so the
+ * receiver never interprets a filtered generation as deleted.
+ */
+export async function buildEmbeddingAwareSnapshotStream(
+  options: OfflineSyncSnapshotStreamBuildOptions,
+): Promise<OfflineSyncSnapshotStreamBuild> {
+  const storageHash = createHash("sha256").update(options.root).digest("hex").slice(0, 16);
+  // Deletions: the canonical filter (exclusions + stale-tombstone exists
+  // check) FIRST, then whole-generation suppression so a filtered generation
+  // is never announced as deleted (PR #3148 round 6).
+  const deletions = await filterOfflineSyncDeletionRevisions({
+    root: options.root,
+    deletions: options.deletions,
+    includeTranscripts: options.includeTranscripts,
+    userExcludeRegexps: options.userExcludeRegexps,
+    excludeFile: options.excludeFile,
+  });
+  const omission = await computeOmittedEmbeddingGenerationPaths({
+    rootAbs: options.root,
+    userExcludeRegexps: options.userExcludeRegexps,
+    excludeFile: options.excludeFile,
+    // RAW pre-filter tombstones (see resolvePushEmbeddingGenerationState).
+    tombstonedPaths: options.deletions.map((deletion) => deletion.path),
+    isExcludedRelPath: (relPath) =>
+      matchesOfflineSyncDefaultExclude(relPath) ||
+      Boolean(options.userExcludeRegexps?.some((re) => re.test(relPath))),
+  });
+  const omittedDirs = new Set(omission.omittedDirs);
+  const deletionsAfterGenerationSuppression = deletions.filter((deletion) => {
+    const membership = embeddingGenerationMembership(deletion.path);
+    return !(membership && omittedDirs.has(membership.shardDir));
+  });
+  return {
+    namespace: options.namespace,
+    format: OFFLINE_SYNC_SNAPSHOT_FORMAT,
+    schemaVersion: 1,
+    createdAt: new Date().toISOString(),
+    sourceId: `remnic:${options.namespace}:${storageHash}`,
+    includeTranscripts: options.includeTranscripts,
+    deletions: deletionsAfterGenerationSuppression,
+    ...(omission.omittedDirs.length > 0
+      ? { omittedEmbeddingGenerationDirs: omission.omittedDirs }
+      : {}),
+    files: iterateOfflineSyncSnapshotFileRecords({
+      root: options.root,
+      includeContent: options.includeContent,
+      includeTranscripts: options.includeTranscripts,
+      readFile: options.readFile,
+      readFileDigest: options.readFileDigest,
+      signal: options.signal,
+      userExcludeRegexps: options.userExcludeRegexps,
+      excludeFile: options.excludeFile,
+      skipEmbeddingGenerationPaths: omission.omittedPaths,
+    }),
+  };
+}

package/src/offline-sync-upload-staging.ts

@@ -0,0 +1,291 @@
+// Offline-sync upload staging: chunked upload spool under
+// `.offline-sync/uploads/` (issue #2033). Extracted from offline-sync.ts so
+// the god-file line-count ratchet does not grow; behavior is unchanged.
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { SYNC_INTERNAL_DIR, setSafeFileMtime } from "./offline-sync-file-io.js";
+import type { OfflineSyncFileTarget } from "./offline-sync-file-io.js";
+import type {
+  OfflineSyncFileStagingWriteTarget,
+  OfflineSyncFileWriteChunksTarget,
+  OfflineSyncFileWriteTarget,
+} from "./offline-sync.js";
+import { type SafeArchiveRoot, resolveSafeArchiveTarget } from "./transfer/fs-utils.js";
+
+const OFFLINE_SYNC_UPLOAD_STAGING_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+export function hashText(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+interface OfflineUploadStaging {
+  kind: "single" | "chunks";
+  relPath: string;
+  filePath: string;
+}
+
+function offlineUploadRelPath(options: {
+  sourceId: string;
+  relPath: string;
+  sha256: string;
+  bytes: number;
+}): string {
+  const key = hashText([options.sourceId, options.relPath, options.sha256, String(options.bytes)].join("\0"));
+  return `${SYNC_INTERNAL_DIR}/uploads/${key}.part`;
+}
+
+async function offlineUploadPath(
+  root: SafeArchiveRoot,
+  options: {
+    sourceId: string;
+    relPath: string;
+    sha256: string;
+    bytes: number;
+  }
+): Promise<OfflineUploadStaging> {
+  const relPath = offlineUploadRelPath(options);
+  return {
+    kind: "single",
+    relPath,
+    filePath: await resolveSafeArchiveTarget(root, relPath),
+  };
+}
+
+async function offlineUploadChunkPath(
+  root: SafeArchiveRoot,
+  options: {
+    sourceId: string;
+    relPath: string;
+    sha256: string;
+    bytes: number;
+    offset: number;
+  }
+): Promise<OfflineUploadStaging> {
+  const uploadRelPath = offlineUploadRelPath(options);
+  const relPath = `${uploadRelPath}/${String(options.offset).padStart(20, "0")}.part`;
+  return {
+    kind: "chunks",
+    relPath,
+    filePath: await resolveSafeArchiveTarget(root, relPath),
+  };
+}
+
+export async function writeOfflineUploadChunk(options: {
+  root: SafeArchiveRoot;
+  sourceId: string;
+  relPath: string;
+  sha256: string;
+  bytes: number;
+  offset: number;
+  content: Buffer;
+  readFile?: (target: OfflineSyncFileTarget) => Promise<Buffer>;
+  writeFile?: (target: OfflineSyncFileWriteTarget) => Promise<void>;
+  writeStagingFile?: (target: OfflineSyncFileStagingWriteTarget) => Promise<void>;
+}): Promise<OfflineUploadStaging> {
+  if ((options.writeFile || options.writeStagingFile) && !options.readFile) {
+    throw new Error("offline sync upload chunk storage hooks require readFile");
+  }
+  const uploadRoot = {
+    ...(await offlineUploadPath(options.root, options)),
+    kind: "chunks" as const,
+  };
+  if (options.offset === 0) {
+    await rm(uploadRoot.filePath, { recursive: true, force: true }).catch(() => {});
+  } else {
+    const existing = await stat(uploadRoot.filePath).catch((error: unknown) => {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    });
+    if (!existing || !existing.isDirectory()) {
+      throw new Error(`offline sync upload is missing initial chunk for ${options.relPath}`);
+    }
+  }
+  const chunk = await offlineUploadChunkPath(options.root, { ...options, offset: options.offset });
+
+  const writeStagingFile = options.writeStagingFile ?? options.writeFile;
+  if (writeStagingFile) {
+    // Storage-backed services provide these hooks so secure-store deployments
+    // keep staged partial uploads encrypted at rest without mutating indexes.
+    await writeOfflineUploadContent({
+      root: options.root,
+      relPath: chunk.relPath,
+      filePath: chunk.filePath,
+      content: options.content,
+      writeFile: writeStagingFile,
+    });
+    return uploadRoot;
+  }
+
+  await mkdir(path.dirname(chunk.filePath), { recursive: true });
+  const existingChunk = await lstat(chunk.filePath).catch((error: unknown) => {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  });
+  if (existingChunk?.isSymbolicLink()) {
+    throw new Error(`offline sync upload chunk is a symlink: ${chunk.relPath}`);
+  }
+  await writeFile(chunk.filePath, options.content, { mode: 0o600 });
+  return uploadRoot;
+}
+
+export async function pruneOfflineUploadStaging(root: SafeArchiveRoot): Promise<void> {
+  const uploadsRelPath = `${SYNC_INTERNAL_DIR}/uploads`;
+  const uploadsPath = await resolveSafeArchiveTarget(root, uploadsRelPath);
+  const entries = await readdir(uploadsPath, { withFileTypes: true }).catch((error: unknown) => {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  });
+  const now = Date.now();
+  await Promise.all(
+    entries.map(async (entry) => {
+      if (!/^[a-f0-9]{64}\.part$/i.test(entry.name)) return;
+      const relPath = `${uploadsRelPath}/${entry.name}`;
+      const filePath = await resolveSafeArchiveTarget(root, relPath);
+      const info = await lstat(filePath).catch((error: unknown) => {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+        throw error;
+      });
+      if (!info) return;
+      if (now - info.mtimeMs <= OFFLINE_SYNC_UPLOAD_STAGING_MAX_AGE_MS) return;
+      await rm(filePath, { recursive: true, force: true });
+    })
+  );
+}
+
+async function* readOfflineUploadStagingChunks(options: {
+  root: SafeArchiveRoot;
+  upload: OfflineUploadStaging;
+  readFile?: (target: OfflineSyncFileTarget) => Promise<Buffer>;
+}): AsyncGenerator<Buffer> {
+  if (options.upload.kind === "single") {
+    yield await readOfflineUploadContent({
+      root: options.root,
+      relPath: options.upload.relPath,
+      filePath: options.upload.filePath,
+      readFile: options.readFile,
+    });
+    return;
+  }
+
+  const entries = await readdir(options.upload.filePath);
+  const chunkNames = entries.filter((entry) => /^\d{20}\.part$/.test(entry)).sort();
+  if (chunkNames.length === 0) {
+    throw new Error(`offline sync upload is missing chunks for ${options.upload.relPath}`);
+  }
+  let expectedOffset = 0;
+  for (const chunkName of chunkNames) {
+    const offset = Number(chunkName.slice(0, 20));
+    if (!Number.isSafeInteger(offset) || offset !== expectedOffset) {
+      throw new Error(
+        `offline sync upload offset mismatch for ${options.upload.relPath}: expected ${expectedOffset}, got ${offset}`
+      );
+    }
+    const relPath = `${options.upload.relPath}/${chunkName}`;
+    const filePath = await resolveSafeArchiveTarget(options.root, relPath);
+    const content = await readOfflineUploadContent({
+      root: options.root,
+      relPath,
+      filePath,
+      readFile: options.readFile,
+    });
+    expectedOffset += content.length;
+    yield content;
+  }
+}
+
+export async function digestOfflineUploadStagingContent(options: {
+  root: SafeArchiveRoot;
+  upload: OfflineUploadStaging;
+  readFile?: (target: OfflineSyncFileTarget) => Promise<Buffer>;
+}): Promise<{ sha256: string; bytes: number }> {
+  const hash = createHash("sha256");
+  let bytes = 0;
+  for await (const chunk of readOfflineUploadStagingChunks(options)) {
+    hash.update(chunk);
+    bytes += chunk.length;
+  }
+  return { sha256: hash.digest("hex"), bytes };
+}
+
+export async function writeSafeFileFromUpload(
+  root: SafeArchiveRoot,
+  relPath: string,
+  upload: OfflineUploadStaging,
+  readFile?: (target: OfflineSyncFileTarget) => Promise<Buffer>,
+  writeFileChunks?: (target: OfflineSyncFileWriteChunksTarget) => Promise<void>,
+  mtimeMs?: number
+): Promise<void> {
+  const target = await resolveSafeArchiveTarget(root, relPath);
+  const chunks = readOfflineUploadStagingChunks({ root, upload, readFile });
+  if (writeFileChunks) {
+    await writeFileChunks({ root: root.abs, path: relPath, filePath: target, chunks });
+    await setSafeFileMtime(root, relPath, mtimeMs);
+    return;
+  }
+
+  await mkdir(path.dirname(target), { recursive: true });
+  const tmp = path.join(path.dirname(target), `.remnic-sync.${process.pid}.${randomUUID()}.tmp`);
+  const handle = await open(tmp, "w", 0o600);
+  try {
+    for await (const chunk of chunks) {
+      if (chunk.length > 0) await handle.write(chunk);
+    }
+    await handle.close();
+    const targetStat = await lstat(target).catch((error: unknown) => {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    });
+    if (targetStat?.isSymbolicLink()) {
+      throw new Error(`offline sync target is a symlink: ${relPath}`);
+    }
+    await rename(tmp, target);
+    await setSafeFileMtime(root, relPath, mtimeMs);
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await unlink(tmp).catch(() => {});
+    throw error;
+  }
+}
+
+export async function cleanupOfflineUpload(upload: OfflineUploadStaging): Promise<void> {
+  if (upload.kind === "chunks") {
+    await rm(upload.filePath, { recursive: true, force: true });
+    return;
+  }
+  await unlink(upload.filePath).catch((error: unknown) => {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  });
+}
+
+async function readOfflineUploadContent(options: {
+  root: SafeArchiveRoot;
+  relPath: string;
+  filePath: string;
+  readFile?: (target: OfflineSyncFileTarget) => Promise<Buffer>;
+}): Promise<Buffer> {
+  if (options.readFile) {
+    return options.readFile({
+      root: options.root.abs,
+      path: options.relPath,
+      filePath: options.filePath,
+    });
+  }
+  return readFile(options.filePath);
+}
+
+async function writeOfflineUploadContent(options: {
+  root: SafeArchiveRoot;
+  relPath: string;
+  filePath: string;
+  content: Buffer;
+  writeFile: (target: OfflineSyncFileWriteTarget) => Promise<void>;
+}): Promise<void> {
+  await options.writeFile({
+    root: options.root.abs,
+    path: options.relPath,
+    filePath: options.filePath,
+    content: options.content,
+  });
+}