@vrtmrz/livesync-commonlib 0.2.0 → 0.2.1

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/settings-lifecycle.md

@@ -68,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`).

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -1010,7 +1010,7 @@
     "events": "^3.3.0",
     "fflate": "^0.8.2",
     "idb": "^8.0.3",
-    "markdown-it": "^14.3.2",
+    "markdown-it": "^14.3.3",
     "minimatch": "^10.2.6",
     "octagonal-wheels": "^0.1.55",
     "pouchdb-adapter-http": "^9.0.0",