@vrtmrz/livesync-commonlib 0.1.44 → 0.2.1

package/docs/development.md

@@ -18,6 +18,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.
 
+## Module filenames
+
+For new or renamed TypeScript and JavaScript source modules, start the filename
+with an upper-case letter when the file contains a class with the same name,
+such as `ServiceHub.ts`. Use a lower-case initial when the module primarily
+exports functions, such as `fastForward.ts`. Follow the surrounding filename
+style for the rest of the basename. Corresponding test files use the same
+basename, such as `fastForward.unit.spec.ts`. Retain established names for
+unrelated files and separate conventions for components or other file types.
+
 ## Service composition and state ownership
 
 Commonlib uses four related forms of composition. Choose between them by ownership and dependency direction, not merely by whether an implementation has mutable state.
@@ -29,6 +39,8 @@ Commonlib uses four related forms of composition. Choose between them by ownersh
 
 When a feature needs state, separate the component which owns that state, its transitions, and its invariants from the code which connects it to application lifecycle events and downstream effects. Give the stateful component narrow collaborators or callbacks rather than the complete Service Hub or application core. Keep application-level handler registration and host-specific presentation in the surrounding serviceFeature. A handler or effect which is part of the state contract, such as querying unresolved errors or reporting their first occurrence, may remain inside the stateful component when its input and output ports are explicit and bounded.
 
+Settings storage follows the same ownership boundary. Each host selects one exact-key asynchronous `ValueStore & ValueDeleter` at its composition root and supplies it as the setting service's required `deviceValues` dependency. `setting.deviceValues` is that root; `setting.config` wraps it with the existing Vault and database-suffix scope, and the Service Hub `config` property aliases the same view. Commonlib does not discover browser globals or provide a module-global fallback. Keep existing local keys on the exact-key root, preserve configuration key names, and await Value Store operations. See [Settings lifecycle](settings-lifecycle.md#host-storage-for-device-values-and-configuration) for the key mapping and host example.
+
 Existing features illustrate this direction:
 
 - `targetFilter.ts` keeps each cache or readiness gate inside the factory which owns the corresponding predicate. `useTargetFilters` composes those predicates and registers them in the required order.
@@ -127,15 +139,15 @@ The compatibility event bridge delegates lifecycle and status requests to the st
 
 The physical room, WebRTC peer, and relay-socket boundaries are documented in [P2P transport lifecycle](p2p-transport-lifecycle.md). In particular, normal shutdown leaves the Trystero room without closing raw peer connections directly.
 
-Self-hosted LiveSync remains the principal downstream consumer. A Commonlib change is not ready for publication until the exact packed artefact has also passed the applicable LiveSync type checks, unit and integration tests, application builds, CLI E2E, and focused real-Obsidian E2E.
+Self-hosted LiveSync remains a principal maintained consumer. Commonlib's normal publication gate is its own type, unit, integration, and packed-boundary checks, as described in [the release runbook](releasing.md). Run targeted downstream or real-runtime checks against the exact packed artefact when a named host-specific risk is not established by those owner tests; consumer adoption and downstream test completion are not general release prerequisites.
 
 Commonlib owner tests exercise the real implementation behind each focused result and lifecycle contract. A consumer-owned unit test may inject the smallest structural capability it uses and provide its own fake or spy when that current test needs isolation. Do not publish Vitest-specific mocks, expose private service constructors, or refactor a production boundary merely to create possible future test infrastructure. Mock and spy helpers are not a prerequisite for the LiveSync 1.0 package-boundary work; add them only with the consumer test which requires them, or after that release work.
 
-Prefer an object or callback injected at the host composition boundary over replacing an ESM module namespace. If a proposed focused API would require global mutation, import-order coupling, hidden construction, or private nominal types to substitute later, stop and review the production design before stabilising it. Exact-package downstream checks and focused real-runtime E2E remain responsible for proving the real package and host composition together.
+Prefer an object or callback injected at the host composition boundary over replacing an ESM module namespace. If a proposed focused API would require global mutation, import-order coupling, hidden construction, or private nominal types to substitute later, stop and review the production design before stabilising it. Use exact-package downstream checks and focused real-runtime E2E for named host-specific risks which the owner tests cannot establish.
 
 Commonlib publishes the typed English messages which it owns and uses them when a host does not provide a translator. A host may inject a translator through `ServiceContext`; the full multilingual catalogue and language-selection state belong to that host and are not part of the Commonlib package.
 
-Keep [the maintained-host evidence](proven-in-use.md) aligned with the downstream source and gates. If a host no longer consumes a focused entry, a test is retired, or a compatibility path receives a reviewed replacement, update the consumer-facing account as part of the same maintenance rather than leaving historical adoption as a current support claim.
+The [maintained-host examples and evidence](proven-in-use.md) are optional context, not a support entitlement or release or adoption gate. When that page is updated, distinguish current use, historical use, Commonlib-owned results, downstream tests, and real-runtime observations, and keep each claim within the evidence.
 
 ## Integration tests
 

package/docs/offline-scanner.md

@@ -1,7 +1,7 @@
 ---
-date: 2026-09-04
-commonlib-version: "0.1.21"
-self-hosted-livesync-version: "1.0.24"
+date: 2026-10-25
+commonlib-version: "0.2.0"
+self-hosted-livesync-version: "1.0.40"
 status: unreleased
 ---
 
@@ -31,15 +31,15 @@ The tables below cover only paths which remain after identity validation, the ho
 
 The `initialized` marker records that a full-scan invocation has reached its aggregate-result boundary and that later invocations may restore stored storage-event operations. It is not a successful-scan marker: the first invocation records it after an aggregate `false` result, `true`, or an accepted partial result. An exception before the aggregate result is produced does not reach that write.
 
-Storage-event restoration is a bounded start-up recovery step. Restored events bypass their former batch delay, but `restoreState()` waits for their actual file operations to finish and preserves snapshot sentinel ordering before the file collections are compared. Saved events run first because a deletion or rename can carry operation intent which is no longer visible in the current storage listing. An individual restored operation failure is logged and does not prevent the scan from examining the resulting current state. The following full scan then makes the final reconciliation decision.
+Storage-event restoration is a bounded start-up recovery step. Restored events bypass their former batch delay, but `restoreState()` waits for their actual handler outcomes and snapshot ordering before the file collections are compared. Saved events run first because a deletion or rename can carry operation intent which is no longer visible in the current storage listing. An individual restored operation failure remains in the pending snapshot and is logged; it does not prevent the scan from examining current state or independent paths. The following full scan then makes the final reconciliation decision.
 
