@vrtmrz/livesync-commonlib 0.3.1 → 0.3.2

package/dist/replication/journal/LiveSyncJournalReplicator.js

@@ -12,7 +12,7 @@ import { MinioStorageAdapter } from "./objectstore/MinioStorageAdapter.js";
 import { LiveSyncAbstractReplicator } from "../LiveSyncAbstractReplicator.js";
 import { ensureRemoteIsCompatible } from "../../pouchdb/LiveSyncDBFunctions.js";
 import { getEffectiveTweakValues } from "../../pouchdb/LiveSyncDBFunctions.js";
-import { assertSupportedPathNormalizationVersion, getPathNormalizationVersion } from "../../common/pathNormalization.js";
+import { assertSupportedPathNormalizationVersion } from "../../common/pathNormalization.js";
 import { JournalStorageReadStatuses } from "./objectstore/JournalStorageAdapter.js";
 import { computeKeyedId, configuredIdKey } from "../../common/idDerivation.js";
 import { decryptString, encryptString } from "../../encryption/stringEncryption.js";
@@ -31,6 +31,12 @@ import {
   forgetJoinedDevice as forgetJoinedDeviceFromStore,
   projectJoinedDevices
 } from "../joinedDevices.js";
+import {
+  journalVersionRange,
+  hasJournalNodeDeclarations,
+  matchesJournalPathIdentity,
+  inspectJournalPathIdentity
+} from "./journalCompatibility.js";
 const MILSTONE_DOCID = "_00000000-milestone.json";
 async function readRemoteMilestone(client) {
   const result = await client.downloadJsonWithResult(MILSTONE_DOCID);
@@ -38,23 +44,6 @@ async function readRemoteMilestone(client) {
   if (result.status === JournalStorageReadStatuses.NOT_FOUND) return void 0;
   throw result.error;
 }
-const currentVersionRange = {
-  min: 0,
-  max: 2,
-  current: 2
-};
-function journalVersionRange(setting) {
-  if (getPathNormalizationVersion(setting) === 1) return { min: 4, max: 4, current: 4 };
-  return configuredIdKey(setting) && setting.encrypt && setting.usePathObfuscation ? { min: 3, max: 3, current: 3 } : currentVersionRange;
-}
-function pathIdentityFromJournalRange(range) {
-  if (range?.min === 4 && range?.max === 4) return 1;
-  if (!range) return 0;
-  if (Number.isSafeInteger(range.min) && Number.isSafeInteger(range.max) && range.min >= 0 && range.max <= 3 && range.min <= range.max) {
-    return 0;
-  }
-  throw new Error("The Journal declares an unsupported path identity range.");
-}
 class LiveSyncJournalReplicator extends LiveSyncAbstractReplicator {
   get client() {
     return this.setupJournalSyncClient();
@@ -89,17 +78,8 @@ class LiveSyncJournalReplicator extends LiveSyncAbstractReplicator {
     return this._client;
   }
   async isBucketPathIdentityCompatible(setting, milestone, client) {
-    const pathVersion = getPathNormalizationVersion(setting);
-    const ranges = milestone?.node_chunk_info ?? {};
-    const nodes = /* @__PURE__ */ new Set([...milestone?.accepted_nodes ?? [], ...Object.keys(ranges)]);
-    for (const node of nodes) {
-      const range = ranges[node];
-      const usesNFC = range?.min === 4 && range?.max === 4;
-      if (usesNFC !== (pathVersion === 1)) return false;
-    }
-    const preferred = milestone?.tweak_values?.[DEVICE_ID_PREFERRED];
-    if (preferred && getPathNormalizationVersion(preferred) !== pathVersion) return false;
-    if (nodes.size === 0 && await client.hasRemoteJournals()) {
+    if (!matchesJournalPathIdentity(setting, milestone)) return false;
+    if (!hasJournalNodeDeclarations(milestone) && await client.hasRemoteJournals()) {
       throw new Error(
         "The Journal compatibility milestone is missing. Rebuild from the authoritative Vault before synchronising."
       );
@@ -144,22 +124,13 @@ class LiveSyncJournalReplicator extends LiveSyncAbstractReplicator {
   async inspectRemotePathIdentity(setting) {
     const client = this.setupJournalSyncClient(setting);
     const milestone = await readRemoteMilestone(client);
-    const versions = /* @__PURE__ */ new Set();
-    const ranges = milestone?.node_chunk_info ?? {};
-    const nodes = /* @__PURE__ */ new Set([...milestone?.accepted_nodes ?? [], ...Object.keys(ranges)]);
-    for (const node of nodes) {
-      versions.add(pathIdentityFromJournalRange(ranges[node]));
-    }
-    const preferred = milestone?.tweak_values?.[DEVICE_ID_PREFERRED];
-    if (preferred) versions.add(getPathNormalizationVersion(preferred));
-    if (versions.size > 1) throw new Error("The Journal has conflicting path identity declarations.");
-    if (nodes.size === 0 && await client.hasRemoteJournals()) {
+    const identity = inspectJournalPathIdentity(milestone);
+    if (!hasJournalNodeDeclarations(milestone) && await client.hasRemoteJournals()) {
       throw new Error(
         "The Journal path identity declaration is missing. Use matching settings or Rebuild from the authoritative Vault."
       );
     }
-    const version = [...versions][0];
-    return version === void 0 ? { status: "empty" } : { status: "configured", pathNormalizationVersion: version };
+    return identity;
   }
   /** Lock existing journals for replacement without declaring the replacement's identity. */
   async markRemoteLockedForRebuild(setting) {
@@ -178,7 +149,7 @@ class LiveSyncJournalReplicator extends LiveSyncAbstractReplicator {
       throw new Error("Could not upload remote milestone");
     }
   }
-  async ensureBucketIsCompatible(deviceNodeID, currentVersionRange2, setting = this.currentSettings, client = this.setupJournalSyncClient(setting), recordTweakAssessment) {
+  async ensureBucketIsCompatible(deviceNodeID, currentVersionRange, setting = this.currentSettings, client = this.setupJournalSyncClient(setting), recordTweakAssessment) {
     const downloadedMilestone = await readRemoteMilestone(client) ?? false;
     if (!await this.isBucketPathIdentityCompatible(setting, downloadedMilestone || void 0, client)) {
       return "INCOMPATIBLE";
@@ -193,7 +164,7 @@ class LiveSyncJournalReplicator extends LiveSyncAbstractReplicator {
       downloadedMilestone,
       setting,
       deviceNodeID,
-      currentVersionRange2,
+      currentVersionRange,
       {
         app_version: this.env.services.API.getAppVersion(),
         plugin_version: this.env.services.API.getPluginVersion(),
@@ -356,6 +327,18 @@ class LiveSyncJournalReplicator extends LiveSyncAbstractReplicator {
       (client) => client.sendLocalJournal(showingNotice)
     );
   }
+  /** Return the stopped Journal from the current transfer client without creating another client. */
+  getStoppedJournal() {
+    return this._client?.getStoppedJournal();
+  }
+  /** Recheck connectivity and compatibility, skip the confirmed Journal, and resume receipt. */
+  async skipStoppedJournalAndResume(setting, stopped, showingNotice = true) {
+    return await this.runDirectionalReplication(
+      setting,
+      showingNotice,
+      (client) => client.skipStoppedJournalAndResume(stopped, showingNotice)
+    );
+  }
   async replicateAllFromServer(setting, showingNotice) {
     return await this.runDirectionalReplication(
       setting,
@@ -721,6 +704,10 @@ ${ex.message}`, LOG_LEVEL_NOTICE);
     return Promise.resolve(false);
   }
 }
+function isLiveSyncJournalReplicator(value) {
+  return value instanceof LiveSyncJournalReplicator;
+}
 export {
-  LiveSyncJournalReplicator
+  LiveSyncJournalReplicator,
+  isLiveSyncJournalReplicator
 };

package/dist/replication/journal/journalCompatibility.d.ts

@@ -0,0 +1,9 @@
+import { type ChunkVersionRange, type EntryMilestoneInfo, type RemoteDBSettings } from "../../common/types.js";
+import type { PathIdentityInspection } from "../../pouchdb/pathIdentityCompatibility.js";
+export declare function journalVersionRange(setting: RemoteDBSettings): ChunkVersionRange;
+export declare function pathIdentityFromJournalRange(range: ChunkVersionRange | undefined): 0 | 1;
+/** Without a node declaration, the caller must inspect storage before treating the bucket as empty. */
+export declare function hasJournalNodeDeclarations(milestone: EntryMilestoneInfo | undefined): boolean;
+export declare function matchesJournalPathIdentity(setting: RemoteDBSettings, milestone: EntryMilestoneInfo | undefined): boolean;
+/** Project declarations only; an empty result does not establish that remote storage is empty. */
+export declare function inspectJournalPathIdentity(milestone: EntryMilestoneInfo | undefined): PathIdentityInspection;

package/dist/replication/journal/journalCompatibility.js

@@ -0,0 +1,58 @@
+import {
+  DEVICE_ID_PREFERRED
+} from "../../common/types.js";
+import { configuredIdKey } from "../../common/idDerivation.js";
+import { getPathNormalizationVersion } from "../../common/pathNormalization.js";
+const currentVersionRange = {
+  min: 0,
+  max: 2,
+  current: 2
+};
+function journalVersionRange(setting) {
+  if (getPathNormalizationVersion(setting) === 1) return { min: 4, max: 4, current: 4 };
+  return configuredIdKey(setting) && setting.encrypt && setting.usePathObfuscation ? { min: 3, max: 3, current: 3 } : currentVersionRange;
+}
+function pathIdentityFromJournalRange(range) {
+  if (range?.min === 4 && range?.max === 4) return 1;
+  if (!range) return 0;
+  if (Number.isSafeInteger(range.min) && Number.isSafeInteger(range.max) && range.min >= 0 && range.max <= 3 && range.min <= range.max) {
+    return 0;
+  }
+  throw new Error("The Journal declares an unsupported path identity range.");
+}
+function journalPathIdentityNodes(milestone) {
+  return /* @__PURE__ */ new Set([...milestone?.accepted_nodes ?? [], ...Object.keys(milestone?.node_chunk_info ?? {})]);
+}
+function hasJournalNodeDeclarations(milestone) {
+  return journalPathIdentityNodes(milestone).size > 0;
+}
+function matchesJournalPathIdentity(setting, milestone) {
+  const pathVersion = getPathNormalizationVersion(setting);
+  const ranges = milestone?.node_chunk_info ?? {};
+  for (const node of journalPathIdentityNodes(milestone)) {
+    const range = ranges[node];
+    const usesNFC = range?.min === 4 && range?.max === 4;
+    if (usesNFC !== (pathVersion === 1)) return false;
+  }
+  const preferred = milestone?.tweak_values?.[DEVICE_ID_PREFERRED];
+  return !preferred || getPathNormalizationVersion(preferred) === pathVersion;
+}
+function inspectJournalPathIdentity(milestone) {
+  const versions = /* @__PURE__ */ new Set();
+  const ranges = milestone?.node_chunk_info ?? {};
+  for (const node of journalPathIdentityNodes(milestone)) {
+    versions.add(pathIdentityFromJournalRange(ranges[node]));
+  }
+  const preferred = milestone?.tweak_values?.[DEVICE_ID_PREFERRED];
+  if (preferred) versions.add(getPathNormalizationVersion(preferred));
+  if (versions.size > 1) throw new Error("The Journal has conflicting path identity declarations.");
+  const version = [...versions][0];
+  return version === void 0 ? { status: "empty" } : { status: "configured", pathNormalizationVersion: version };
+}
+export {
+  hasJournalNodeDeclarations,
+  inspectJournalPathIdentity,
+  journalVersionRange,
+  matchesJournalPathIdentity,
+  pathIdentityFromJournalRange
+};

package/dist/replication/journal/journalReceive.d.ts

@@ -0,0 +1,23 @@
+import type { EntryDoc } from "../../common/types.js";
+import type { ProcessingEntry } from "./journalRecords.js";
+type ChunkReadRow = {
+    id?: string;
+    error?: string;
+};
+type WriteResult = PouchDB.Core.Error | PouchDB.Core.Response;
+export declare function partitionJournalDocuments(entries: readonly ProcessingEntry[]): {
+    chunks: ProcessingEntry[];
+    docs: ProcessingEntry[];
+};
+/** Chunks have stable content, so only absent identifiers need a new local revision. */
+export declare function selectChunksToSave(chunks: readonly ProcessingEntry[], rows: readonly ChunkReadRow[]): PouchDB.Core.PutDocument<EntryDoc>[];
+export declare function hasJournalWriteErrors(results: readonly WriteResult[]): boolean;
+/** Report persisted Chunks even when another row failed, but require every requested Chunk for completion. */
+export declare function assessChunkWrites<T extends PouchDB.Core.PutDocument<EntryDoc>>(chunks: readonly T[], results: readonly WriteResult[]): {
+    persisted: T[];
+    failed: boolean;
+};
+export declare function journalMetadataRevisions(docs: readonly ProcessingEntry[]): PouchDB.Core.RevisionDiffOptions;
+/** Retain complete transferred Metadata, including revision ancestry, for each missing revision. */
+export declare function selectMetadataToSave(docs: readonly ProcessingEntry[], diff: PouchDB.Core.RevisionDiffResponse): ProcessingEntry[];
+export {};

package/dist/replication/journal/journalReceive.js

@@ -0,0 +1,44 @@
+function partitionJournalDocuments(entries) {
+  const chunks = [];
+  const docs = [];
+  for (const entry of entries) {
+    (entry._id.startsWith("h:") ? chunks : docs).push(entry);
+  }
+  return { chunks, docs };
+}
+function selectChunksToSave(chunks, rows) {
+  if (rows.some((row) => "error" in row && row.error !== "not_found")) {
+    throw new Error("Could not inspect existing Chunks");
+  }
+  const existingIDs = new Set(rows.map((row) => row.id).filter((id) => id !== void 0));
+  return chunks.filter((entry) => !existingIDs.has(entry._id)).map((entry) => ({ ...entry, _rev: void 0 }));
+}
+function hasJournalWriteErrors(results) {
+  return results.some((row) => "error" in row);
+}
+function assessChunkWrites(chunks, results) {
+  const persistedIDs = new Set(results.filter((row) => !("error" in row)).map((row) => row.id));
+  return {
+    persisted: chunks.filter((entry) => persistedIDs.has(entry._id)),
+    failed: hasJournalWriteErrors(results) || chunks.some((entry) => !persistedIDs.has(entry._id))
+  };
+}
+function journalMetadataRevisions(docs) {
+  return docs.reduce(
+    (revisions, entry) => ({ ...revisions, [entry._id]: [...revisions[entry._id] ?? [], entry._rev] }),
+    {}
+  );
+}
+function selectMetadataToSave(docs, diff) {
+  return docs.filter(
+    (entry) => entry._id in diff && "missing" in diff[entry._id] && (diff[entry._id].missing?.indexOf(entry._rev) ?? 0) !== -1
+  );
+}
+export {
+  assessChunkWrites,
+  hasJournalWriteErrors,
+  journalMetadataRevisions,
+  partitionJournalDocuments,
+  selectChunksToSave,
+  selectMetadataToSave
+};

package/dist/replication/journal/journalRecords.d.ts

@@ -0,0 +1,10 @@
+import { type EntryDoc } from "../../common/types.js";
+export type ProcessingEntry = PouchDB.Core.PutDocument<EntryDoc> & PouchDB.Core.GetMeta;
+export declare function serializeDoc(doc: EntryDoc): Uint8Array;
+export declare function decodeJournalRecords(data: Uint8Array): {
+    ok: true;
+    docs: ProcessingEntry[];
+} | {
+    ok: false;
+    stage: "decode" | "parse";
+};

package/dist/replication/journal/journalRecords.js

@@ -0,0 +1,96 @@
+import {} from "../../common/types.js";
+import { escapeNewLineFromString, unescapeNewLineFromString } from "../../common/utils.js";
+const RECORD_SPLIT = `
+`;
+const UNIT_SPLIT = ``;
+const te = new TextEncoder();
+function parseJournalRecord(value) {
+  const parsed = JSON.parse(value);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new TypeError("Invalid Journal record");
+  }
+  const record = parsed;
+  if (typeof record._id !== "string" || record._id.length === 0) {
+    throw new TypeError("Invalid Journal document identifier");
+  }
+  if (record._id.startsWith("h:")) {
+    if (record._id.length <= 2 || typeof record._rev !== "string" || typeof record.data !== "string") {
+      throw new TypeError("Invalid Journal Chunk record");
+    }
+  } else if (typeof record._rev !== "string" || record._rev.length === 0) {
+    throw new TypeError("Invalid Journal Metadata revision");
+  }
+  return parsed;
+}
+function decodeCompactJournalRecord(value) {
+  const separatorIndex = value.indexOf(UNIT_SPLIT);
+  if (separatorIndex === -1) {
+    return { ok: false, stage: "parse" };
+  }
+  const idPart = value.substring(1, separatorIndex);
+  if (!idPart.startsWith("h:") || idPart.length <= 2) {
+    return { ok: false, stage: "parse" };
+  }
+  const dataPart = value.substring(separatorIndex + 1);
+  return {
+    ok: true,
+    doc: {
+      _id: idPart,
+      data: unescapeNewLineFromString(dataPart),
+      type: "leaf",
+      _rev: ""
+    }
+  };
+}
+function decodeJournalRecordFrame(frame, decoder) {
+  let value;
+  try {
+    value = decoder.decode(frame);
+  } catch {
+    return { ok: false, stage: "decode" };
+  }
+  if (value.startsWith("~")) {
+    return decodeCompactJournalRecord(value);
+  }
+  try {
+    return { ok: true, doc: parseJournalRecord(value) };
+  } catch {
+    return { ok: false, stage: "parse" };
+  }
+}
+function serializeDoc(doc) {
+  if (doc._id.startsWith("h:")) {
+    const data = doc.data;
+    const writeData = escapeNewLineFromString(data);
+    return te.encode(`~${doc._id}${UNIT_SPLIT}${writeData}${RECORD_SPLIT}`);
+  }
+  return te.encode(JSON.stringify(doc) + RECORD_SPLIT);
+}
+function decodeJournalRecords(data) {
+  if (data.length === 0) {
+    return { ok: true, docs: [] };
+  }
+  if (data[data.length - 1] !== 10) {
+    return { ok: false, stage: "parse" };
+  }
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let idxFrom = 0;
+  const result = [];
+  while (idxFrom < data.length) {
+    const idxTo = data.indexOf(10, idxFrom);
+    if (idxTo === -1 || idxTo === idxFrom) {
+      return { ok: false, stage: "parse" };
+    }
+    const record = decodeJournalRecordFrame(data.slice(idxFrom, idxTo), decoder);
+    if (record.ok === false) {
+      return record;
+    }
+    result.push(record.doc);
+    idxFrom = idxTo + 1;
+  }
+  return { ok: true, docs: result };
+}
+export {
+  decodeJournalRecords,
+  serializeDoc
+};

package/docs/adr/2026_11_shared_storage_path_resolution.md

@@ -2,7 +2,7 @@
 date: 2026-11-03
 commonlib-version: "0.3.0"
 self-hosted-livesync-version: "1.0.44"
-status: accepted-unreleased
+status: published
 ---
 
 # Architectural Decision Record: Shared Storage Path Resolution
@@ -16,7 +16,9 @@ lifecycle. The [design](../design_docs/storage_path_resolution.md) defines the
 accepted contract and remaining adoption work.
 
 Accepted on 2026-11-03 against the versions recorded above. The implementation
-is unreleased. Publication does not by itself enable NFC in WebApp or Bridge.
+is published in [Commonlib 0.3.1](https://www.npmjs.com/package/@vrtmrz/livesync-commonlib/v/0.3.1).
+The original date and reviewed versions retain the accepted baseline.
+Publication does not by itself enable NFC in WebApp or Bridge.
 
 ## Context
 

package/docs/design_docs/storage_path_resolution.md

@@ -2,7 +2,7 @@
 date: 2026-11-03
 commonlib-version: "0.3.0"
 self-hosted-livesync-version: "1.0.44"
-status: accepted-unreleased
+status: published
 ---
 
 # Shared storage path resolution
@@ -10,8 +10,8 @@ status: accepted-unreleased
 This design moves the CLI's existing Unicode-aware path resolution into
 Commonlib so Node, File System Access, and Bridge can apply the same naming
 rules. The shared resolver, path types, and Node and File System Access
-integrations are implemented as unreleased additions. Installing the package
-does not enable NFC in an existing host or migrate its database.
+integrations are published in Commonlib 0.3.1. Installing the package does
+not enable NFC in an existing host or migrate its database.
 
 Accepted on 2026-11-03. The [decision record](../adr/2026_11_shared_storage_path_resolution.md)
 records the ownership and compatibility choices. The [platform guide](../platform-storage.md#unicode-path-resolution)
@@ -258,10 +258,11 @@ of state, including hosts which report them as deletion and creation.
 ## Current adoption and publication status
 
 The shared `/storage` contract, Node and File System Access adapters, and
-explicit `DirectFileManipulator` path-version option are unreleased additions
-after the published Commonlib `0.3.0` artefact. They require a new immutable
-package version; a source checkout with version string `0.3.0` is not the
-registry artefact.
+explicit `DirectFileManipulator` path-version option are published in
+[Commonlib 0.3.1](https://www.npmjs.com/package/@vrtmrz/livesync-commonlib/v/0.3.1).
+The original decision date and reviewed versions above retain the accepted
+baseline. These additions are absent from the registry artefact `0.3.0`;
+a source checkout carrying that version label is not the published artefact.
 
 The CLI candidate uses the shared Node resolver, and the current Obsidian
 candidate uses shared namespace and comparison helpers while retaining Vault

package/docs/development.md

@@ -21,8 +21,8 @@ Files elsewhere under `src` are implementation details unless a focused entry re
 
 ## Storage path boundary
 
-The unreleased `/storage` entry owns namespace helpers, comparison keys, and
-strict component resolution. The [design](design_docs/storage_path_resolution.md)
+The `/storage` entry, published in Commonlib 0.3.1, owns namespace helpers,
+comparison keys, and strict component resolution. The [design](design_docs/storage_path_resolution.md)
 and [decision record](adr/2026_11_shared_storage_path_resolution.md) separate
 that contract from host handles, caches, watchers, and migration. See the
 [platform guide](platform-storage.md#unicode-path-resolution) for composition.

package/docs/journal-receive-recovery.md

@@ -0,0 +1,66 @@
+---
+date: 2026-11-04
+commonlib-version: "0.3.1"
+self-hosted-livesync-version: "1.0.44"
+status: unreleased
+---
+
+# Journal receive failures and recovery
+
+This document describes unreleased receive behaviour. Hosts choose when to
+offer the manual skip operation and remain responsible for Vault reflection
+and conflict handling.
+
+## Stop and retry by default
+
+A per-Journal decode, record-processing, or write failure stops receipt. The
+failed Journal and all later Journals remain unacknowledged. The next normal
+receive attempt retries the failed Journal before proceeding to later Journals.
+Partial progress does not change this rule.
+
+Chunks are written before Metadata, so a Chunk failure prevents that Journal's
+Metadata stage. Metadata retains its received revision ancestry through
+`new_edits: false`, whose empty success result is valid. Successfully written
+records remain in the database when another record fails. There is no rollback.
+
+A retry avoids rewriting existing records and delivers accepted Metadata to
+the host again, including revisions saved before an earlier partial failure.
+The host must tolerate repeated delivery. Chunk-arrival events describe only
+successful writes. The `knownIDs` set suppresses unnecessary
+outbound transfer; it does not prove that a receive has completed locally.
+
+Warnings identify the failed Journal key and the stage where receipt stopped,
+without logging document contents. A stop request lets current I/O settle and
+closes the receive operation; it is not a Journal failure.
+
+## Skip the stopped Journal and resume
+
+When receipt stops on a Journal failure, a host may offer the explicit
+'Skip stopped Journal and resume' operation. It accepts the exact stopped
+failure snapshot, marks only that Journal received, and resumes receipt of the
+remaining Journals. If another Journal fails, receipt stops at that Journal
+and requires a separate decision.
+
+Skipping does not roll back partial writes. It can leave content or revision
+history missing, and receipt of later Journals does not prove that every file
+can be reconstructed or reflected to storage. Each skip acknowledges the
+failed Journal despite its warning.
+
+The stopped failure is runtime state, not a persistent skip mode or failure
+queue. After a restart, normal receipt must encounter the failure again before
+the host can offer a skip for it.
+
+## Replay and host boundaries
+
+The existing 'Reset journal received history' operation clears `receivedFiles`
+and `knownIDs`, while retaining the local database and `sentFiles`. After the
+failure has been corrected, resetting this history lets receipt replay remote
+Journals other than those sent by this device. Replay requires the affected
+remote objects to remain available and readable; resetting history cannot
+recreate missing remote bytes.
+
+A host operation which replaces the local database, such as CLI Fetch, has
+separate reconstruction and completion rules. Repeating Fetch is not the
+same-database retry described above. Journal receipt also remains separate
+from Vault reflection and conflict handling; hosts must preserve their own
+failure and content-protection checks.

package/docs/platform-storage.md

@@ -63,8 +63,8 @@ The File System Access API does not expose portable creation times or permit set
 
 ## Unicode path resolution
 
-The following APIs are unreleased additions after Commonlib 0.3.0. Node and
-File System Access hosts can use the same NFC comparison and component
+These APIs are published in [Commonlib 0.3.1](https://www.npmjs.com/package/@vrtmrz/livesync-commonlib/v/0.3.1).
+Node and File System Access hosts can use the same NFC comparison and component
 resolution while retaining the names listed by their filesystem. Hosts still
 own the selected identity mode and its database migration.
 

package/docs/unicode-path-identity.md

@@ -109,11 +109,13 @@ the package protocol support alone does not mean those host integrations have
 shipped.
 
 The shared `/storage` resolver, Node and File System Access adapters, and
-explicit `DirectFileManipulator` path-version option are later unpublished
-additions described in the [shared storage path design](design_docs/storage_path_resolution.md).
-They are not in the registry artefact `0.3.0` and require a new immutable
-Commonlib package version. A source checkout carrying the same version string
-does not make these additions part of the published artefact.
+explicit `DirectFileManipulator` path-version option are published in
+[Commonlib 0.3.1](https://www.npmjs.com/package/@vrtmrz/livesync-commonlib/v/0.3.1),
+as described in the [shared storage path design](design_docs/storage_path_resolution.md).
+They are absent from the registry artefact `0.3.0`; select the new immutable
+version rather than a source checkout carrying an older version label. Shared
+path adoption remains in [LiveSync #1315](https://github.com/vrtmrz/obsidian-livesync/pull/1315)
+and [Bridge #92](https://github.com/vrtmrz/livesync-bridge/pull/92).
 
 | Consumer surface | Published baseline | Current candidate status |
 | --- | --- | --- |
@@ -122,7 +124,7 @@ does not make these additions part of the published artefact.
 | Bridge | Legacy version `0` remains the default baseline. | The Bridge candidate enables version `1` only by explicit peer opt-in; every peer in a group must use the same path version. Its ordinary case-mismatch check remains separate from the required version check. |
 | WebApp | Legacy version `0` only. | WebApp remains Legacy-only; an explicit version `1` is rejected at startup. The browser storage primitive alone does not enable application support. |
 | WebPeer | A vaultless P2P utility. | It is not an NFC filesystem host. |
-| `DirectFileManipulator` | The published package rejects a remote declaring the NFC feature. | The unpublished option defaults to version `0`, accepts explicit `0` or `1`, and rejects a populated database in the opposite mode. The caller still owns physical path handling. |
+| `DirectFileManipulator` | Commonlib `0.3.1` supports explicit version `1`; omitted or `0` retains Legacy identity. A populated database in the opposite mode is rejected. | The caller still owns physical path handling and coordinated migration. |
 
 `PathService` owns logical ID derivation. In the unreleased LiveSync host
 candidate, the CLI resolves NFC-equivalent names against directory entries
@@ -172,8 +174,7 @@ checkpoints; the P2P source mark and target checkpoint handle database
 replacement. These operations do not rewrite IDs or merge histories in place.
 P2P retains its existing source selection during Fetch.
 
-Published Commonlib direct file access refuses a remote which declares the NFC
-feature. The unpublished `DirectFileManipulator` addition exposes explicit
+Commonlib 0.3.1 `DirectFileManipulator` exposes explicit
 `pathNormalizationVersion` options, defaulting to `0`: missing or `0` retains
 Legacy and rejects an NFC database; `1` accepts NFC and rejects a populated
 Legacy database before feature negotiation can change its declaration. A

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",