@vrtmrz/livesync-commonlib 0.2.0 → 0.2.2

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-26
+commonlib-version: "0.2.1"
+self-hosted-livesync-version: "1.0.40"
 status: unreleased
 ---
 
@@ -29,17 +29,25 @@ The tables below cover only paths which remain after identity validation, the ho
 6. after the first permitted invocation reaches its aggregate-result boundary, record `initialized = true`; and
 7. return the aggregate pair result under the caller's selected handling of file failures.
 
+### Startup content checking
+
+`VaultScanOptions.strictContentCheck` is optional. `initialiseDatabase` accepts `VaultScanOptions` as its optional fifth argument, and `scanVault` accepts it as its optional fourth argument and forwards it. `performFullScan` exposes the same option through `FullScanOptions`. Omitting the option, or setting it to `true`, retains strict content comparison. Only an explicit `false` permits the scanner to pass the `canSkipUnchangedFile` hint to the file handler. Commonlib does not read a host setting or global storage; a host may select this option from a per-installation startup preference.
+
+The hint is considered only when the normal freshness comparison reaches `EVEN`, replacing the additional body comparison at that point. It never bypasses `BASE_IS_NEW` or `TARGET_IS_NEW`; those branches retain their timestamp-directed reflection and last-seen bookkeeping. Inside `EVEN`, the hint is allowed only for a tracked file whose raw modification time exactly equals the recorded provenance mtime (not merely a value in the same platform comparison bucket), whose byte size matches the recorded value, whose tracked revision is the current live database revision, and which has no live conflicts or related queued, running, or failed file work. If tracking evidence is missing, or the host cannot establish pending-work state, the existing strict byte-comparison path remains. When the hint is accepted, the pair result is `SKIPPED`; it does not compare or claim equal bytes, write provenance, or introduce Commonlib persistent state. Incoming content, conflict handling, and logical-deletion protection retain their existing rules.
+
+A local edit which preserves the tracked modification time and byte size may be missed by a scan using explicit `false`. Existing same-stat edit checks exercise the omitted-option strict path.
+
 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 +66,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 +146,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
+
+For a `both` pair which selects `NEWER_WINS` (`sync-newer`), the normal freshness comparison can reach `EVEN` for equal raw modification times or distinct times within the platform tolerance; those timestamps alone do not establish that the storage file is unchanged. Under the omitted-option strict path, the scanner 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. With explicit `strictContentCheck: false`, the scanner may request `canSkipUnchangedFile` only in the `EVEN` branch, and only when the raw mtime exactly matches the recorded provenance mtime; a value merely in the same tolerance bucket does not qualify. The `BASE_IS_NEW` and `TARGET_IS_NEW` branches retain their existing timestamp-directed reflection and last-seen bookkeeping. The existing selection, file-size, and conflict policies still apply, and the `DB_APPLY` action remains unchanged.
 
-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.
+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.
 
-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.
+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 +166,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 with `strictContentCheck` omitted, keeping its same-stat edit assertions on the strict default path. 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-26
+commonlib-version: "0.2.1"
+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,105 @@ and unsynchronised storage content retain their existing reflection rules.
 The watcher guard does not intercept this path or general explicit database
 deletion operations.
 
+## Startup scans and pending operations
+
+The full scanner's optional `strictContentCheck: false` path is gated by the host's file-operation state. Any related queued, running, or failed operation blocks the `canSkipUnchangedFile` hint. The host must provide an available query before the scanner can establish that no related work exists; without that query or other required evidence, strict content comparison remains active. The hint is considered only after normal freshness comparison reaches `EVEN`, and requires the raw mtime to exactly match the recorded provenance value; a match within the platform comparison bucket is insufficient. `BASE_IS_NEW` and `TARGET_IS_NEW` retain their timestamp-directed reflection and last-seen bookkeeping. A pair returned as `SKIPPED` by this hint does not acknowledge or remove a saved event. Event work continues to follow the snapshot and handler-completion contract below. This option affects only the full-scan same-stat check; ordinary watcher `CREATE` and `CHANGED` handling, replicated writes, and logical-deletion protection retain their existing rules. See [Full offline scan](offline-scanner.md#startup-content-checking) for the full option and eligibility conditions.
+
+## 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 +193,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.2",
   "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",