-This ordering does not mean that storage unconditionally overwrites the replay result. The action matrix remains authoritative: when a replayed operation leaves an ambiguous pair, such as a storage file alongside a deleted database entry, the selected policy may deliberately return `skipped` rather than guess which side is intended. This boundary does not include events which are buffered or received later, and it must not be confused with a host's separate replication-result queue.
+This ordering does not mean that storage unconditionally overwrites the replay result. The action matrix remains authoritative: when a replayed operation leaves an ambiguous pair, such as a storage file alongside a deleted database entry, the selected policy may deliberately return `skipped` rather than guess which side is intended. A failed replay does not become a completed operation; a later scan may still reconcile its current pair. This start-up recovery boundary is separate from later watcher work and a host's replication-result queue.
 
 ### Stored event interpretation
 
-The storage-event snapshot contains operations which the previous runtime observed but had not begun or which were still waiting for their batch boundary. It is not a file-content journal and does not discover changes made while the application was stopped. An operation which had already been removed from the queue and entered file processing is also outside the persisted boundary. The following full scan remains responsible for observing the current storage state across all of these gaps.
+The storage-event snapshot retains every accepted operation while it is buffered, waiting for a batch boundary, or in a handler. It remains there until the operation has a durable local result, is proved already represented or safely covered by a successful successor, or ends in a skip explicitly allowed by policy. A `false` handler result or exception leaves the saved operation pending. A failed initial snapshot prevents the handler from starting; a later snapshot failure is reported and cannot be treated as completion. Ordered snapshot writes prevent an older asynchronous save from replacing a newer pending view. The snapshot records operation intent, not file content, and cannot recover bytes or events which the host never persisted or delivered; the full scan continues to observe current storage state.
 
-A restored event is an operation intent which must be revalidated against the current exact storage path before it can cause a database side effect. Its saved file stub, timestamps, and optional editor cache describe the earlier observation; they are not authoritative file content after a restart. Whenever an inclusion is still applicable, the handler reads a fresh stub and content from current storage. Whenever an ordinary deletion's expected absence is contradicted by a current storage item, that deletion is suppressed and the full scan evaluates that current item instead.
+A restored event is an operation intent which must be revalidated against the current exact storage path before it can cause a database side effect. Its saved file stub, timestamps, and optional editor cache describe the earlier observation; they are not authoritative file content after a restart. Whenever an inclusion is still applicable, the handler reads a fresh stub and current content when the operation runs. Whenever an ordinary deletion's expected absence is contradicted by a current storage item, that deletion is suppressed and the full scan evaluates that current item instead.
 
 For this check, an exact path means that the canonical path returned by storage has the saved spelling after ordinary separator normalisation. A file returned only through a case-insensitive lookup does not prove the saved inclusion path. A same-ID rename remains the explicit case-change path described below.
 
@@ -58,7 +58,7 @@ The standard-file revalidation contract is:
 | Case-only or otherwise same-ID `RENAME` | A current selected file resolves to the renamed canonical path      | Update that single document's path and current content without a separate deletion   |
 | Case-only or otherwise same-ID `RENAME` | The current identity does not support the saved rename              | Do not replay the rename; let the full scan evaluate the current path                |
 
-An inability to inspect the current path is not proof of absence. Revalidation therefore suppresses a destructive half when storage inspection fails, records the failure, and leaves the following scan to report whether reconciliation can proceed. Target-file policy and file-size limits are evaluated from current settings rather than inherited from the saved event.
+An inability to inspect the current path is not proof of absence. Revalidation suppresses a destructive half when storage inspection fails, records the failure, and leaves the operation pending. The full scan can still examine the current state and reports any selected-pair failure under its strict or explicitly partial completion policy. Target-file policy and file-size limits are evaluated from current settings rather than inherited from the saved event.
 
 The unreleased rename-exclusion guard retains `renameTarget` when a rename is converted to deletion during target filtering. Unlike an ordinary deletion, this intent can remove a file from synchronisation without removing it from storage. The guard distinguishes deliberate exclusion from transient case-collision rejection, preserves a recreated source, and permits a deliberately excluded same-ID destination without requiring that destination to disappear. Older snapshots without this optional field retain the absence-only rule. See [Storage events and database-to-storage reflection](storage-events-and-reflection.md) for the exact admission conditions and the separate ordinary watcher boundary.
 
@@ -138,11 +138,13 @@ By default, the complete scan returns `false` when any pair is `failed`, and ret
 
 Self-hosted LiveSync enables this policy only for ordinary Obsidian start-up, where one unavailable path must not prevent unaffected files from synchronising. Fast Setup, Fetch, Rebuild, direct scans, and CLI mirror or daemon paths retain the strict default.
 
-## Equal-time files without a recorded revision
+## Files in the same timestamp bucket
 
-An equal modification time does not establish that the storage file is unchanged. Before completing such a pair, the scanner asks the file handler to record its current database revision if device-local provenance is absent. The handler reads the actual storage and database content under its document lock and records the revision only when both contain the same bytes, the database has no conflicting leaf, and its current revision agrees with the one observed by the scan. It rechecks the storage snapshot, database revision, and absent provenance before writing the record. This operation writes neither storage content nor a database revision.
+For a `both` pair which selects `NEWER_WINS` (`sync-newer`), equal raw modification times and distinct times within the platform tolerance do not establish that the storage file is unchanged. The scanner first asks the file handler to record provenance for the current database revision only when current storage and one unambiguous live revision have matching content. The handler checks the storage bytes and database revision under the document lock, then revalidates the storage snapshot, current revision, and absent provenance before writing the record. This check writes neither storage content nor a database revision. The existing selection, file-size, and conflict policies still apply, and the `DB_APPLY` action remains unchanged.
 
