@vrtmrz/livesync-commonlib 0.2.3 → 0.3.1

package/docs/adr/2026_11_shared_storage_path_resolution.md

@@ -0,0 +1,73 @@
+---
+date: 2026-11-03
+commonlib-version: "0.3.0"
+self-hosted-livesync-version: "1.0.44"
+status: accepted-unreleased
+---
+
+# Architectural Decision Record: Shared Storage Path Resolution
+
+## Conclusion
+
+Commonlib owns strict Unicode path comparison and resolution behind a focused
+`/storage` entry. Node and File System Access provide thin storage integrations;
+hosts retain filesystem handles, original paths, caches, watchers, and operation
+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.
+
+## Context
+
+The Self-hosted LiveSync CLI already resolves NFC-equivalent names component by
+component while preserving physical spelling. Repeating that logic in browser
+and Deno hosts would duplicate ambiguity, missing-path, and rename rules.
+Meanwhile, the legacy path union includes comparison keys, so removing a
+namespace can appear to turn a lossy comparison value back into a file path.
+
+## Decisions
+
+- Separate original document paths, unprefixed file paths, NFC refinements,
+  resolved storage paths, and comparison keys. Preserve the old public types;
+  new namespace helpers exclude their legacy comparison-key member.
+- Inject only strict directory enumeration into the resolver. Return `null`
+  for absence, and propagate permission, non-directory, and other I/O failures.
+  Resolve ambiguity before mutation, including when an exact spelling exists.
+- Copy comparison settings for one operation or scan. Retain no cross-operation
+  directory cache or persistent path mapping. Scan already resolved entries
+  once per directory, and re-resolve later lookups after external changes.
+- Preserve ordinary writes' physical spelling. An explicit rename may request
+  another spelling of the same leaf. Mutation and replacement semantics remain
+  with the storage owner; resolution is not an atomic reservation.
+- Keep string-taking storage APIs and Legacy behaviour. New physical-I/O ports
+  take `StoragePath`. Namespace routing and cryptographic document-ID derivation
+  remain separate from filesystem resolution.
+- Adopt the shared implementation in the CLI and the shared comparison and
+  namespace helpers at applicable Obsidian boundaries. WebApp and Bridge NFC
+  enablement remains separate work, including admission, events, and caches.
+
+## Alternatives considered
+
+- Duplicating the CLI resolver per host would duplicate the behavioural contract
+  and its failure handling.
+- Renaming all physical files to NFC would alter user-owned storage and require
+  collision recovery beyond the accepted scope.
+- A persistent alias map or shared directory cache would introduce invalidation,
+  restart, and lifecycle obligations which current directory reads avoid.
+- Combining namespace, Unicode form, and case in a family of filename types
+  would conflate independent properties. Comparison keys instead name their
+  purpose and their storage or document domain.
+
+## Consequences and verification
+
+Hosts supply trustworthy complete listings and preserve distinct names before
+constructing keyed collections. Filesystems or APIs which hide aliases limit
+what the resolver can observe. Host concurrency and permission checks remain
+necessary after resolution.
+
+Contract tests cover spelling, ambiguity, strict failures, snapshots, scans,
+and renames. Packed-consumer tests check assignability and platform bundling.
+The downstream CLI retains its behavioural suite against the exact packed
+candidate. Memory-backed File System Access tests establish adapter behaviour;
+real-browser permissions and Deno integration require their own host evidence.

package/docs/conflict-resolution.md

@@ -74,7 +74,7 @@ A host must not apply a dialogue result after either compared revision has cease
 
 ## Scheduling conflict checks
 
-The unreleased `@vrtmrz/livesync-commonlib/conflicts` entry exports
+The `@vrtmrz/livesync-commonlib/conflicts` entry, published in Commonlib 0.2.3, exports
 `createConflictCheckQueue`. The host supplies a `process(path, scope)` callback
 and may observe pending plus active checks through `onProgress`. Concurrency
 defaults to ten and includes each item's deferred cleanup. The host continues

package/docs/design_docs/storage_path_resolution.md

