@vrtmrz/livesync-commonlib 0.2.2 → 0.3.0

package/dist/ContentSplitter/ContentSplitterV2.js

@@ -8,25 +8,15 @@ class ContentSplitterV2 extends ContentSplitterBase {
     return settings.chunkSplitterVersion === ChunkAlgorithms.V2 || settings.chunkSplitterVersion === ChunkAlgorithms.V2Segmenter;
   }
   async processSplit(options) {
-    if (options.useWorker) {
-      return (await splitPieces2WorkerV2(
-        options.blob,
-        options.pieceSize,
-        options.plainSplit,
-        options.minimumChunkSize,
-        options.path,
-        options.useSegmenter
-      ))();
-    } else {
-      return (await splitPieces2V2(
-        options.blob,
-        options.pieceSize,
-        options.plainSplit,
-        options.minimumChunkSize,
-        options.path,
-        options.useSegmenter
-      ))();
-    }
+    const split = options.useWorker ? splitPieces2WorkerV2 : splitPieces2V2;
+    return (await split(
+      options.blob,
+      options.pieceSize,
+      options.plainSplit,
+      options.minimumChunkSize,
+      options.path,
+      options.useSegmenter
+    ))();
   }
 }
 export {

package/dist/common/models/setting.type.d.ts

@@ -557,7 +557,7 @@ export interface P2PConnectionInfo {
      */
     P2P_useDiagRTC?: boolean;
 }
-export interface P2PSyncSetting extends P2PConnectionInfo {
+export interface P2PSyncSetting extends P2PConnectionInfo, Partial<PathIdentitySettings> {
     P2P_AutoAccepting: AutoAccepting;
     P2P_AutoSyncPeers: string;
     P2P_AutoWatchPeers: string;

package/dist/common/models/shared.definition.configNames.js

@@ -66,8 +66,7 @@ const configurationNames = {
   },
   pathNormalizationVersion: {
     name: "Path identity mode",
-    desc: "CouchDB only. Version 0 preserves legacy path identity; version 1 uses Unicode NFC. Physical file names stay unchanged. Update every device and stop synchronisation, then Rebuild both databases from a complete authoritative Vault and Fetch on the other devices. Resolve colliding file names first. P2P and Object Storage do not support version 1.",
-    isAdvanced: true
+    desc: "Version 0 preserves legacy path identity; version 1 uses Unicode NFC. Physical file names stay unchanged. Update every device and stop synchronisation, then Rebuild from a complete authoritative Vault and Fetch on the other devices. With P2P, Rebuild prepares only the source device's local database. Resolve colliding file names first."
   },
   doNotUseFixedRevisionForChunks: {
     name: "Content-derived chunk revisions (obsolete setting)",

package/dist/common/models/tweak.definition.d.ts

@@ -120,8 +120,8 @@ export declare const TweakValuesRecommendedTemplate: Partial<ObsidianLiveSyncSet
 export declare const TweakValuesDefault: Partial<ObsidianLiveSyncSettings>;
 export declare const TweakValuesTemplate: {
     tweakModified: number;
-    usePluginSyncV2: boolean;
     pathNormalizationVersion: import("./setting.type.js").PathNormalizationVersion;
+    usePluginSyncV2: boolean;
     encrypt: boolean;
     idDerivationVersion: 0 | 1;
     usePathObfuscation: boolean;

package/dist/common/pathNormalization.d.ts

@@ -1,4 +1,6 @@
 import type { PathNormalizationVersion } from "./models/setting.type.js";
+/** Reject unsupported path identity versions while allowing an absent legacy value. */
+export declare function assertSupportedPathNormalizationVersion(version: number | undefined): asserts version is PathNormalizationVersion | undefined;
 /** Resolve the stored path identity version, treating an absent legacy value as version zero. */
 export declare function getPathNormalizationVersion(settings: {
     pathNormalizationVersion?: number;

package/dist/common/pathNormalization.js

@@ -1,13 +1,18 @@
+function assertSupportedPathNormalizationVersion(version) {
+  if (version === void 0 || version === 0 || version === 1) return;
+  throw new Error(`Unsupported path normalisation version: ${version}`);
+}
 function getPathNormalizationVersion(settings) {
   const version = settings.pathNormalizationVersion === void 0 ? 0 : settings.pathNormalizationVersion;
-  if (version === 0 || version === 1) return version;
-  throw new Error(`Unsupported path normalisation version: ${version}`);
+  assertSupportedPathNormalizationVersion(version);
+  return version;
 }
 function normalisePathForIdentity(path, version) {
   const resolvedVersion = getPathNormalizationVersion({ pathNormalizationVersion: version });
   return resolvedVersion === 1 ? path.normalize("NFC") : path;
 }
 export {
+  assertSupportedPathNormalizationVersion,
   getPathNormalizationVersion,
   normalisePathForIdentity
 };

package/dist/common/utils.d.ts

@@ -3,6 +3,8 @@ import { replaceAll, replaceAllPairs } from "octagonal-wheels/string";
 export { replaceAll, replaceAllPairs };
 import { concatUInt8Array } from "octagonal-wheels/binary";
 export { concatUInt8Array };
+import { createBinaryBlob, createTextBlob } from "octagonal-wheels/binary/blob";
+export { createBinaryBlob, createTextBlob };
 import { delay, fireAndForget } from "octagonal-wheels/promises";
 export { delay, fireAndForget };
 import { arrayToChunkedArray, unique } from "octagonal-wheels/collection";
@@ -28,12 +30,40 @@ export declare function getDocData(doc: string | string[]): string;
 export declare function getDocDataAsArray(doc: string | string[]): string[];
 export declare function getDocDataAsArrayBuffer(doc: string | string[] | ArrayBuffer): Uint8Array<ArrayBuffer>;
 export declare function isTextBlob(blob: Blob): boolean;
-export declare function createTextBlob(data: string | string[]): Blob;
-export declare function createBinaryBlob(data: Uint8Array<ArrayBuffer> | ArrayBuffer): Blob;
+/**
+ * Normalises content to a Blob through the legacy Commonlib entry point.
+ *
+ * @param data - Text, ordered text parts, binary bytes, or an existing Blob.
+ * @returns The original Blob, or a new text or binary Blob for other inputs.
+ * @remarks
+ * This compatibility wrapper retains the `createBlob` name and delegates to
+ * `toBlob` from `octagonal-wheels/binary/blob`. Existing Blob instances retain
+ * their identity and MIME type. Text retains transparent line endings; binary
+ * views contribute only their visible bytes. Calls use the current realm's
+ * Blob constructor. Document classification and decoding remain in
+ * {@link readAsBlob}; importing this legacy module retains its existing
+ * environment initialisation.
+ */
 export declare function createBlob(data: string | string[] | Uint8Array<ArrayBuffer> | ArrayBuffer | Blob): Blob;
 export declare function isTextDocument(doc: LoadedEntry): boolean;
 export declare function readAsBlob(doc: LoadedEntry): Blob;
 export declare function readContent(doc: LoadedEntry): string | ArrayBuffer;
+/**
+ * Tests whether legacy document-content inputs represent equal bytes.
+ *
+ * @param docA - Text, ordered text parts, a Blob, or binary bytes.
+ * @param docB - The second content value in any supported representation.
+ * @returns Whether the normalised inputs contain equal bytes, ignoring MIME types.
+ * @remarks
+ * Inputs are normalised with {@link createBlob}. Different sizes return false
+ * without reading content. IndexedDB comparison availability is selected at
+ * module import; that path resolves the current method and receiver before
+ * reading both complete Blobs sequentially, including empty inputs.
+ * Otherwise, `isBlobContentEqual` from `octagonal-wheels/binary/blob` reads
+ * pairs of parts of at most 10,000 bytes, using Commonlib's Base64 encoder and
+ * its existing host Buffer fallback. Empty inputs on this path return true
+ * without reads. Read and comparison failures propagate unchanged.
+ */
 export declare function isDocContentSame(docA: string | string[] | Blob | ArrayBuffer, docB: string | string[] | Blob | ArrayBuffer): Promise<boolean>;
 export declare function isObfuscatedEntry(doc: DatabaseEntry): doc is AnyEntry;
 export declare function isEncryptedChunkEntry(doc: DatabaseEntry): doc is EntryLeaf;
@@ -66,7 +96,7 @@ export declare function runWithInterval<T>(key: string, interval: number, task:
  * @remarks This function is not designed to be concurrent.
  */
 export declare function runWithStartInterval<T>(key: string, interval: number, task: () => Promise<T>): Promise<T>;
-export declare const globalConcurrencyController: import("octagonal-wheels/concurrency/semaphore_v2").SemaphoreObject;
+export declare const globalConcurrencyController: import("octagonal-wheels/concurrency/semaphore").SemaphoreObject;
 export declare function determineTypeFromBlob(data: Blob): "newnote" | "plain";
 /**
  * Whether remediation mode is active.

package/dist/common/utils.js

@@ -9,8 +9,10 @@ import {
 } from "./types.js";
 import { normaliseP2PConnectionPath, normaliseP2PMaxWirePayloadBytes } from "./models/setting.p2p.js";
 import { isErrorOfMissingDoc } from "../pouchdb/utils_couchdb.js";
-import { replaceAll, replaceAllPairs } from "octagonal-wheels/string";
+import { joinDelimitedList, replaceAll, replaceAllPairs, splitDelimitedList } from "octagonal-wheels/string";
+import { formatDuration } from "octagonal-wheels/notation/duration";
 import { concatUInt8Array } from "octagonal-wheels/binary";
+import { createBinaryBlob, createTextBlob, isBlobContentEqual, toBlob } from "octagonal-wheels/binary/blob";
 import { delay, fireAndForget } from "octagonal-wheels/promises";
 import { arrayToChunkedArray, unique } from "octagonal-wheels/collection";
 import { extractObject, isObjectDifferent } from "octagonal-wheels/object";
@@ -55,17 +57,8 @@ function getDocDataAsArrayBuffer(doc) {
 function isTextBlob(blob) {
   return blob.type === "text/plain";
 }
-function createTextBlob(data) {
-  const d = Array.isArray(data) ? data : [data];
-  return new Blob(d, { endings: "transparent", type: "text/plain" });
-}
-function createBinaryBlob(data) {
-  return new Blob([data], { endings: "transparent", type: "application/octet-stream" });
-}
 function createBlob(data) {
-  if (data instanceof Blob) return data;
-  if (data instanceof Uint8Array || data instanceof ArrayBuffer) return createBinaryBlob(data);
-  return createTextBlob(data);
+  return toBlob(data);
 }
 function isTextDocument(doc) {
   if (doc.type == "plain") return true;
@@ -88,23 +81,17 @@ function readContent(doc) {
   }
 }
 const isIndexDBCmpExist = typeof compatGlobal?.indexedDB?.cmp !== "undefined";
+async function isArrayBufferContentEqual(left, right) {
+  return await arrayBufferToBase64Single(left) === await arrayBufferToBase64Single(right);
+}
 async function isDocContentSame(docA, docB) {
   const blob1 = createBlob(docA);
   const blob2 = createBlob(docB);
-  if (blob1.size != blob2.size) return false;
   if (isIndexDBCmpExist) {
+    if (blob1.size != blob2.size) return false;
     return compatGlobal.indexedDB.cmp(await blob1.arrayBuffer(), await blob2.arrayBuffer()) === 0;
   }
-  const checkQuantum = 1e4;
-  const length = blob1.size;
-  let i = 0;
-  while (i < length) {
-    const ab1 = await blob1.slice(i, i + checkQuantum).arrayBuffer();
-    const ab2 = await blob2.slice(i, i + checkQuantum).arrayBuffer();
-    i += checkQuantum;
-    if (await arrayBufferToBase64Single(ab1) != await arrayBufferToBase64Single(ab2)) return false;
-  }
-  return true;
+  return isBlobContentEqual(blob1, blob2, isArrayBufferContentEqual);
 }
 function isObfuscatedEntry(doc) {
   if (doc._id.startsWith(PREFIX_OBFUSCATED)) {
@@ -267,24 +254,7 @@ function escapeMarkdownValue(value) {
   }
 }
 function timeDeltaToHumanReadable(delta) {
-  const sec = delta / 1e3;
-  if (sec < 60) {
-    return `${sec.toFixed(2)}s`;
-  }
-  const min = sec / 60;
-  if (min < 60) {
-    return `${min.toFixed(2)}m`;
-  }
-  const hour = min / 60;
-  if (hour < 24) {
-    return `${hour.toFixed(2)}h`;
-  }
-  const day = hour / 24;
-  if (day < 365) {
-    return `${day.toFixed(2)}d`;
-  }
-  const year = day / 365;
-  return `${year.toFixed(2)}y`;
+  return formatDuration(delta);
 }
 async function wrapException(func) {
   try {
@@ -378,12 +348,10 @@ function parseCustomRegExpList(list, flags, delimiter) {
   return items.map((e) => new CustomRegExp(e, flags));
 }
 function constructCustomRegExpList(items, delimiter) {
-  return items.map((e) => `${e}`).join(`${delimiter}`);
+  return joinDelimitedList(items.map((e) => `${e}`), `${delimiter}`);
 }
 function splitCustomRegExpList(list, delimiter) {
-  const d = delimiter;
-  const source = `${list ?? ""}`;
-  return source.split(d).filter((e) => e);
+  return splitDelimitedList(`${list ?? ""}`, delimiter);
 }
 class CustomRegExp {
   regexp;

package/dist/common/utils.object.js

@@ -1,6 +1,7 @@
 import { LiveSyncError } from "./LSError.js";
+import { cloneViaJSON } from "octagonal-wheels/encoding/json";
 function asCopy(obj) {
-  return JSON.parse(JSON.stringify(obj));
+  return cloneViaJSON(obj);
 }
 function ensureError(error) {
   if (error instanceof Error) {

package/dist/concurrency/keyedPendingWork.d.ts

@@ -0,0 +1,13 @@
+/** An unclaimed value; its identity distinguishes replacements for the same key. */
+export interface PendingWork<K, T> {
+    readonly key: K;
+    readonly value: T;
+}
+/** Keep only the latest unclaimed value for each key, in replacement order. */
+export declare function createKeyedPendingWork<K, T>(keyOf: (value: T) => K): {
+    add(value: T): void;
+    peek(): PendingWork<K, T> | undefined;
+    claim(entry: PendingWork<K, T>): boolean;
+    values(): readonly T[];
+    readonly size: number;
+};

package/dist/concurrency/keyedPendingWork.js

@@ -0,0 +1,27 @@
+function createKeyedPendingWork(keyOf) {
+  const pending = /* @__PURE__ */ new Map();
+  return {
+    add(value) {
+      const key = keyOf(value);
+      pending.delete(key);
+      pending.set(key, { key, value });
+    },
+    peek() {
+      return pending.values().next().value;
+    },
+    claim(entry) {
+      if (pending.get(entry.key) !== entry) return false;
+      pending.delete(entry.key);
+      return true;
+    },
+    values() {
+      return Array.from(pending.values(), (entry) => entry.value);
+    },
+    get size() {
+      return pending.size;
+    }
+  };
+}
+export {
+  createKeyedPendingWork
+};

package/dist/conflicts/conflictCheckQueue.d.ts

@@ -0,0 +1,45 @@
+import type { FilePathWithPrefix } from "../common/types.js";
+import { type Awaitable, type Scope } from "octagonal-wheels/resource/scope";
+/** Host-owned conflict processing and observation for one queue. */
+export interface ConflictCheckQueueOptions {
+    /** Process one admitted path. Deferred cleanup occupies the same execution slot. */
+    readonly process: (path: FilePathWithPrefix, scope: Scope<undefined>) => Awaitable<unknown>;
+    /** Positive safe integer; defaults to ten. Pending paths have no fixed capacity. */
+    readonly concurrency?: number;
+    /** Observe pending plus active checks. A thrown error stops the queue after active work settles. */
+    readonly onProgress?: (remaining: number) => void;
+}
+/** One queue owns pending checks; the host owns conflict decisions and recovery policy. */
+export interface ConflictCheckQueue {
+    /** Accept a path without waiting for its check; a pending duplicate moves to the tail. */
+    enqueue(path: FilePathWithPrefix): void;
+    /** Wait for quiescence, including requeues and cleanup; false means the queue was aborted. Do not await from its processor. */
+    waitForIdle(): Promise<boolean>;
+    /** Stop admission and drain accepted work. A processor must not await its own queue's closure. */
+    close(): Promise<boolean>;
+    /** Stop admission and dispatch, join active cleanup, and return the retained, unstarted paths. */
+    abort(): Promise<readonly FilePathWithPrefix[]>;
+    /** Snapshot of unstarted paths; retained after abort or failure for the host to inspect. */
+    readonly pending: readonly FilePathWithPrefix[];
+    /** Pending and active checks, including item cleanup. */
+    readonly remaining: number;
+}
+/**
+ * Compose keyed pending checks with bounded scoped execution.
+ *
+ * Input is accepted synchronously without a fixed pending-count limit. Each
+ * execution consumes a synchronous iterable which ends when no pending path
+ * remains; later arrivals join it or start the next execution. An empty queue has no input read,
+ * timer, or worker waiting in the background.
+ *
+ * Replacement affects unclaimed entries only. A running check may enqueue its
+ * own path without waiting for an execution slot. It is not cancelled or replaced
+ * by that later input. The host remains responsible for serialising any shared
+ * resource or interaction inside the processor.
+ *
+ * Unhandled processing, cleanup, or observation errors stop further dispatch.
+ * Started work and cleanup settle before completion waiters reject; unstarted
+ * paths remain inspectable. Catch an item error inside process when the host's
+ * explicit policy is to log and continue. There is no implicit retry or logging.
+ */
+export declare function createConflictCheckQueue(options: ConflictCheckQueueOptions): ConflictCheckQueue;

package/dist/conflicts/conflictCheckQueue.js

@@ -0,0 +1,108 @@
+import { createKeyedPendingWork } from "../concurrency/keyedPendingWork.js";
+import { createNotifier } from "octagonal-wheels/concurrency/notifier";
+import { forEachInScope } from "octagonal-wheels/concurrency/scoped.iteration";
+import { withScope } from "octagonal-wheels/resource/scope";
+function createConflictCheckQueue(options) {
+  const concurrency = options.concurrency ?? 10;
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+    throw new RangeError("Conflict check concurrency must be a positive safe integer.");
+  }
+  const pending = createKeyedPendingWork((path) => path);
+  const changed = createNotifier();
+  const failures = [];
+  let accepting = true;
+  let aborted = false;
+  let stoppingAfterFailure = false;
+  let active = 0;
+  let running;
+  const remaining = () => pending.size + active;
+  const canDispatch = () => !aborted && !stoppingAfterFailure && failures.length === 0;
+  const recordFailure = (error) => {
+    accepting = false;
+    stoppingAfterFailure = true;
+    failures.push(error);
+    changed.notify();
+  };
+  const reportProgress = () => {
+    if (failures.length === 0) {
+      try {
+        options.onProgress?.(remaining());
+      } catch (error) {
+        recordFailure(error);
+      }
+    }
+    changed.notify();
+  };
+  function* availableWork() {
+    while (canDispatch()) {
+      const entry = pending.peek();
+      if (!entry) return;
+      yield entry;
+    }
+  }
+  function schedule() {
+    if (running || !canDispatch() || pending.size === 0) return;
+    running = Promise.resolve().then(
+      () => withScope(
+        void 0,
+        (parent) => forEachInScope(parent, availableWork(), { concurrency }, async (entry, child) => {
+          if (!canDispatch() || !pending.claim(entry)) return;
+          active++;
+          child.defer(() => {
+            active--;
+            reportProgress();
+          });
+          reportProgress();
+          try {
+            await options.process(entry.value, child);
+          } catch (error) {
+            accepting = false;
+            stoppingAfterFailure = true;
+            throw error;
+          }
+        })
+      )
+    ).then(() => void 0, recordFailure).finally(() => {
+      running = void 0;
+      schedule();
+      changed.notify();
+    });
+  }
+  async function waitForIdle() {
+    schedule();
+    while (running) await changed.wait();
+    if (failures.length === 1) throw failures[0];
+    if (failures.length > 1) throw new AggregateError(failures, "Conflict checks failed.");
+    return !aborted;
+  }
+  return {
+    enqueue(path) {
+      if (!accepting) throw new Error("The conflict check queue is closed.");
+      pending.add(path);
+      reportProgress();
+      schedule();
+    },
+    waitForIdle,
+    close() {
+      accepting = false;
+      schedule();
+      return waitForIdle();
+    },
+    async abort() {
+      accepting = false;
+      aborted = true;
+      changed.notify();
+      await waitForIdle();
+      return pending.values();
+    },
+    get pending() {
+      return pending.values();
+    },
+    get remaining() {
+      return remaining();
+    }
+  };
+}
+export {
+  createConflictCheckQueue
+};

package/dist/conflicts.d.ts

@@ -0,0 +1,3 @@
+export { createConflictCheckQueue } from "./conflicts/conflictCheckQueue.js";
+export type { ConflictCheckQueue, ConflictCheckQueueOptions } from "./conflicts/conflictCheckQueue.js";
+export type { FilePathWithPrefix } from "./common/types.js";

package/dist/conflicts.js

@@ -0,0 +1,4 @@
+import { createConflictCheckQueue } from "./conflicts/conflictCheckQueue.js";
+export {
+  createConflictCheckQueue
+};

package/dist/diagnostics/integrity.js

@@ -1,3 +1,4 @@
+import { withScope } from "octagonal-wheels/resource/scope";
 import {
   DOCID_SYNC_PARAMETERS,
   EntryTypes,
@@ -749,12 +750,11 @@ async function analyseDatabaseIntegrity(options) {
   let wasCancelled = cancelled(options);
   let configurationChanged = false;
   let pathEquivalenceGroups = [];
-  let ownedRemote;
   if (!wasCancelled && !isConfigurationCurrent(options)) {
     configurationChanged = true;
     appendError(errors, "configuration", "configuration-changed");
   }
-  try {
+  await withScope(void 0, async (scope) => {
     if (!wasCancelled && !configurationChanged) {
       const localRun = makeSourceRun("local", options.local);
       runs.push(localRun);
@@ -768,7 +768,14 @@ async function analyseDatabaseIntegrity(options) {
           runs.push(remoteRun);
         } else {
           try {
-            ownedRemote = await options.remote();
+            const ownedRemote = await options.remote();
+            scope.defer(async () => {
+              try {
+                await ownedRemote.close();
+              } catch {
+                appendError(errors, "remote", "source-unavailable");
+              }
+            });
             if (cancelled(options)) {
               wasCancelled = true;
             } else {
@@ -851,15 +858,7 @@ async function analyseDatabaseIntegrity(options) {
         }
       }
     }
-  } finally {
-    if (ownedRemote) {
-      try {
-        await ownedRemote.close();
-      } catch {
-        appendError(errors, "remote", "source-unavailable");
-      }
-    }
-  }
+  });
   if (cancelled(options)) wasCancelled = true;
   if (!wasCancelled && !configurationChanged && !isConfigurationCurrent(options)) {
     configurationChanged = true;

package/dist/interfaces/ServiceModule.d.ts

@@ -20,29 +20,49 @@ export interface ServiceModules {
      */
     rebuilder: Rebuilder;
 }
-export type RequiredServices<T extends keyof ServiceHub> = Pick<ServiceHub, T | "context">;
+/**
+ * Selects service dependencies from the host's service type.
+ * A context is retained when the selected source exposes one. The default
+ * source preserves the existing ServiceHub dependency contract.
+ */
+export type RequiredServices<T extends keyof THub, THub = ServiceHub> = Pick<THub, T | Extract<"context", keyof THub>>;
 export type RequiredServiceModules<T extends keyof ServiceModules> = Pick<ServiceModules, T>;
-export type RequiredServicesInterfaces<T extends keyof IServiceHub> = Pick<IServiceHub, T>;
+export type RequiredServicesInterfaces<T extends keyof IServiceHub> = RequiredServices<T, IServiceHub>;
 export type RequiredServiceModulesInterfaces<T extends keyof ServiceModules> = Pick<ServiceModules, T>;
-export type NecessaryServices<T extends keyof ServiceHub, U extends keyof ServiceModules> = {
-    services: RequiredServices<T>;
+/**
+ * Declares the Services and ServiceModules consumed by a feature.
+ * Select a more specific source to retain injectable handlers or an extended
+ * host context, or use IServiceHub for operation-only interfaces. Additional
+ * collaborators, such as a borrowed LogFunction, belong in the feature's own
+ * dependency type. This type neither selects runtime values nor owns them.
+ */
+export type NecessaryServices<T extends keyof THub, U extends keyof ServiceModules, THub = ServiceHub> = {
+    services: RequiredServices<T, THub>;
     serviceModules: RequiredServiceModules<U>;
 };
-export type NecessaryServicesInterfaces<T extends keyof IServiceHub, U extends keyof ServiceModules> = {
-    services: RequiredServicesInterfaces<T>;
-    serviceModules: RequiredServiceModulesInterfaces<U>;
-};
-export type ServiceFeatureFunction<T extends keyof ServiceHub, U extends keyof ServiceModules, TR> = (host: NecessaryServices<T, U>) => TR;
+export type NecessaryServicesInterfaces<T extends keyof IServiceHub, U extends keyof ServiceModules> = NecessaryServices<T, U, IServiceHub>;
+export type ServiceFeatureFunction<T extends keyof THub, U extends keyof ServiceModules, TR, THub = ServiceHub> = (host: NecessaryServices<T, U, THub>) => TR;
 type ServiceFeatureContext<T> = T & {
     _log: LogFunction;
 };
-export type ServiceFeatureFunctionWithContext<T extends keyof ServiceHub, U extends keyof ServiceModules, C, TR> = (host: NecessaryServices<T, U>, context: ServiceFeatureContext<C>) => TR;
+export type ServiceFeatureFunctionWithContext<T extends keyof THub, U extends keyof ServiceModules, C, TR, THub = ServiceHub> = (host: NecessaryServices<T, U, THub>, context: ServiceFeatureContext<C>) => TR;
+type AnyServiceFeature = (...args: never[]) => unknown;
+type ServiceFeatureWithArguments<T extends keyof THub, U extends keyof ServiceModules, THub = ServiceHub> = (host: NecessaryServices<T, U, THub>, ...args: never[]) => unknown;
 /**
- * Helper function to create a service feature with proper typing.
- * @param featureFunction The feature function to be wrapped.
- * @returns The same feature function with proper typing.
+ * Retains a service feature's complete function type and identity.
+ * Declare the dependency type on the feature parameter so that required
+ * collaborators, concrete service types, and returned views remain explicit.
+ * Optional arguments, overloads, generic signatures, and asynchronous results
+ * are preserved. Older unannotated callbacks retain their ServiceHub context;
+ * their dependency keys cannot be inferred from the callback body.
+ *
+ * This helper does not invoke the feature, acquire or release its dependencies,
+ * or wrap its return value or errors. The host owns composition and disposal.
+ * @param featureFunction The feature function to retain.
+ * @returns The supplied function without a runtime wrapper.
  * @example
- * const useIndexFeature = createServiceFeature((host: NecessaryServices<"appLifecycle", "storageAccess">) => {
+ * type IndexHost = NecessaryServices<"appLifecycle", "storageAccess">;
+ * const useIndexFeature = createServiceFeature((host: IndexHost) => {
  *   const { appLifecycle } = host.services;
  *   const { storageAccess } = host.serviceModules;
  *
@@ -51,18 +71,16 @@ export type ServiceFeatureFunctionWithContext<T extends keyof ServiceHub, U exte
  *     return true;
  *   });
  * });
- *
- * useIndexFeature({
- *   services: { context: serviceHub.context, appLifecycle: serviceHub.appLifecycle },
- *   serviceModules: { storageAccess },
- * });
  */
+export declare function createServiceFeature<TFeature extends ServiceFeatureWithArguments<keyof ServiceHub, keyof ServiceModules>>(featureFunction: TFeature): TFeature;
+export declare function createServiceFeature<TFeature extends AnyServiceFeature>(featureFunction: TFeature): TFeature;
 export declare function createServiceFeature<T extends keyof ServiceHub, U extends keyof ServiceModules, TR>(featureFunction: ServiceFeatureFunction<T, U, TR>): ServiceFeatureFunction<T, U, TR>;
-type ContextFactory<T extends keyof ServiceHub, U extends keyof ServiceModules, C> = (host: NecessaryServices<T, U>) => ServiceFeatureContext<C>;
-export declare function serviceFeature<T extends keyof ServiceHub, U extends keyof ServiceModules>(): {
-    create<TR>(featureFunction: ServiceFeatureFunction<T, U, TR>): ServiceFeatureFunction<T, U, TR>;
-    withContext<C extends object = object>(ContextFactory: ContextFactory<T, U, C>): {
-        create: <TR>(featureFunction: ServiceFeatureFunctionWithContext<T, U, C, TR>) => (host: NecessaryServices<T, U>, context: ServiceFeatureContext<C>) => TR;
+type ContextFactory<T extends keyof THub, U extends keyof ServiceModules, C, THub = ServiceHub> = (host: NecessaryServices<T, U, THub>) => ServiceFeatureContext<C>;
+/** Selects the host type for the existing service-feature builder. */
+export declare function serviceFeature<T extends keyof THub, U extends keyof ServiceModules, THub = ServiceHub>(): {
+    create: <TR, TFeature extends (host: NecessaryServices<T, U, THub>, ...args: never[]) => TR = ServiceFeatureFunction<T, U, TR, THub>>(featureFunction: TFeature) => TFeature;
+    withContext<C extends object = object>(ContextFactory: ContextFactory<T, U, C, THub>): {
+        create: <TR>(featureFunction: ServiceFeatureFunctionWithContext<T, U, C, TR, THub>) => (host: NecessaryServices<T, U, THub>, context: ServiceFeatureContext<C>) => TR;
     };
 };
 export {};

package/dist/interfaces/ServiceModule.js

@@ -2,10 +2,11 @@ function createServiceFeature(featureFunction) {
   return featureFunction;
 }
 function serviceFeature() {
+  function create(featureFunction) {
+    return featureFunction;
+  }
   return {
-    create(featureFunction) {
-      return featureFunction;
-    },
+    create,
     withContext(ContextFactory) {
       return {
         create: (featureFunction) => (host, context) => featureFunction(host, ContextFactory(host))

package/dist/managers/ChunkFetcher.d.ts

@@ -1,5 +1,6 @@
 import { type DocumentID } from "../common/types.js";
 import { type ChunkManager } from "./ChunkManager.js";
+import type { ChunkFetchSource } from "./chunkFetchSource.js";
 import type { IReplicatorService, ISettingService } from "../services/base/IService.js";
 export declare const EVENT_MISSING_CHUNKS = "missingChunks";
 export declare const EVENT_MISSING_CHUNK_REMOTE = "missingChunkRemote";
@@ -9,6 +10,8 @@ export type ChunkFetcherOptions = {
     chunkManager: ChunkManager;
     replicatorService: IReplicatorService;
     deliveryStallTimeoutMs?: number;
+    /** Direct hosts replace both retrieval and acceptance; the default uses the active replicator. */
+    source?: ChunkFetchSource;
 };
 export declare class ChunkFetcher {
     options: ChunkFetcherOptions;