-An existing provenance record keeps its branch identity even when the file bytes match another revision. An unreadable record, unavailable content, differing bytes, a competing branch, or a changing snapshot leaves provenance untouched. The scan still completes that equal-time pair; a later file event or incoming reflection retains the ordinary conservative conflict policy. If the local database has already advanced past the file's content, the equal-time repair cannot establish its earlier origin.
+The result of `tryRecordUntrackedFileRevision()` is not an edit predicate. Its `false` can mean that provenance already exists, content differs, history conflicts, required content or provenance is unavailable, or state changed during verification. When it returns `false`, the scanner uses the ordinary, non-forced `storeFileToDB` path with bounded storage revalidation; it does not force the Vault file into the current database winner. The file handler retains a known branch when readable provenance identifies it, applies newer database state when the storage bytes match that recorded older revision, and saves a genuine edit on its recorded branch.
+
+A valid saved content hash can prove that unchanged bytes still represent a recorded revision whose database content has been pruned. A hash cannot reconstruct ancestry for edited bytes. If the recorded base is pruned and the current bytes do not match its saved hash, the handler may preserve readable storage as an independent branch when it matches no current live leaf; it must not attach those bytes to an arbitrary database winner. This unknown-origin case is distinct from an unavailable comparison: if required storage, provenance, database content, or revalidation cannot be read, the operation remains unresolved and the pair fails for retry. Repeated storage changes are bounded and also remain failed rather than being reported as reconciled.
 
 ## Result-state verification
 
@@ -156,12 +158,12 @@ Focused two-pass coverage starts with a `DB_APPLY` reflection whose file handler
 
 Full-scan coverage also verifies that the strict default returns `false`, an ordinary-start-up scan which explicitly continues returns `completed-with-file-failures` while logging the affected path at verbose level, and a later clean scan returns `true`.
 
-The equal-time regression uses real in-memory PouchDB and the file handler. It checks missing and recorded provenance with unchanged files and genuine local edits, then advances the database and reflects the incoming revision. Focused handler tests cover provenance read and write failures, unreadable current content, an existing conflict, and storage or database changes during verification.
+The equal-time regression uses real in-memory PouchDB and the file handler. It checks missing and recorded provenance with unchanged files and genuine local edits at both identical raw timestamps and distinct raw timestamps within one comparison bucket. It verifies that edits are preserved during the scan, then advances the database and checks that an incoming revision retains the local branch. It also verifies that a matching saved hash remains useful after its database revision is pruned, while edited bytes with an unhashed pruned base and no matching live leaf are preserved independently. Focused scanner tests verify that a failed ordinary save returns a failed pair. Focused handler tests cover provenance read and write failures, unavailable recorded-base content, an existing conflict, and storage or database changes during verification.
 
 A second two-pass case starts with a `db-only` entry skipped by the size limit. It then removes that limit and verifies that the entry is reflected to storage rather than misclassified as an offline local deletion. Coverage for an existing storage file verifies that a failed `sync-newer` reflection retains the observed storage mtime, and full-scan coverage verifies that the aggregate failure reaches its caller after scanner initialisation completes.
 
 Identity coverage verifies early quarantine when no consistent target exists, continued processing when consistent Metadata represents the same logical path, expired-deletion retention, special-namespace routing, actual-ID-first inspection, stale and ambiguous repair rejection, target-first ordering, exact-target retry, source preservation after failure, and last-seen clearing.
 
-Stored-event coverage verifies that current storage content replaces saved observations, a recreated path suppresses a stale deletion, distinct-ID rename halves are admitted independently from current path state, and a same-ID rename never performs a separate deletion. It also verifies that a storage-inspection failure does not become evidence for a destructive operation and that an individual replay failure does not prevent the full scan from running.
+Stored-event coverage verifies that current storage content replaces saved observations, a recreated path suppresses a stale deletion, distinct-ID rename halves are admitted independently from current path state, and a same-ID rename never performs a separate deletion. It also verifies that a storage-inspection failure does not become evidence for a destructive operation, that failed work remains pending, and that an individual replay failure does not prevent the full scan from running.
 
 Maintain that interaction boundary when changing file-handler results, last-seen persistence, Fast Setup reflection, or offline deletion detection.

package/docs/proven-in-use.md