@@ -0,0 +1,305 @@
+---
+date: 2026-11-03
+commonlib-version: "0.3.0"
+self-hosted-livesync-version: "1.0.44"
+status: accepted-unreleased
+---
+
+# Shared storage path resolution
+
+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.
+
+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)
+provides consumer examples.
+
+The baseline is Commonlib 0.3.0 and the CLI implementation reviewed in
+[Self-hosted LiveSync #1309](https://github.com/vrtmrz/obsidian-livesync/pull/1309)
+at `2716d68b3d21d493cdfdefa0857fad4c6a3c522a`. The existing
+[Unicode identity contract](../unicode-path-identity.md) continues to govern
+Metadata IDs, remote admission, defaults, and database migration.
+
+## Ownership
+
+Commonlib owns path comparison, component-by-component resolution, ambiguity
+checks, and thin platform-storage integrations. Hosts own root selection,
+permissions, filesystem handles, file objects, watchers, caches, and operation
+lifecycle. A resolver performs directory reads but no filesystem mutation.
+
+Keep the existing Node and File System Access storage APIs and their Legacy
+behaviour. Compose the resolver only for NFC mode. Its comparison policy is
+an immutable snapshot for one operation or scan, copied at construction;
+a settings change requires a new composition. Explicit case-sensitive and
+case-insensitive lookups use
+the corresponding snapshot, without mutating a shared resolver.
+
+## Path types
+
+Separate namespace, Unicode form, comparison use, and storage resolution.
+An actual filename can already be NFC, so these are not mutually exclusive
+string categories.
+
+| Type | Meaning | Producer |
+| --- | --- | --- |
+| `FilePath` | Original spelling without a Metadata namespace; no NFC or resolution guarantee. | Existing input and host boundaries. |
+| `DocumentPath` | Original spelling with an optional recognised Metadata namespace; excludes comparison keys. | Document input and namespace helpers. |
+| `NfcFilePath` | A `FilePath` normalised to NFC, without lower-casing. | The shared NFC normalisation function. |
+| `StoragePath` | A root-relative storage target whose existing components use their resolved spelling. | Resolver or supported physical enumeration. |
+| `PathComparisonKey<"storage">` | A comparison key for a path within one storage root. | The shared comparison helper. |
+| `PathComparisonKey<"document">` | A comparison key which retains the document namespace. | The shared comparison helper. |
+
+`StoragePath` is not proof that an entry exists, still exists, is a file,
+or cannot change concurrently. A write target may contain missing components.
+The root is the empty path; each operation retains its existing root rules.
+
+Reuse the existing `FilePath` and OW `TaggedType` definitions. Add independent
+symbols for refinements: nesting `TaggedType<FilePath, "StoragePath">` would
+intersect incompatible values of OW's existing tag property.
+
+```ts
+declare const unicodeForm: unique symbol;
+declare const storagePath: unique symbol;
+
+type DocumentPath = Exclude<FilePathWithPrefix, FilePathWithPrefixLC>;
+
+type NfcFilePath = FilePath & {
+    readonly [unicodeForm]: "NFC";
+};
+
+type StoragePath = FilePath & {
+    readonly [storagePath]: true;
+};
+
+type PathComparisonKey<Domain extends "storage" | "document"> =
+    TaggedType<string, `PathComparisonKey:${Domain}`>;
+```
+
+Use `NfcFilePath` within the normalisation boundary initially. Publish the
+path and key types needed by consumers of the new focused API. Preserve the
+existing definitions of `FilePathWithPrefix` and `FilePathWithPrefixLC` at
+compatibility entry points. Do not alias either old type to a new key type:
+that would change existing assignability.
+
+The old `FilePathWithPrefix` union includes both `FilePath` and
+`FilePathWithPrefixLC`. The new `DocumentPath` intentionally removes the latter.
+The old scanner's `convertCase()` returns its `LC` type even when case-sensitive
+handling retains letter case. New code therefore names its output by its
+comparison purpose, not an assumed lower-case form.
+
+Brand values at the boundary which establishes their meaning. `parseFilePath`
+validates raw storage input using the existing path vocabulary without changing
+its spelling. `parseDocumentPath` accepts original document-path strings;
+namespace routing precedes storage validation. Neither input helper recovers
+original spelling from a comparison key. NFC conversion and resolution establish their own refinements.
+Keep casts inside those owning implementations; consumer code receives the
+typed result. The existing string-taking APIs remain compatibility escape
+routes, so this migration does not claim to make all old call sites type-safe.
+Within the new integrations, physical-I/O ports accept `StoragePath`; NFC
+normalisation or key generation alone cannot supply that argument.
+
+## Namespaces and comparison
+
+Namespace helpers accept `DocumentPath`, return a separate namespace and
+`FilePath`, and recognise the existing `i:`, `ix:`, and `ps:` rules. Split one
+namespace only; further colons belong to the body. The caller handles the
+namespace's meaning before submitting a filesystem path to the resolver.
+Chunk prefixes and obfuscated IDs remain `DocumentID` concerns.
+
+Document comparison preserves the namespace; storage comparison does not
+receive one. A normal document and an internal document with the same body
+remain distinct document identities. Neither comparison-key domain is accepted
+by the resolver or by the new namespace helpers.
+
+The comparison policy uses the existing `normalisePathForIdentity` operation,
+then the existing `toLowerCase()` rule only when configured. NFC conversion
+alone produces `NfcFilePath`; the complete comparison pipeline produces a key.
+It does not infer the host filesystem's case rules or introduce a new Unicode
+case-folding rule. Preserve original paths alongside keys; a key is never
+converted back into an original path.
+
+```ts
+type PathComparisonSettings = Readonly<{
+    pathNormalizationVersion: 0 | 1;
+    handleFilenameCaseSensitive: boolean;
+}>;
+
+type DocumentPathParts = Readonly<{
+    prefix: "" | "i:" | "ix:" | "ps:";
+    path: FilePath;
+}>;
+
+declare function splitDocumentPath(path: DocumentPath): DocumentPathParts;
+declare function joinDocumentPath(parts: DocumentPathParts): DocumentPath;
+
+declare function getStoragePathComparisonKey(
+    path: FilePath, settings: PathComparisonSettings
+): PathComparisonKey<"storage">;
+
+declare function getDocumentPathComparisonKey(
+    path: DocumentPath, settings: PathComparisonSettings
+): PathComparisonKey<"document">;
+```
+
+Namespace routing and cryptographic document-ID derivation remain outside the
+resolver. The new comparison helpers must retain the existing key bytes for
+each supported policy; extracting them does not rewrite IDs or stored paths.
+
+## Directory and resolver contract
+
+The only injected I/O operation enumerates immediate children using their
+actual names and kinds. Paths are relative to the selected root and use `/`.
+`null` means the directory is absent. Permission failures, a non-directory
+parent, and other I/O failures reject; they are not empty listings.
+
+The existing storage `list()` methods can hide some failures as empty results.
+Provide a strict enumeration path for the resolver while preserving the old
+methods' published behaviour. Reuse each platform's containment and symbolic-link
+checks. Keep native handles and platform stat types behind this boundary.
+
+```ts
+type DirectoryEntry = Readonly<{
+    name: string;
+    kind: "file" | "directory";
+}>;
+
+type ReadDirectory = (
+    physicalDirectory: StoragePath
+) => Promise<readonly DirectoryEntry[] | null>;
+
+type StorageEntry = Readonly<{
+    path: StoragePath;
+    kind: "file" | "directory";
+}>;
+
+type ResolvedRename = Readonly<{
+    source: StoragePath;
+    target: StoragePath;
+}>;
+
+interface StoragePathResolver {
+    resolveExisting(path: FilePath): Promise<StoragePath | null>;
+    resolveForWrite(path: FilePath): Promise<StoragePath>;
+    resolveRename(source: FilePath, target: FilePath): Promise<ResolvedRename | null>;
+    listResolvedDirectory(path: StoragePath): Promise<readonly StorageEntry[] | null>;
+}
+
+declare function createStoragePathResolver(options: Readonly<{
+    readDirectory: ReadDirectory;
+    policy: Readonly<{
+        pathNormalizationVersion: 1;
+        handleFilenameCaseSensitive: boolean;
+    }>;
+}>): StoragePathResolver;
+```
+
+`DirectoryEntry.name` is an immediate child name, never a path. Reject malformed
+entries at the enumeration boundary. Add a separate filename brand only when a
+consumer boundary needs it; do not publish a family of filename variants now.
+
+The resolver uses complete sibling enumeration before deciding uniqueness;
+a literal match does not override a second equivalent name. File/directory
+collisions count as ambiguity. A unique file cannot be traversed as a parent.
+An individual lookup checks candidates for each requested component; a full
+scan checks every sibling group before returning that directory's entries.
+
+| Operation | Result |
+| --- | --- |
+| `resolveExisting` | Resolve each existing component to its listed spelling; return `null` on absence. |
+| `resolveForWrite` | Preserve listed names for existing components and the requested spelling for the missing suffix. |
+| `resolveRename` | Resolve both ends. If the target resolves to the source, retain the resolved parent and the explicitly requested leaf spelling. Return `null` when the source is absent. |
+| `listResolvedDirectory` | Read an already resolved directory, check all sibling identities, and return actual child paths for scanning and direct access. |
+
+All operations reject ambiguity using the shared `AmbiguousNormalisedPathError`.
+Include the requested path and conflicting actual names for diagnosis. Preserve
+I/O failures separately from absence. Host catch blocks must propagate these
+failures instead of converting them to a missing file or a successful partial
+scan.
+
+Normal writes preserve existing Unicode spelling. Explicit renames may change
+it. Existing-destination replacement policy and the actual rename, write,
+rollback, or deletion remain the storage owner's responsibility. Resolution is
+not an atomic reservation; existing host operation ordering and platform
+protections remain necessary. The guarantee is limited to names exposed by the
+host's supported listing.
+
+## Composition and adoption
+
+The `/storage` entry contains the host-neutral types, comparison and
+namespace helpers, and resolver. It imports no Node, DOM, database, or Service
+Hub runtime. `/node` and `/browser` expose their platform integrations through
+the existing bundling boundaries.
+
+Commonlib owns `UnicodeResolvingNodeStorageAdapter` and delegates
+its resolution to the common implementation. The current CLI candidate adopts
+the focused API while retaining Legacy delegation and thin compatibility
+methods. File System Access uses the same resolver, including host paths which
+operate directly on handles. Bridge supplies a Deno directory reader and uses
+the same contract in an unreleased integration candidate.
+
+Keep the resolver free of persistent mappings, cross-operation caches, watchers,
+retry owners, and disposal requirements. A full scan descends through the
+resolved entries and reads each directory once. A later lookup re-reads the
+relevant directories, including after a file-object cache hit. OW Scope or
+context can own host operation resources where needed; the resolver itself
+requires no resource scope.
+
+Hosts retain original physical paths alongside any comparison keys. Detect
+aliases before collapsing them into a keyed collection. Cache invalidation,
+queue ownership, and watch-event reconciliation must follow the same comparison
+policy without losing distinct names. A deletion event may name an entry which
+is already absent; preserve that event path rather than trying to recover its
+spelling from a live directory lookup. Check rename events as an ordered change
+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.
+
+The CLI candidate uses the shared Node resolver, and the current Obsidian
+candidate uses shared namespace and comparison helpers while retaining Vault
+APIs and its alias guard. The matching Journal and P2P host adoption remains
+unreleased in Self-hosted LiveSync [#1309](https://github.com/vrtmrz/obsidian-livesync/pull/1309).
+The browser resolver is a general primitive, not WebApp NFC support: WebApp
+remains Legacy-only and rejects an explicit version `1` at startup. WebPeer
+has no Vault filesystem and is not an NFC filesystem host.
+
+Bridge's Deno integration is also an unreleased candidate. NFC mode is an
+explicit per-peer opt-in, and every peer in a group must use the same path
+version. Its ordinary case-mismatch check remains enabled; the Bridge-wide
+`disableCheckingConfigMismatch: true` override disables that case check only
+and does not bypass path-version admission. Preserve the existing coordinated
+Rebuild/Fetch migration and remote mismatch protection. This design adds no
+automatic migration or translation between identity modes.
+
+## Verification
+
+Check the public declarations against the actual published path types and OW
+tag implementation. Positive cases cover source paths, namespace round trips,
+and independent NFC/storage refinements. Negative cases cover raw strings,
+prefix-bearing paths at the resolver, comparison keys at resolution and namespace
+boundaries, and mixing the two key domains. Retain an assertion that the legacy
+`LC` type is still assignable to the legacy union, but not to `DocumentPath`.
+
+Implementation must preserve the existing CLI behavioural cases and apply one
+resolver contract to Node and File System Access, with Bridge-specific checks:
+
+- NFD files and mixed-spelling parents remain addressable without implicit renames.
+- New components retain the requested spelling under the actual parent.
+- File, directory, and case collisions reject before mutation, including exact-match requests.
+- Permission and listing failures do not become absence, creation, deletion, or partial-scan success.
+- Explicit spelling renames preserve contents and the host's replacement and recovery semantics.
+- External additions, deletions, renames, and collisions are observed after earlier cache hits.
+- Full scans inspect each directory once; Legacy behaviour and namespace separation remain unchanged.
+- Watcher deletion/creation sequences, restart state, and cache keys preserve the intended identity.
+
+Packed-package checks must verify the focused entry and platform bundling
+boundaries. Real browser and Deno checks establish their host behaviour;
+Commonlib's memory and Node tests alone do not establish those guarantees.

package/docs/development.md

@@ -6,7 +6,7 @@ This document is for Commonlib developers. Package consumers should begin with t
 
 The source tree is larger than the supported package surface. Consumers may import only paths in the generated package export map:
 
-- `src/index.ts`, `src/context.ts`, `src/settings.ts`, `src/remoteConfigurations.ts`, `src/p2p/index.ts`, `src/platform/browser/index.ts`, and `src/platform/node/index.ts` define the focused entries;
+- `src/index.ts`, `src/context.ts`, `src/storage.ts`, `src/settings.ts`, `src/remoteConfigurations.ts`, `src/p2p/index.ts`, `src/platform/browser/index.ts`, and `src/platform/node/index.ts` define the focused entries;
 - `src/conflicts.ts` defines the host-owned conflict-check queue contract; `src/concurrency/keyedPendingWork.ts` remains package-private;
 - `src/replication/index.ts` defines the focused provider-capability and interaction contract for hosts which compose replication;
 - `src/diagnostics/index.ts` defines read-only Usage and integrity inspection, report projection, and formatting; hosts own the run dialogue and output destination;
@@ -19,6 +19,16 @@ The source tree is larger than the supported package surface. Consumers may impo
 
 Files elsewhere under `src` are implementation details unless a focused entry re-exports them or the compatibility inventory names them. Do not use the source layout, TypeScript path aliases, or the presence of generated declarations as evidence of a supported consumer import.
 
+## Storage path boundary
+
+The unreleased `/storage` entry 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.
+The [Unicode identity contract](unicode-path-identity.md) retains its existing
+Metadata, remote-admission, and database-migration rules.
+
 ## Module filenames
 
 For new or renamed TypeScript and JavaScript source modules, start the filename
@@ -111,6 +121,10 @@ The revision-tree safety rules are documented in [Conflict resolution and file p
 
 `LiveSyncReplicator.unit.spec.ts` owns the CouchDB remote-chunk batch contract: a mixed `_all_docs` result must return each available document even when another keyed row reports an error. `ChunkFetcher.unit.spec.ts` owns the consumer behaviour: it writes valid returned chunks and emits `missingChunkRemote` only for requested IDs which are absent from the returned set. Extend both sides when changing remote chunk acquisition or missing-chunk delivery.
 
+Direct CouchDB hosts supply a database-bound `ChunkFetchSource` through the optional `LiveSyncLocalDB` runtime factory. `LiveSyncManagers` passes it to the shared `ChunkFetcher`; application hosts omit it and retain active-replicator retrieval and local persistence. The direct source reads the prepared database and accepts results without writing them back. Recreate it with each database instance so reopening cannot retain a closed connection. `ChunkFetcher.source.unit.spec.ts` covers direct retrieval, delayed availability without change notifications, bounded failure, and teardown. `DirectFileManipulatorV2.integration.spec.ts` covers encrypted arrival before and during an outstanding read, with assertions that the reader does not write Chunks back.
+
+`DirectFileWatchOwner` owns the direct watch lifecycle. Its per-client state retains unfinished reads, same-document delivery ownership, and pending checkpoint persistence across stop and restart. Each watch session separately owns its pending documents, connection generation, and timers. Named operations receive explicit contexts through Octagonal Wheels `bindContext`; per-file and per-delivery scopes release their bookkeeping after the operation settles. Feed cancellation and timer cancellation remain synchronous in `endWatch()`, independently of unfinished reads or host callbacks. The owner tests cover retries, safe checkpoint positions, replacement sessions, and failure handling; `DirectFileManipulatorV2.unit.spec.ts` retains the public state, database binding, and close-order checks.
+
 `RemoteService.connect()` returns an owned CouchDB connection as the existing flat `{ db, info }` result with an idempotent `close()` method. `close()` first aborts outstanding abort-capable requests in that connection, then closes the PouchDB handle. The owner must transfer or close the complete connection; passing only `db` loses the cancellation boundary. A skipped information request retains the established placeholder in `info` for compatibility. `OwnedCouchDBConnection`, its opening options, and the checked `CouchDBReplicationConnection` are Commonlib-owned types exported by the existing CouchDB replicator module. The legacy `_ensureConnection()` helper continues to return a raw PouchDB handle for source compatibility; new Commonlib code must retain and close the complete owned connection instead.
 
 The one-shot CouchDB connectivity preflight is the first bounded consumer. It applies an internal 60-second safety fuse to the complete preflight on the web-compatible fetch path, disables fallback into the non-abortable native request adapter, and clears the fuse before transferring the connection to replication. The fuse is a last-resort wall-clock bound on an owner which would otherwise remain pending indefinitely; it is not the expected completion time, a per-request inactivity timeout, a user setting, or the `useTimeouts` changes-feed setting. The explicitly selected native Request API retains its previous unbounded behaviour because its current host adapter cannot honour `AbortSignal`. Extend `RemoteService.unit.spec.ts` and the one-shot ownership table in `LiveSyncReplicator.unit.spec.ts` when changing this boundary. Do not use `Promise.race()` to report a mutating native request as cancelled while it can still complete remotely.

package/docs/platform-storage.md

@@ -61,6 +61,67 @@ Writes create missing parent directories. Listing returns direct child paths rel
 
 The File System Access API does not expose portable creation times or permit setting file times. Consumers must not rely on identical timestamp fidelity across the two adapters.
 
+## 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
+resolution while retaining the names listed by their filesystem. Hosts still
+own the selected identity mode and its database migration.
+
+```ts
+import { UnicodeResolvingNodeStorageAdapter } from '@vrtmrz/livesync-commonlib/node';
+import { parseFilePath } from '@vrtmrz/livesync-commonlib/storage';
+
+const storage = new UnicodeResolvingNodeStorageAdapter(
+    '/srv/livesync',
+    () => settings.pathNormalizationVersion,
+    () => !settings.handleFilenameCaseSensitive,
+);
+const existing = await storage.resolveLogicalPath(parseFilePath('Café.md'), undefined, false);
+if (existing !== null) {
+    const content = await storage.readResolved(existing);
+}
+```
+
+The browser equivalent is `UnicodeResolvingFileSystemAccessStorageAdapter`
+from `/browser`, constructed with an authorised root handle and the same
+settings callbacks. Version `0` delegates to the existing storage behaviour;
+version `1` resolves every component against complete sibling listings. Normal
+writes preserve existing spelling. Node's explicit `rename` can change a leaf's
+Unicode or letter-case spelling; the browser adapter retains its existing
+operation set and does not add a rename primitive.
+
+`AmbiguousNormalisedPathError` from `/storage` reports multiple equivalent
+names, even when one is a literal match. Preserve that error and directory or
+permission failures. Only absence produces `null`; a failure must not be used
+as permission to create a file or as a successful partial scan.
+
+For another host, compose `createStoragePathResolver({ readDirectory, policy })`
+from `/storage`. `readDirectory` accepts a `StoragePath` and returns immediate
+child names and kinds, or `null` for absence. Propagate other failures. The
+resolver copies one NFC policy and retains no directory cache. For a full scan,
+start at `resolveForWrite(parseFilePath(''))`, then recurse through
+`listResolvedDirectory` entries using the same resolver. Each directory is read
+once. Re-resolve later operations so external changes are visible.
+
+`FilePath` retains original, unprefixed spelling. `StoragePath` records that
+existing components have been resolved; it does not guarantee existence or
+reserve a target. `parseDocumentPath` marks an original document-path input,
+and `splitDocumentPath` separates one recognised namespace before host routing.
+Use `joinDocumentPath` to restore it. `getStoragePathComparisonKey` and
+`getDocumentPathComparisonKey` return distinct comparison-only types; the latter
+preserves the namespace. Keep the original path beside each key. The old
+`FilePathWithPrefix` and `FilePathWithPrefixLC` remain available for compatibility.
+
+The [design](design_docs/storage_path_resolution.md) defines the detailed
+contract. These primitives do not enable NFC automatically in a host
+application. WebApp remains Legacy-only and rejects explicit version `1` at
+startup. The Bridge Deno integration is an unreleased candidate; version `1`
+is an explicit peer opt-in, and every peer in a group must use the same path
+version. Its ordinary case-mismatch check remains separate from path-version
+admission. See [Unicode path identity](unicode-path-identity.md#supported-hosts)
+for the current publication and host-adoption boundaries.
+
 ## Bundling boundary
 
 Browser consumers import only `@vrtmrz/livesync-commonlib/browser`. Packed-package tests build that entry with browser conditions and verify that the Node implementation is absent. Node consumers import `@vrtmrz/livesync-commonlib/node`; the root and context entries do not load Node built-ins.

package/docs/proven-in-use.md

@@ -6,9 +6,23 @@ The useful evidence is host- and contract-specific. Focused Commonlib tests esta
 
 The code paths below identify maintained Self-hosted LiveSync composition points as examples. The reviewed downstream revision and compatibility imports are recorded in [`migration/downstream-imports.json`](migration/downstream-imports.json), which is regenerated by the package-boundary tooling rather than copied into prose links. These snapshots may become historical as the maintained downstream changes; this page is optional context, not a support entitlement or release or adoption gate.
 
-## Blob construction and comparison: candidate integration
+## Published shared-runtime integration
 
-The unreleased Blob extraction delegates construction to
+Commonlib [0.2.3](https://github.com/vrtmrz/livesync-commonlib/releases/tag/0.2.3)
+is published on npm through `latest` and `next`, with an exact dependency on
+Octagonal Wheels 0.1.56. Self-hosted LiveSync
+[1.0.44](https://github.com/vrtmrz/obsidian-livesync/releases/tag/1.0.44)
+adopts the published Commonlib package. Its
+[integration record](https://github.com/vrtmrz/obsidian-livesync/pull/1307)
+separates the final source checks from the focused browser, CLI, and real-Obsidian
+results for unchanged consumer boundaries. The earlier candidate measurements
+below remain historical evidence at their recorded versions.
+
+<a id="blob-construction-and-comparison-candidate-integration"></a>
+
+## Blob construction and comparison: published integration
+
+Commonlib 0.2.3 delegates Blob construction to
 `octagonal-wheels/binary/blob`. Commonlib retains the old creation imports and
 wraps `toBlob` as `createBlob`, while document classification, binary decoding,
 and content-comparison policy remain in Commonlib. The legacy
@@ -31,13 +45,12 @@ absence on the native path. The
 the existing Commonlib imports after packaging.
 
 Earlier candidate checks explicitly installed the selected unpublished Octagonal
-Wheels tarball in the disposable consumer. The current unreleased Commonlib
-integration pins the published Octagonal Wheels 0.1.56 dependency and uses the
-ordinary package gate without a candidate override. Self-hosted LiveSync tests its hidden-file
-loading and revision handling through the legacy entry with matching
-candidate tarballs. Those consumer checks are distinct from Commonlib-owned
-compatibility contracts; real-Obsidian and mobile validation of this extraction
-remain pending.
+Wheels tarball in the disposable consumer. Commonlib 0.2.3 pins the published
+Octagonal Wheels 0.1.56 dependency and uses the ordinary package gate without a
+candidate override. The subsequent Self-hosted LiveSync integration uses the
+exact published Commonlib package. Its recorded application builds and focused
+real-Obsidian conflict and catalogue checks complement the Commonlib-owned
+compatibility contracts; they do not establish physical mobile-device behaviour.
 
 ## Obsidian plug-in
 
@@ -254,7 +267,9 @@ Use the named consumer paths as integration examples, while retaining the owners
 This optional page preserves examples, current integration evidence, and history. It does not define supported behaviour or create a release or adoption gate; package guarantees are described by the published contracts and release policy. When this page is updated, distinguish current use, historical use, Commonlib-owned tests, downstream tests, and real-runtime observations, and keep each claim within its evidence.
 
 
-## Shared value helpers: candidate integration
+<a id="shared-value-helpers-candidate-integration"></a>
+
+## Shared value helpers: published integration
 
 The [runtime helper tests](../src/common/utils.runtime-tools.unit.spec.ts)
 characterise duration thresholds, delimiter empty parts, and JSON conversion
@@ -264,16 +279,18 @@ to detach settings before an operation. The shared package owns the value
 operations. The packed [type fixture](../_tools/fixtures/runtime-tools-types.ts) and
 [runtime fixture](../_tools/fixtures/runtime-tools-runtime.mjs) exercise those
 public duration and delimiter compatibility entries. The original checks used an
-unpublished dependency candidate; the current integration pins the published
+unpublished dependency candidate; Commonlib 0.2.3 pins the published
 Octagonal Wheels 0.1.56 release. Source tests cover the internal copy adapter.
 LiveSync continues to use the existing compatibility entry points, including
 duration labels in ConfigSync and tagged lists in settings. Source and packed
 checks do not establish real-Obsidian rendering or device behaviour.
 
 
-## Shared multi-key locking: candidate integration
+<a id="shared-multi-key-locking-candidate-integration"></a>
+
+## Shared multi-key locking: published integration
 
-The unreleased candidate imports `withLocks` directly from
+Commonlib 0.2.3 imports `withLocks` directly from
 `octagonal-wheels/concurrency/lock` for offline Metadata repair and file-event
 processing. Commonlib retains the `processFileEvent-` namespace, unique sorted
 document IDs, and conflict hooks deferred until every lock has been released.

package/docs/releasing.md

@@ -34,12 +34,39 @@ Inspect the lockfile diff before committing it. A dependency-only maintenance ch
 
 When a named host-specific risk is not established by the Commonlib owner checks, run the relevant downstream workflow against an exact Self-hosted LiveSync ref which consumes the package. It installs the tarball produced from the selected Commonlib commit and runs LiveSync type checks, unit tests, plug-in and application builds, and CLI E2E. Real Obsidian E2E remains local-only and is appropriate when the named risk concerns actual plug-in composition, storage, UI, or platform behaviour. These checks are conditional on the risk; LiveSync adoption is not a general release prerequisite.
 
+## Coordinating package and application releases
+
+A downstream release which imports a new package entry point or depends on new
+behaviour must use a published immutable Commonlib version. Prepare and test
+consumer branches against an exact local pack while the package is unreleased,
+but retain those results as local-candidate evidence.
+
+1. Complete the Commonlib owner checks and review the release source. For a
+   stable package, the exact reviewed release commit must be on `main` before
+   staging, as required by the trusted workflow below. An optional prerelease
+   can select a reviewed draft branch instead.
+2. Stage the exact package to `next`, validate the published registry artefact,
+   and complete any specifically required downstream checks before promoting
+   that same version to `latest`. These remain separate maintainer operations.
+3. Update each releasing consumer to the exact validated version and registry
+   integrity. Self-hosted LiveSync records one root dependency for its plug-in,
+   CLI, WebApp, and WebPeer; Bridge records its own Deno import map and lockfile.
+   Verify clean installation and the affected consumer boundaries before their
+   release workflows run.
+
+Commonlib publication does not require every consumer branch to be merged.
+Conversely, publishing Commonlib does not release an application or migrate an
+existing database. A source checkout with the same version label as a registry
+package is not a substitute for that immutable registry artefact.
+
 ## Version compatibility policy
 
 The Commonlib 0.2 policy begins with 0.2.0 and does not retroactively change compatibility expectations for published 0.1.x versions. Within 0.2.x, preserve published APIs, types, behaviour, supported persisted data, and exported `compat/*` paths. Intentional breaking changes belong in 0.3.0. Consumers may declare a range such as `^0.2.0`; lockfiles and `npm ci` remain the reproducible install path.
 
 For 0.2.3, the documented exceptions are the `HandlerFunction.setHandler` and `LazyHandlerFunction.setHandler` return types changing from `void` to `UnregisterFunction`, and `timeDeltaToHumanReadable(Infinity)` returning `∞y` instead of `Infinityy`. The setter types now describe the existing runtime return. Custom implementations and test doubles whose setters return `void` must provide an unregister function; ordinary callers may continue to ignore the result. These are the specific 0.2.3 exceptions to the policy.
 
+Version 0.3.0 introduces a source compatibility change: the custom client passed to `LiveSyncJournalReplicator.ensureBucketIsCompatible` must provide `hasRemoteJournals(): Promise<boolean>`. The operation distinguishes an empty bucket from Journal files left without an identifying milestone. Keeping it required makes missing client capability a type error. The standard `JournalSyncCore` client already supplies it. This change uses the next minor version under the policy above.
+
 ## Preparing a release
 
 Choose the version explicitly. For the 0.2 line, start at 0.2.0. A stable candidate can use its final version on the `next` dist-tag, then be checked by exact source revision and tarball SHA-256 before the same version is promoted to `latest`. No `-next.N` or `-rc.N` version is required; use a separate prerelease version only when it is useful for a distinct candidate. Package-proof versions are local artefacts and cannot be staged.

package/docs/service-feature-composition.md

@@ -2,11 +2,17 @@
 date: 2026-10-25
 commonlib-version: "0.2.0"
 self-hosted-livesync-version: "1.0.40"
-status: unreleased
+status: published
 ---
 
 # Service feature composition
 
+Publication update, 2nd November, 2026: the Service Hub source selection, narrowed
+host dependencies, and signature-preserving composition helpers are published
+in Commonlib [0.2.3](https://github.com/vrtmrz/livesync-commonlib/releases/tag/0.2.3)
+and used by Self-hosted LiveSync 1.0.44. The front matter retains the original
+review date and version baseline.
+
 This guide is for Commonlib and maintained-host developers who are adding behaviour to the Service Hub composition. It explains when to extend a Service, create a serviceFeature, share a ServiceModule, or introduce a class which owns a resource.
 
 The choice is primarily about dependency direction and ownership. Mutable state alone does not require a class or a ServiceModule.