@vrtmrz/livesync-commonlib 0.3.0 → 0.3.2

package/docs/adr/2026_11_shared_storage_path_resolution.md

@@ -0,0 +1,75 @@
+---
+date: 2026-11-03
+commonlib-version: "0.3.0"
+self-hosted-livesync-version: "1.0.44"
+status: published
+---
+
+# 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 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
+
+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/design_docs/storage_path_resolution.md

@@ -0,0 +1,306 @@
+---
+date: 2026-11-03
+commonlib-version: "0.3.0"
+self-hosted-livesync-version: "1.0.44"
+status: published
+---
+
+# 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 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)
+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 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
+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 `/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.
+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

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

@@ -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
+
+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.
+
+```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/releasing.md

@@ -34,6 +34,31 @@ 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.