@@ -1,13 +1,43 @@
-# Proven in maintained hosts
+# Maintained-host examples and evidence
 
 Commonlib is extracted from the implementation shared by [Self-hosted LiveSync](https://github.com/vrtmrz/obsidian-livesync) and its host applications. The package is therefore exercised by a substantial maintained consumer, but it does not yet claim a separate ecosystem of independent applications or a stable end-to-end SDK.
 
 The useful evidence is host- and contract-specific. Focused Commonlib tests establish reusable result semantics; Self-hosted LiveSync tests establish how those contracts compose into the Obsidian plug-in, CLI, WebApp, and WebPeer. The Obsidian plug-in and CLI retain the strongest device and long-running synchronisation evidence. The browser applications add focused adapter and runtime tests, browser smoke tests, a cross-application P2P scenario ending at the production CLI, and public Pages smoke validation.
 
-The code paths below identify the maintained Self-hosted LiveSync composition points used to establish this package boundary. The exact 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. The integration descriptions must still be reviewed when the maintained downstream changes.
+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.
 
 ## Obsidian plug-in
 
+The unreleased V3 Rabin–Karp correction uses proportional binary thresholds,
+including at values 0 and 1. Regression tests cover natural boundaries, suffix
+reuse, forced caps, explicit minima, EOF tails, and large UTF-8 text. The packed
+old/new CLI matrix verifies 810 file-stage digests over CouchDB, Journal, and
+P2P in both directions. Separate revision tests retain conflict coverage.
+The Linux Obsidian manual-setup workflow verifies value 0, eight 32 KiB binary
+pieces, unchanged Metadata revision and complete local Chunk inventory after
+restart, exact binary reception through Fast Fetch, and a bidirectional note
+round-trip. These checks use the unpublished local candidate with LiveSync
+1.0.39; they do not establish mobile or Cloudant-service behaviour.
+
+Unreleased Fast Fetch tests verify all current conflict leaves, including deleted
+leaves, before advancing the durable stream cursor. CouchDB 3.5.0 integration
+tests exercise revision ancestry retrieval and a fresh-import handoff to the
+ordinary PouchDB checkpoints, followed by a batch-size change and receipt of a
+new revision in LiveSync mode. Unit tests cover unimported local writes, missing
+or replaced checkpoint guards, partial publication, and exclusion of persisted
+resume cursors. A controlled connection delay also verifies that disposing the
+resource during preparation closes the connection when it arrives. Rebuilder
+tests also delay and reject device-local checkpoint
+writes, verifying that handoff, completion, and checkpoint removal wait for
+successful persistence. The handoff requires an empty local database, suspended local
+writers, and a remote database which is not replaced during the operation.
+These package-owned tests do not establish arbitrary-time fast-forwarding,
+On Demand repair, or real Obsidian runtime behaviour.
+
+The unreleased joined-device resource and UI-command work adds instance-owned typed UI handlers, legacy-compatible device projections, and device-record removal. Focused unit tests cover missing records, preservation of other devices and unknown fields, self-removal rejection, conflict retries, unsupported writes, verification failures, and handler disposal. CouchDB 3.5.0 integration tests verify that reading or forgetting never creates a missing database, and verify removal and preservation while retaining a fixture which demonstrates that local documents accept stale revisions. Object Storage integration tests against RustFS verify conditional removal and rejection of stale ETags. These checks do not make concurrent CouchDB updates atomic.
+
+Before integration with Commonlib 0.2.0, a local packed candidate based on 0.1.44 passed Self-hosted LiveSync 1.0.39 checks, unit tests, and production build. Its focused real-Obsidian 1.12.7 scenario on Linux verifies the settings entry, self-first and locked-out records, current metadata, manual refresh, confirmed removal, and preservation of other records and remote state. Mobile emulation verifies the command-palette entry, scrolling, viewport and safe-area bounds, and touch targets. Self-hosted LiveSync owns the dialogue and advisory version Notices. These results establish the tested build's behaviour; publication and native iOS and Android behaviour remain unverified.
+
 Unreleased remote-inspection tests compare individual and bulk reads against CouchDB 3.5.0. A fixture with 65 Metadata documents and 130 Chunks produces identical integrity reports while reducing HTTP requests from 198 to 8. Encrypted bulk reads preserve current conflicts, exact revision access, missing-document evidence, and unchanged database and Security Seed state. Unit tests cover bounded GET batches, encoded URL limits, per-document failures, cancellation, and explicitly excluded remote coverage. These counts describe the fixture; they do not establish large-Vault elapsed-time improvements.
 
 Unreleased [database diagnostics](database-diagnostics.md) tests cover preserved Usage accounting, normal-file identity classification, current conflict branches, byte comparisons, embedded Chunks, missing and unreadable content, cancellation, concurrent changes, and consistent pseudonyms. Real in-memory PouchDB tests verify pagination and conflict revision reads while retaining the original database handle. A CouchDB 3.5.0 integration test verifies GET-only access, encrypted Metadata and Chunk reads with an existing Security Seed, missing-seed failure without initialisation, and unchanged database update sequences and Seed documents. Focused tests also reject ciphertext which remains undecoded after an ID mismatch. Commonlib owns the result contract and compact Integrity Markdown formatter; Self-hosted LiveSync owns the serviceFeature, run-time name choice, dialogue lifecycle, and report copy and download controls. Its real Obsidian 1.12.7 test on Linux verifies cancellation before a run, both name modes, the nine-column Usage report, copy and download payloads, local integrity findings when CouchDB is unavailable, and unchanged settings, database update sequences, and Vault file names. Mobile emulation verifies the choice dialogue's viewport, safe-area, and touch-target layout; native iOS and Android behaviour remains unverified.
@@ -28,10 +58,14 @@ The CouchDB connection fix bypasses browser HTTP caching so encrypted replicatio
 
 Unreleased settings tests verify that Object Storage-only credentials, JWT values, and authentication headers reach the host persistence handler only after connection encryption, and that unavailable or failed required encryption preserves the previous persisted settings. The focused `/settings` entry also supplies conditional whole-profile Markdown preparation and import preservation. A clean packed consumer checks the exhaustive property policy and prepared output types with an ES2018 compile fixture. Commonlib owns these result and type contracts; Self-hosted LiveSync owns Markdown file writes, its settings interface, and restoration through a real Obsidian restart.
 
+The setting-service tests also cover the injected device-value boundary: exact local keys remain unchanged, the existing Vault and database-suffix configuration key layout is preserved, and separately injected stores remain isolated. These are Commonlib-owned asynchronous store contracts. Each host owns selecting its persistent adapter and verifying host storage across restart; this evidence does not claim additional real-runtime coverage.
+
 Unreleased colon-path regression tests establish that Commonlib preserves ordinary file paths through Metadata storage, Chunk retrieval, and storage reflection, with path obfuscation enabled or disabled. They use real PouchDB with injected storage. This result does not establish which filenames a host's file-creation API accepts; that boundary requires host runtime verification.
 
 Commonlib's encryption tests verify that an obfuscated Metadata document retains its document ID while its HKDF-encrypted path and file properties round-trip, that V1-obfuscated paths remain readable through the fallback, and that PouchDB replication presents a decoded path to both local storage and change events. The Fast Fetch test verifies decryption before storage and checkpointing. On 26th September 2026, a local packed candidate of this fix passed LiveSync 1.0.31's `npm run check` and unit tests, as well as real Obsidian two-Vault synchronisation, encrypted CLI-to-Obsidian transfer, and encrypted Metadata retrieval through Fast Fetch during manual CouchDB onboarding.
 
+The EntryManager selection tests distinguish Hidden File Sync documents by their original `i:` prefix. They check that the normal-file allow-list applies to ordinary paths while prefixed hidden documents remain eligible, that the normal-file ignore-list still excludes matching hidden documents, and that hidden-file disablement and the Customisation Sync exceptions retain their behaviour. Hidden File Sync owns its additional target and ignore patterns in Self-hosted LiveSync; storage reflection and native Obsidian behaviour remain downstream verification boundaries.
+
 The unreleased 0.1.30 packed candidate adds encryption of Hidden File Sync and Customisation Sync Metadata when CouchDB, E2EE V2, and Property Encryption are active. Focused Commonlib tests cover the `i:f:`, `ix:f:`, and legacy `ps:f:` representations, legacy and new setting defaults, feature declaration, concurrent version updates, and unknown-feature rejection. With that packed candidate in LiveSync, two real-Obsidian scenarios checked the raw CouchDB Metadata marker, zeroed times and size, empty public Chunk-reference list, and generation 13 feature declaration before restoring the files in a second Vault. The Hidden File Sync scenario also rebuilt the remote and verified the accepted writer's feature declaration and encrypted Metadata before the second Vault fetched them. The CLI-to-Obsidian encrypted note scenario also passed with matching effective settings. A separate real-Obsidian scenario kept continuous CouchDB replication active whilst the remote version document acquired an unknown feature; the local document was observed, the active Replicator retired, another replication was refused, and previously accepted Vault content remained intact. After restarting the Vault, both finite replication and the actual continuous connection attempt were refused by the remote declaration, without a KV feature history. These runs establish the tested local package and host build; they do not validate a published registry artefact or recovery under a future compatible client.
 
 Additional real-CouchDB integration tests exercise Fast Fetch admission before local reset, generation 12 acceptance, and generation 13 retrieval with plaintext and encrypted internal Metadata together. A real-Obsidian migration scenario enables the preference through the settings UI without Rebuild, verifies that unchanged Metadata retains its original revision while rewritten entries are encrypted with stable IDs, and checks a second device's mismatch rejection and restoration after alignment. After turning the preference OFF, Fast Fetch still retrieves both representations and their Chunks with matching content; the remote feature declaration remains. These checks use the local packed candidate with LiveSync 1.0.32.
@@ -182,6 +216,6 @@ A new integration should start with the focused entries, not by reproducing Self
 
 Use the named consumer paths as integration examples, while retaining the ownership and limitations stated in the [root README](../readme.md), [storage guide](platform-storage.md), [standard-I/O guide](platform-standard-io.md), and [remote configuration profile guide](remote-configurations.md).
 
-## Maintenance rule
+## Scope and maintenance
 
-This page records current evidence rather than historical adoption. When a host stops using an entry point, a verification path is retired, or a compatibility import moves to a focused contract, update the description and links instead of retaining a stronger claim than the maintained consumer establishes.
+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.

package/docs/releasing.md

@@ -2,16 +2,19 @@
 
 This document is the developer and maintainer runbook for preparing and publishing `@vrtmrz/livesync-commonlib`. Package-consumer guidance belongs in the root README.
 
-## Release gate
+## Commonlib-owned release checks
 
-Run the complete owner gate from a clean checkout:
+Run the normal owner checks from a clean checkout:
 
 ```bash
 npm ci
 npm run verify:package
+npm run test:integration:managed
 ```
 
-The gate type-checks Commonlib, runs its complete unit suite, verifies the source boundary, builds the distributable package, installs its exact tarball into a clean consumer, and bundles representative browser and Node entry points. The source `package.json` remains private to prevent publishing the repository root. Only the generated `.package` directory is publishable, and its manifest defaults to public publication on the `next` dist-tag.
+Together these checks type-check Commonlib, run its unit and integration suites, verify the source boundary, build the distributable package, install its exact tarball into a clean consumer, and bundle representative browser and Node entry points. These Commonlib-owned checks are the normal publication criteria. The source `package.json` remains private to prevent publishing the repository root. Only the generated `.package` directory is publishable, and its manifest defaults to public publication on the `next` dist-tag.
+
+Downstream or real-runtime checks are appropriate when a named host-specific risk is not established by the owner tests; run those checks against the exact packed artefact and record the risk and result. LiveSync adoption and downstream validation are not general publication prerequisites. The [maintained-host examples and evidence](proven-in-use.md) page is optional context, not a release or update gate.
 
 The package builder normalises generated directories to `0755`, ordinary files to `0644`, and declared `bin` targets to `0755` before validation. `test:package` uses a restrictive umask and verifies the packed modes, so local and hosted builds do not differ only because their caller environments use different umasks.
 
@@ -29,13 +32,17 @@ npm run verify:package
 
 Inspect the lockfile diff before committing it. A dependency-only maintenance change must not alter the source package version, and lockfile normalisation must not be described as a package upgrade when resolved versions and integrity values are unchanged. When the workflow selects a newer reviewed npm CLI, update this example in the same change.
 
-Before publication, run the downstream workflow against an exact Self-hosted LiveSync ref which already consumes the package. The workflow installs the tarball produced from the selected Commonlib commit, then runs LiveSync type checks, unit tests, plug-in and application builds, and CLI E2E. Real Obsidian E2E remains local-only and is required when the changed boundary affects actual plug-in composition, storage, UI, or platform behaviour.
+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.
+
+## 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.
 
 ## Preparing a release
 
-Choose the version explicitly. Prefer a `-next.N` prerelease, such as `0.1.32-next.0`, when registry installation must be validated before the stable version. Reserve `-rc.N` for an explicitly chosen release candidate. Package-proof versions are local artefacts and cannot be staged.
+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.
 
-Prepare both stable releases and pre-releases on a reviewed pull request based on `main`. A pre-release may be staged from the exact reviewed pull-request branch commit so that the registry artefact can be validated in Self-hosted LiveSync before the Commonlib change is merged. A stable release must be staged only after its exact reviewed release commit is present on `main`.
+Prepare stable releases and any optional prereleases on a reviewed pull request based on `main`. An optional prerelease may be staged from the exact reviewed pull-request branch commit. A stable release must be staged only after its exact reviewed release commit is present on `main`.
 
 ```bash
 npm ci
@@ -44,7 +51,7 @@ npm run verify:package
 npm publish --dry-run .package --tag next --access public
 ```
 
-Review `package.json`, `package-lock.json`, the generated manifest, the tarball contents, the test results, and the downstream evidence. Commit only the source manifest and lockfile for the version change; `.package`, `.package-consumer`, and `artifacts` are generated and ignored. Push and open a release pull request only after the usual user checkpoint. Keep a pre-release pull request in draft while its exact registry artefact is validated in Self-hosted LiveSync. Merge and stable publication remain separate later checkpoints.
+Review `package.json`, `package-lock.json`, the generated manifest, the tarball contents, and the Commonlib-owned test results. Add downstream evidence when a named host-specific risk requires it. Commit only the source manifest and lockfile for the version change; `.package`, `.package-consumer`, and `artifacts` are generated and ignored. Push and open a release pull request only after the usual user checkpoint. Keep a pull request in draft while a specifically planned downstream check is in progress; that check is not required when no such risk remains. Merge and publication remain separate later checkpoints.
 
 ## Historical initial npm bootstrap
 
@@ -58,9 +65,9 @@ npm run verify:package
 npm publish .package --tag next --access public
 ```
 
-Confirm the authenticated npm account, `@vrtmrz` scope ownership, package name, version, tarball checksum, packed contents, source commit, and target tag immediately before publication. Treat bootstrap publication as a separate user-authorised operation. npm may assign `latest` to the first published version even when `next` is requested; leave the immutable version in place and replace `latest` only after a stable release has passed consumer validation.
+Confirm the authenticated npm account, `@vrtmrz` scope ownership, package name, version, tarball checksum, packed contents, source commit, and target tag immediately before publication. Treat bootstrap publication as a separate user-authorised operation. npm may assign `latest` to the first published version even when `next` is requested; leave the immutable version in place and replace `latest` only after a stable release has passed the Commonlib owner checks and any applicable targeted host checks.
 
-Bootstrap publication was the one historical exception which used direct `npm publish`. Do not repeat that operation for routine releases. Current pre-releases use protected staged publishing and may select an exact reviewed branch commit; stable releases use an exact `main` commit. If validation fails, leave the published version immutable and prepare a new pre-release version.
+Bootstrap publication was the one historical exception which used direct `npm publish`. Do not repeat that operation for routine releases. Optional prereleases use protected staged publishing and may select an exact reviewed branch commit; stable releases use an exact `main` commit. If the owner checks or an applicable targeted host check fails, leave the published version immutable and prepare a new version.
 
 ## Trusted staged publishing
 
@@ -73,9 +80,9 @@ After bootstrap, configure the npm Trusted Publisher for:
 
 Protect the GitHub `npm` environment with a required reviewer and permit only `main`. The trusted workflow definition always runs from `main`. A pre-release may package an exact commit from a reviewed draft branch, while a stable release also requires the package source and workflow-triggering commit to be the exact current `main` commit. The workflow confirms that the selected source branch still points to the requested full commit SHA, checks out that SHA, runs `verify:package`, validates the requested version and confirmation text, packs the reviewed output, records its checksum, and passes the same tarball to the protected staging job.
 
-npm's automatic provenance identifies the `main` commit which triggered the trusted workflow. For a pre-release selected from a draft branch, this identifies the trusted workflow source rather than the packaged source commit. Record and verify the separate `source_ref`, exact package SHA, and tarball checksum before approving the staged version. This provenance distinction is accepted for an immutable pre-release used to validate the consumer before merge. A stable release requires the workflow and package source to be the same exact `main` commit.
+npm's automatic provenance identifies the `main` commit which triggered the trusted workflow. For an optional prerelease selected from a draft branch, this identifies the trusted workflow source rather than the packaged source commit. Record and verify the separate `source_ref`, exact package SHA, and tarball checksum before approving the staged version. This provenance distinction is accepted for an immutable prerelease when a consumer check is planned before merge. A stable release requires the workflow and package source to be the same exact `main` commit.
 
-Dispatch a pre-release from its exact reviewed draft branch commit:
+When using an optional pre-release, dispatch it from its exact reviewed draft branch commit:
 
 ```bash
 source_ref=separate-setting-lifecycle
@@ -91,11 +98,11 @@ gh workflow run publish-npm.yml \
 
 For a stable release, use `source_ref=main`. The workflow rejects a stable release selected from another branch, rejects a stable release without its trusted workflow commit, and requires the workflow-triggering SHA to equal the packaged `main` SHA. The workflow dispatch itself uses `--ref main` for every release, so an unmerged branch cannot change the trusted publication job or acquire access to the `npm` environment.
 
-The workflow always stages to `next`. Inspect the staged package name, version, access, dist-tag, provenance, checksum, files, selected source branch, and source commit before approving it through npm. Approval and later promotion to `latest` are separate user-authorised operations. Keep the Commonlib and Self-hosted LiveSync consumer pull requests in draft while validating the exact registry pre-release. If validation fails, leave that published version immutable and prepare a new pre-release. After successful consumer validation, merge Commonlib only through its separate maintainer gate. Validate a stable release in Self-hosted LiveSync before promoting it to `latest`.
+The workflow always stages to `next`. Inspect the staged package name, version, access, dist-tag, provenance, checksum, files, selected source branch, and source commit before approving publication to npm. After approval publishes the version, fetch that exact registry version and compare its SHA-256, package name and version, and provenance with the reviewed staged artefact and source revision; confirm that `next` points to that version. Install the fetched registry artefact in a clean consumer and run the relevant package checks before requesting promotion. Stage approval and later promotion to `latest` are separate user-authorised operations. Promote the same version only after those registry checks pass and any applicable targeted host checks are complete. If a check fails, leave the published version immutable and prepare a new version. Keep consumer pull requests in draft only while a specifically planned host check is in progress; consumer adoption is not a precondition for Commonlib merge or release.
 
 ## Publishing a GitHub Release
 
-Create a GitHub Release for each stable Commonlib release after the exact registry artefact has passed downstream validation and the version has been promoted to `latest`. Target the exact `main` commit used to build the published package.
+Create a GitHub Release for each stable Commonlib release after the exact registry artefact has passed the Commonlib owner checks and the version has been promoted to `latest`. Complete any applicable targeted host checks before release. Target the exact `main` commit used to build the published package.
 
 Protect the GitHub `github-release` environment with a required reviewer and permit only `main`. The manually dispatched workflow first verifies the release with read-only repository access. Only its protected publication job receives `contents: write` access.
 

package/docs/settings-lifecycle.md

@@ -18,7 +18,7 @@ import { createNewVaultSettings } from "@vrtmrz/livesync-commonlib/settings";
 const initialSettings = createNewVaultSettings();
 ```
 
-The recommended base currently selects a 50 MB maximum synchronised file size, Rabin–Karp chunk splitting, Plug-in Sync V2, case-insensitive file-name handling, and E2EE V2. Chunk revisions are always derived from their content; the obsolete `doNotUseFixedRevisionForChunks` stored key is retained only for compatibility and is not a recommendation or tweak. The recommended base does not enable synchronisation or encryption on behalf of the user.
+The recommended base currently selects a 50 MB maximum synchronised file size, a `customChunkSize` value of 0, Rabin–Karp chunk splitting, Plug-in Sync V2, case-insensitive file-name handling, and E2EE V2. Chunk revisions are always derived from their content; the obsolete `doNotUseFixedRevisionForChunks` stored key is retained only for compatibility and is not a recommendation or tweak. The recommended base does not enable synchronisation or encryption on behalf of the user.
 
 Compared with the conservative stored-setting fallbacks, the current new-Vault object has exactly two semantic differences:
 
@@ -27,15 +27,23 @@ Compared with the conservative stored-setting fallbacks, the current new-Vault o
 | `usePluginSyncV2` | `false` | `true` |
 | `handleFilenameCaseSensitive` | normalised from the legacy absent value to `false` | `false` |
 
-The other headline recommendations are already the conservative fallbacks: `syncMaxSizeInMB` is 50, `chunkSplitterVersion` is `v3-rabin-karp`, and `E2EEAlgorithm` is `v2`. Data Compression, Eden, V1 dynamic iteration, the legacy IndexedDB adapter, Hidden File Sync, and automatic synchronisation remain disabled when their stored values are absent. Explicit stored values take precedence.
+The other headline recommendations are already the conservative fallbacks: `syncMaxSizeInMB` is 50, `customChunkSize` is 0, `chunkSplitterVersion` is `v3-rabin-karp`, and `E2EEAlgorithm` is `v2`. Data Compression, Eden, V1 dynamic iteration, the legacy IndexedDB adapter, Hidden File Sync, and automatic synchronisation remain disabled when their stored values are absent. Explicit stored values take precedence.
 
-Apply a remote-specific preferred object only while configuring that remote. Do not merge it into an existing stored configuration merely because the remote type can be inferred. The self-hosted CouchDB profile uses a chunk-size coefficient of 60, matching the Doctor check for Rabin–Karp databases; Cloudant retains its service-specific value of 0.
+Apply a remote-specific preferred object only while configuring that remote. Do not merge it into an existing stored configuration merely because the remote type can be inferred. Cloudant, self-hosted CouchDB, and Journal Sync setup all use the common `customChunkSize` value of 0. Their unrelated request and bulk settings remain service-specific. The current Doctor regulation no longer recommends changing the value to 60 universally, and existing explicit values remain valid.
+
+The new Doctor rule set inherits 1.0.33 and withdraws the Chunk-size rule with
+`customChunkSize: undefined`. Historical regulations keep their original rules.
+This removes the recommendation, rather than deleting a stored setting or
+forcing it to 0. Its consultation version deliberately remains 1.0.33: removing
+a recommendation does not require users to review unchanged recommendations
+again. Existing dismissals remain effective; an explicit forced rescan still
+checks the remaining rules.
 
 | Explicitly selected remote | `customChunkSize` | `concurrencyOfReadChunksOnline` | `minimumIntervalOfReadChunksOnline` |
 | --- | ---: | ---: | ---: |
 | Cloudant | 0 | 100 | 333 |
-| Self-hosted CouchDB | 60 | 30 | 25 |
-| Object Storage | 10 | 30 | 25 |
+| Self-hosted CouchDB | 0 | 30 | 25 |
+| Journal Sync (Object Storage) | 0 | 30 | 25 |
 
 These are setup-time recommendations, not upgrade migrations. Selecting or detecting a remote does not apply them to an existing configuration unless the person is actively configuring that remote.
 
@@ -60,6 +68,8 @@ if (prepared.requiresSyncReview) {
 
 Explicit stored values take precedence over every fallback. A migration therefore preserves synchronisation switches and other user choices unless a migration step documents a deliberate transformation.
 
+`batchSaveInLiveSync` is a separate explicit choice for bounded local database batching in LiveSync mode. Both new and existing settings default to `false`; the legacy pair `liveSync: true, batchSave: true` does not enable it. The public setting property is optional for existing host settings shapes, and a missing value remains disabled. Other modes continue to use `batchSave`. Markdown settings and QR data preserve the explicit choice, while older imports without the property do not infer it from `batchSave`. Hosts should preserve both choices during ordinary mode changes and use the shared minimum and maximum delays.
+
 The sleep preferences are included in Setup URI encoding. When an older Setup URI or stored setting does not contain either key, `allowSleepDuringSynchronisation` defaults to `false`, while `allowSleepDuringSynchronisationOnDesktop` defaults to `true`. The maintained Obsidian host therefore retains best-effort screen-awake protection on mobile but allows normal automatic sleep on desktop unless the user selects otherwise.
 
 An existing settings store without an explicit `handleFilenameCaseSensitive` value is normalised to `false` and saved. This preserves the effective behaviour of earlier releases, where an absent value followed the case-insensitive branch. An explicit `true` or `false` value is preserved. New Vaults also select case-insensitive handling (`false`).
@@ -72,6 +82,30 @@ Two other values deliberately remain unset until their owning lifecycle supplies
 
 The standard Commonlib `SettingService` performs this preparation automatically. Hosts which use that service can inspect `getSettingsMigrationState()` after `loadSettings()` instead of calling the function themselves.
 
+## Host storage for device values and configuration
+
+The host selects an asynchronous `ValueStore & ValueDeleter` for each application instance and injects it into the setting service as `deviceValues`. Commonlib does not discover `globalThis.localStorage`, create module-global storage, or fall back to another store. `setting.deviceValues` exposes the injected exact-key root. `setting.config` is an asynchronous view over the same root, scoped to the current Vault name and `additionalSuffixOfDatabaseName`; the Service Hub `config` property refers to that same view.
+
+For an existing Web Storage layout, pass the selected storage object explicitly and use an empty adapter prefix so the service can address existing raw keys:
+
+```ts
+import { createWebStorageValueStore } from "@vrtmrz/value-store/web-storage";
+
+const deviceValues = createWebStorageValueStore(window.localStorage, { prefix: "" });
+// Supply deviceValues as the setting service's required composition dependency.
+```
+
+Use `deviceValues` for exact device-local keys, including existing keys such as `ls-setting-passphrase`. Use `config` for logical configuration keys; the service retains the established Vault and database-suffix key format. For example, the `checkpoint` key for Vault `notes` remains `notes--checkpoint` with an empty suffix and `notes-team-checkpoint` with suffix `team`. Keep the existing key names and await every read, write, and deletion:
+
+```ts
+const passphrase = await setting.deviceValues.getValue("ls-setting-passphrase");
+const checkpoint = await setting.config.getValue("checkpoint");
+await setting.config.setValue("checkpoint", "revision-42");
+await setting.config.delete("checkpoint");
+```
+
+`getValue` returns `null` when a key is absent. Use `getObject` and `setObject` for values stored as JSON; Commonlib does not automatically reinterpret old strings or migrate entries between the exact-key root and the scoped view.
+
 ## Preparing settings for persistence and Markdown
 
 The existing `SettingService` provides `changeConfigurationEncryption(store, passphrase?)` for hosts which edit the configuration encryption mode or device-local custom key. Await it before marking those edits as saved. It prepares one wrapper key for connection credentials, the E2EE passphrase, remote profile URIs, and the independent ID key, and serialises the change with ordinary settings saves. It rejects empty keys and unreadable existing protected items. A failed write attempts to restore the previous device key and does not send a success event. The device key and settings document use separate host writes, so this is not a guarantee of rollback after process termination or an uncertain persistence error.

package/docs/storage-events-and-reflection.md

@@ -1,16 +1,18 @@
 ---
-date: 2026-09-05
-commonlib-version: "0.1.23"
-self-hosted-livesync-version: "1.0.25"
+date: 2026-10-25
+commonlib-version: "0.2.0"
+self-hosted-livesync-version: "1.0.40"
+status: unreleased
 ---
 
 # Storage events and database-to-storage reflection
 
 This note separates storage-to-database event handling from
-database-to-storage reflection. It describes the Commonlib 0.1.23 guard against
-a stale `DELETE` notification logically deleting Metadata while the same file
-is still present in storage. The version fields identify the reviewed source
-versions.
+database-to-storage reflection. It documents the current guard against a stale
+`DELETE` notification logically deleting Metadata while the same file is still
+present in storage, and the accepted local completion contract for queued file
+operations. The version fields identify the reviewed source versions; these
+changes remain unreleased.
 
 ## Processing directions
 
@@ -46,6 +48,101 @@ and unsynchronised storage content retain their existing reflection rules.
 The watcher guard does not intercept this path or general explicit database
 deletion operations.
 
+## Pending operations and local completion
+
+Once admitted, a file operation remains pending while buffered, waiting for its
+batch boundary, or running in a handler. The manager includes all three states
+in its existing event snapshot. It saves snapshots in order, so an older write
+cannot replace a newer view of pending work. The manager acknowledges an
+ordinary file operation only after its effect is durable locally, current state proves the
+effect is already represented or safely covered by a successful successor, or
+the handler returns a skip explicitly allowed by policy. A handler
+failure or exception leaves the saved operation pending. A failed initial
+snapshot prevents the handler from starting; a later snapshot failure is
+reported and cannot be treated as completion. Completion of an older operation
+cannot remove a newer operation for the same path.
+
+The event snapshot records operation intent, not authoritative current file
+content. Admission does not read a file body merely to wait. When a `CREATE` or
+`CHANGED` operation becomes eligible, the handler rechecks the current path and
+obtains its current content for processing. Restored events are revalidated
+against current storage and selection before they can affect the database. The
+saved stub and any optional cache are not used as a historical file version.
+The current-storage deletion checks and rename-exclusion rules below continue to
+apply.
+
+A restored deletion whose database entry is already absent or deleted completes
+without another revision. A restored rename whose source deletion is already
+represented reconciles the current target through the ordinary non-forced
+handler. The same applies to a case-only rename when Metadata already records
+the target spelling. Replaying either completed operation preserves later local
+edits. If the source is still live and a target already exists, the existing
+collision refusal remains in force: the snapshot does not prove that this
+rename created that target, so the unresolved operation remains pending.
+
+`commitPendingFileEvents()` requests immediate processing of the finite set of
+operations accepted before the call, including work which is buffered,
+waiting, or already in a handler. It waits for each actual handler result and
+for the ordered snapshot update which records that result; releasing a timer is
+not completion. Later events do not extend that captured boundary. A newer
+coalesced operation satisfies an earlier one only when its successful result
+covers the earlier intent. A failed handler or snapshot update is reported to
+the caller and leaves unresolved work in the snapshot. This boundary covers
+local completion under the selected handler contract only; it does not prove replication or receipt by another
+Vault.
+
+A `DELETE` or `RENAME` ordering sentinel waits for its predecessors only. It
+must not wait for itself or events which follow it in the dispatch queue. Batch
+timers make work eligible to run; they do not perform it. The quiet period
+follows the latest eligible content update, while the maximum intentional delay
+is measured from the first uncommitted update, starting when the queue call is
+accepted and before asynchronous filtering or the touched-file check. Waiting
+timers do not occupy a processing slot, and time spent waiting for a slot does
+not restart the maximum delay. Once due, the operation acquires a slot and reads
+current content for processing.
+
+## Optional file handlers
+
+`INTERNAL` events and files marked `isInternal` use their owning feature's
+contract. Hosts can register `processOptionalFileEventWithResult` handlers with
+`firstHandled`. `HandlerOutcome<TValue = void, TVetoReason = void>` carries a
+success value and a veto reason independently; a non-void payload is required
+in its branch. Dispatch follows priority and registration order:
+
+| Outcome | Dispatch and completion |
+| --- | --- |
+| `not-applicable` | Try the next provider. If none applies, complete the policy-approved skip. |
+| `completed` | Stop and complete the event after the provider's actual save or verified no-op. |
+| `veto` | Stop and retain the event with a reported refusal reason. |
+| Exception or rejection | Propagate the original error and retain the event. |
+
+A completed result stops dispatch immediately; a later provider cannot veto
+it. Empty registration returns `not-applicable`. False or zero payloads remain
+valid values. Providers must resolve their promise only after the operation
+finishes. Snapshot acknowledgement still follows the handler result, and a
+snapshot failure keeps the event recoverable.
+
+The optional `whenFlushRequested` promise resolves when a finite completion
+boundary includes this event. A provider which debounces saves uses it to
+release that event's captured delay. It must wait for the corresponding save,
+settle all notifications coalesced into that save, and keep later groups outside
+the captured boundary. This signal is runtime state; it does not change the
+persisted snapshot format.
+
+Migrate all optional providers in a host together. Once the first typed provider
+is registered, the manager uses the typed chain exclusively, even when every
+provider returns `not-applicable`. A host without a registered typed provider
+retains `processOptionalFileEvent` as a legacy notification contract. Its
+boolean does not confirm persistence: a resolved notification completes only
+that dispatch, while a rejection which reaches the manager is still retained.
+The existing boolean aggregators and ordinary file contract are unchanged.
+
+During start-up replay and settings or unload flushes, providers use actual
+database readiness and initialise their required local state before saving.
+They must not wait for an application-ready or resume event which occurs only
+after that same flush. An unavailable prerequisite returns a veto; the manager
+does not introduce an automatic retry loop for a failed operation.
+
 ## Event intent and current storage state
 
 | Event intent | Current storage observation | Admitted operation |
@@ -92,9 +189,11 @@ incoming logical deletion can still remove unchanged storage content.
 
 These tests do not establish the native watcher event sequence reported in
 Issue 1168. Real-runtime verification belongs to the host and must distinguish
-observed events from inferred causes. This change does not promise path-case
-convergence or full folder-rename support. It does not rewrite the queue,
-introduce a retry subsystem, or change the database schema.
+observed events from inferred causes. The watcher guard does not promise
+path-case convergence or full folder-rename support. Focused manager tests cover
+finite completion boundaries, ordered snapshots, retained failures, replay, and
+batch timing. This work adds no second journal, unbounded retry loop, or
+database-schema change.
 
 The maintained host's real-runtime comparison is recorded in
 [Proven in maintained hosts](proven-in-use.md#obsidian-plug-in), separately