@vrtmrz/livesync-commonlib 0.1.22 → 0.1.23

package/dist/common/models/fileaccess.type.d.ts

@@ -53,6 +53,8 @@ export type FileEventArgs = {
     file: UXFileInfoStub | UXInternalFileInfoStub;
     cache?: CacheData;
     oldPath?: string;
+    /** The destination of a rename converted to DELETE after target filtering. */
+    renameTarget?: string;
     ctx?: unknown;
 };
 export type FileEventItem = {

package/dist/managers/StorageEventManager.js

@@ -166,6 +166,7 @@ class StorageEventManagerBase extends StorageEventManager {
         args: {
           file,
           oldPath: type === "RENAME" ? oldPath : void 0,
+          ...param.type === "RENAME" && type === "DELETE" ? { renameTarget: param.file.path } : {},
           cache,
           ctx
         },

package/dist/serviceFeatures/targetFilter.d.ts

@@ -1,6 +1,7 @@
 import { type UXFileInfoStub } from "../common/types.js";
 import { type LogFunction } from "../services/lib/logUtils.js";
 import type { NecessaryServices } from "../interfaces/ServiceModule.js";
+import type { IVaultService } from "../services/base/IService.js";
 /**
  * This is a simple handler that accepts all files.
  */
@@ -8,7 +9,7 @@ export declare function isAcceptedAlwaysFactory(host: NecessaryServices<never, n
 /**
  * Check if a file is accepted based on filename duplication in the vault.
  */
-export declare function isAcceptedInFilenameDuplicationFactory(host: NecessaryServices<"vault" | "fileProcessing", "storageAccess">, log: LogFunction): (file: string | UXFileInfoStub) => Promise<boolean>;
+export declare function isAcceptedInFilenameDuplicationFactory(host: NecessaryServices<"vault" | "fileProcessing", "storageAccess">, log: LogFunction): (file: string | UXFileInfoStub, options?: Parameters<IVaultService["isTargetFile"]>[1]) => Promise<boolean>;
 /**
  * Check if a file is accepted by the local database (e.g., not rejected by the local DB's target file check).
  * Local database responsible for non-internal files, syncOnlyRegEx, syncIgnoreRegEx

package/dist/serviceFeatures/targetFilter.js

@@ -35,7 +35,8 @@ function isAcceptedInFilenameDuplicationFactory(host, log) {
       return true;
     }
   });
-  return async function isAcceptedInFilenameDuplication(file) {
+  return async function isAcceptedInFilenameDuplication(file, options) {
+    if (options?.skipCaseCollisionCheck) return true;
     const fileCountMap = (await fileCountMapComputed.update(host.services.fileProcessing.totalStorageFileEventCount)).value;
     const filepath = getStoragePathFromUXFileInfo(file);
     const lc = filepath.toLowerCase();

package/dist/serviceModules/ServiceFileHandlerBase.d.ts

@@ -68,6 +68,7 @@ export declare abstract class ServiceFileHandlerBase extends ServiceModuleBase<S
     private applyDatabaseEntryToStorage;
     private preserveUnsyncedStorageAsConflict;
     private _anyHandlerProcessesFileEvent;
+    private canRecordStorageDeletion;
     private serializedByFileEventPaths;
     /**
      * Revalidate a persisted storage operation against the current storage state.

package/dist/serviceModules/ServiceFileHandlerBase.js

@@ -657,13 +657,15 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       this._log(`Rename event for ${path} has no source path`, LOG_LEVEL_VERBOSE);
       return false;
     }
-    const eventPaths = type === "RENAME" ? [path, eventItem.oldPath] : [path];
+    const relatedPath = type === "RENAME" ? eventItem.oldPath : type === "DELETE" ? eventItem.renameTarget : void 0;
+    const eventPaths = relatedPath === void 0 ? [path] : [path, relatedPath];
     return await this.serializedByFileEventPaths(eventPaths, async () => {
       switch (type) {
         case "CREATE":
         case "CHANGED":
           return await this.storeFileToDB(item.args.file);
         case "DELETE":
+          if (!await this.canRecordStorageDeletion(item)) return true;
           return await this.deleteFileFromDB(item.args.file);
         case "RENAME":
           return await this.renameFileInDB(
@@ -678,6 +680,45 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       }
     });
   }
+  async canRecordStorageDeletion(item) {
+    const path = item.args.file.path;
+    try {
+      const current = await this.storage.getStub(path);
+      let excludedRenameTarget = null;
+      if (item.args.renameTarget !== void 0) {
+        const targetPath = item.args.renameTarget;
+        const targetItem = await this.storage.getStub(targetPath);
+        const target = this.getExactCurrentFile(targetItem, targetPath);
+        if (targetItem !== null && !target) {
+          this._log(`Preserved ${path}: the rename target no longer resolves to ${targetPath}`, LOG_LEVEL_NOTICE);
+          return false;
+        }
+        const targetIsSelected = !shouldBeIgnored(targetPath) && await this.vault.isTargetFile(targetPath, { skipCaseCollisionCheck: true }) && !(target && this.vault.isFileSizeTooLarge(target.stat.size));
+        if (targetIsSelected) {
+          this._log(`Preserved ${path}: rename target ${targetPath} is still selected`, LOG_LEVEL_NOTICE);
+          return false;
+        }
+        excludedRenameTarget = target;
+      }
+      if (current === null) return true;
+      if (!isFolderInfo(current)) {
+        const [currentId, deletedId] = await Promise.all([
+          this.path.path2id(current.path),
+          this.path.path2id(path)
+        ]);
+        if (currentId !== deletedId) return true;
+        if (excludedRenameTarget && this.storage.normalisePath(current.path) !== this.storage.normalisePath(path) && this.storage.normalisePath(current.path) === this.storage.normalisePath(excludedRenameTarget.path)) {
+          return true;
+        }
+      }
+      this._log(`Preserved ${path}: a current storage item contradicts its deletion event`, LOG_LEVEL_NOTICE);
+      return false;
+    } catch (ex) {
+      this._log(`Could not validate deletion of ${path}; preserved the database entry`, LOG_LEVEL_NOTICE);
+      this._log(ex, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+  }
   async serializedByFileEventPaths(eventPaths, callback) {
     const documentIds = await Promise.all(eventPaths.map((eventPath) => this.path.path2id(eventPath)));
     const lockKeys = [...new Set(documentIds)].sort().map((documentId) => `processFileEvent-${documentId}`);
@@ -702,7 +743,8 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       this._log(`Rename event for ${path} has no source path`, LOG_LEVEL_VERBOSE);
       return true;
     }
-    const eventPaths = type === "RENAME" ? [path, eventItem.oldPath] : [path];
+    const relatedPath = type === "RENAME" ? eventItem.oldPath : type === "DELETE" ? eventItem.renameTarget : void 0;
+    const eventPaths = relatedPath === void 0 ? [path] : [path, relatedPath];
     return await this.serializedByFileEventPaths(eventPaths, async (isSameDocument) => {
       let action;
       try {
@@ -732,6 +774,9 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
         return current && await this.isCurrentFileSelected(current) ? { kind: "store", file: current } : { kind: "none" };
       }
       case "DELETE": {
+        if (item.args.renameTarget !== void 0) {
+          return await this.canRecordStorageDeletion(item) && await this.canApplyRestoredDeletion(path) ? { kind: "delete", path } : { kind: "none" };
+        }
         const current = await this.storage.getStub(path);
         return current === null && await this.canApplyRestoredDeletion(path) ? { kind: "delete", path } : { kind: "none" };
       }

package/dist/services/base/IService.d.ts

@@ -351,7 +351,11 @@ export interface IVaultService {
     getVaultName(): string;
     scanVault(showingNotice?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean): Promise<VaultScanResult>;
     isIgnoredByIgnoreFile(file: string | UXFileInfoStub): Promise<boolean>;
-    isTargetFile(file: string | UXFileInfoStub): Promise<boolean>;
+    isTargetFile(file: string | UXFileInfoStub, 
+    /** Inspect selection policy without treating a filename collision as an exclusion. */
+    options?: {
+        skipCaseCollisionCheck?: boolean;
+    }): Promise<boolean>;
     isTargetFileInExtra(file: string | UXFileInfoStub): Promise<boolean>;
     isFileSizeTooLarge(size: number): boolean;
     getActiveFilePath(): FilePath | undefined;

package/dist/services/base/VaultService.d.ts

@@ -35,9 +35,11 @@ export declare abstract class VaultService<T extends ServiceContext = ServiceCon
     /**
      * Check if a file is a target file for synchronisation.
      * @param file The file path or file info stub to check.
-     * @param keepFileCheckList Whether to keep the file in the check list.
+     * @param options Optional selection inspection without filename collision rejection.
      */
-    readonly isTargetFile: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(file: string | import("../../common/types.js").UXFileInfoStub) => Promise<boolean>>;
+    readonly isTargetFile: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(file: string | import("../../common/types.js").UXFileInfoStub, options?: {
+        skipCaseCollisionCheck?: boolean;
+    }) => Promise<boolean>>;
     /**
      * Check if a file is a target file for some extra feature
      */

package/dist/services/base/VaultService.js

@@ -37,7 +37,7 @@ class VaultService extends ServiceBase {
   /**
    * Check if a file is a target file for synchronisation.
    * @param file The file path or file info stub to check.
-   * @param keepFileCheckList Whether to keep the file in the check list.
+   * @param options Optional selection inspection without filename collision rejection.
    */
   isTargetFile = handlers().bailFirstFailure("isTargetFile");
   /**

package/docs/development.md

@@ -83,6 +83,8 @@ The multiple-remote profile contract has focused unit coverage in `src/serviceFe
 
 The full offline scanner applies both the host's target-file policy and Commonlib's built-in `shouldBeIgnored` policy before constructing storage/database pairs. This keeps legacy LiveSync log files and flag files outside ordinary create, restore, and delete decisions even when a host accepts their file extension. Lower-level write guards remain a defence for direct calls; they are not the normal full-scan filter. The complete pair-state decision matrix and database-to-storage reflection result contract are documented in [Full offline scan](offline-scanner.md). Extend that document, the Cartesian action test, and both collection-side tests whenever the policy changes.
 
+The unreleased watcher deletion checks and the separate database-to-storage reflection path are recorded in [Storage events and database-to-storage reflection](storage-events-and-reflection.md).
+
 The revision-tree safety rules are documented in [Conflict resolution and file provenance](conflict-resolution.md). `ConflictManager.unit.spec.ts` owns common-ancestor and conservative merge behaviour, deterministic pair selection for multiple live leaves, and reconstruction from the committed tree between stages. `EntryManagerImpls.unit.spec.ts` owns the distinction between force-writing below an exact revision and conditionally advancing a current live leaf through PouchDB's ordinary revision check. `ServiceDatabaseFileAccessBase.unit.spec.ts` owns all-branch content discovery, short-circuiting history existence checks after an exact match, exact-revision logical deletion, and the public live-base result and event boundary. `ServiceFileHandlerBase.unit.spec.ts` owns the injected provenance policy for edit, deletion, and rename operations, together with user-selected reflection, child creation, strict matching, matching-provenance cleanup after exact branch deletion, and stale-revision refusal. `LiveSyncLocalDB.unit.spec.ts` owns chunk reachability across current winners, shared chunks, live conflicts, available merge ancestry, conflict resolution, and PouchDB replication of collection and recreation. Extend the relevant sides when changing conflict resolution, compaction handling, provenance, chunk collection, or database-to-storage overwrite protection.
 
 `LiveSyncReplicator.unit.spec.ts` owns the CouchDB remote-chunk batch contract: a mixed `_all_docs` result must return each available document even when another keyed row reports an error. `ChunkFetcher.unit.spec.ts` owns the consumer behaviour: it writes valid returned chunks and emits `missingChunkRemote` only for requested IDs which are absent from the returned set. Extend both sides when changing remote chunk acquisition or missing-chunk delivery.

package/docs/offline-scanner.md

@@ -0,0 +1,159 @@
+---
+date: 2026-09-04
+commonlib-version: "0.1.21"
+self-hosted-livesync-version: "1.0.24"
+status: unreleased
+---
+
+# Full offline scan
+
+This document defines the developer contract for `synchroniseAllFilesBetweenDBandStorage`. It describes how the scanner classifies each selected path, chooses an action, and records a database-to-storage reflection. Host-specific setup dialogue and recovery choices remain outside this contract.
+
+Before applying the host's target-file policy, the scanner validates each decoded Metadata document against its actual local document ID. Consistent internal, customisation, and plug-in storage namespaces remain owned by their dedicated features. A namespace disagreement, or a normal-file ID which does not match the ID derived from its recorded path, is quarantined.
+
+The malformed Metadata entry never enters pair processing. If consistent, selected Metadata represents the same case-normalised path, that entry and its storage file continue through the established path-based flow. Otherwise, the storage path is also quarantined. The scanner performs no storage write, database deletion, or last-seen update for an unresolved path, and it retains expired logical deletion history whose identity is inconsistent. This does not add a fourth pair result: quarantined entries do not enter pair processing, and the complete-scan result retains its meaning.
+
+`inspectMetadataDocumentIdentities` provides the separate read-only, actual-ID-first report used by a host repair interface. `repairMetadataDocumentIdentity` revalidates one exact source revision, clears its last-seen state, writes and verifies the expected target, and only then tombstones the obsolete ID. It does not provide batch repair. An exact target left by an interrupted attempt permits the same one-entry repair to finish safely.
+
+The tables below cover only paths which remain after identity validation, the host's target-file policy, and Commonlib's built-in exclusions.
+
+## Full-scan lifecycle
+
+`performFullScan` owns the lifecycle around the pair processor:
+
+1. confirm that settings permit the scan;
+2. read the scanner's `initialized` marker;
+3. when the marker is present, load and complete the stored storage-event operations from the previous runtime;
+4. process expired logical deletion history;
+5. collect and process the selected storage and database entries;
+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.
+
+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.
+
+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.
+
+### 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.
+
+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.
+
+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.
+
+The standard-file revalidation contract is:
+
+| Saved operation                         | Current exact storage state                                         | Operation admitted before the full scan                                              |
+| --------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `CREATE` or `CHANGED`                   | The path is still a selected regular file                           | Store the current stub and content; do not use saved content as a historical version |
+| `CREATE` or `CHANGED`                   | The path is absent, no longer selected, or no longer a regular file | Do not replay the inclusion                                                          |
+| `DELETE` without `renameTarget`          | The selected path remains absent                                    | Apply the saved path's deletion intent                                               |
+| `DELETE` without `renameTarget`          | Any current storage item occupies the path                          | Suppress the stale deletion                                                          |
+| `DELETE` retaining `renameTarget`       | Current source selection and rename-exclusion checks permit deletion | Apply the old document's deletion, including a deliberately excluded same-ID destination |
+| `RENAME` between distinct document IDs  | The new selected path exists                                        | Admit the inclusion half using the new path's current stub and content               |
+| `RENAME` between distinct document IDs  | The old selected path is absent                                     | Admit the deletion half for the old path                                             |
+| `RENAME` between distinct document IDs  | Either half is contradicted by current storage                      | Suppress only that half; the other independently validated half may proceed          |
+| 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.
+
+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.
+
+Independent validation of rename halves does not remove target-first execution. When the new path currently exists, its inclusion must finish successfully before the old-path deletion may run. A failed inclusion preserves the old database entry. When the new path is currently absent, there is no inclusion to publish, and a separately validated absence at the old path may be applied as deletion intent.
+
+`INTERNAL` operations remain owned by the host feature which registered the optional-file handler. That owner must read its current internal storage state; the ordinary file-pair scan does not make a recovery guarantee for an internal path. `SENTINEL_FLUSH` carries ordering only and never represents file state.
+
+The full scan is not a transaction. Expired deletion history may be updated before a later pair fails, and the device-local last-seen map is saved asynchronously after pair processing. The aggregate result does not promise rollback of those earlier side effects or durable completion of that deferred map save.
+
+## Pair states
+
+| State             | Storage             | Local database                   |
+| ----------------- | ------------------- | -------------------------------- |
+| `both`            | File exists         | Live metadata entry exists       |
+| `storage-only`    | File exists         | No metadata entry exists         |
+| `db-only`         | File does not exist | Live metadata entry exists       |
+| `both-db-deleted` | File exists         | Entry records a logical deletion |
+| `db-only-deleted` | File does not exist | Entry records a logical deletion |
+
+A metadata entry with live conflicts is skipped before the ordinary action is selected. It must not be applied to storage by a full scan.
+
+## Option predicates
+
+The action matrix uses these predicates:
+
+- `delete-when-remote-missing` is enabled by `ExtraOnRemote.DELETE_LOCAL_MISSING` or `ExtraOnLocal.DELETE_DB_MISSING`;
+- `delete-when-remote-deleted` is enabled by `ExtraOnRemote.DELETE_LOCAL_MISSING`, `ExtraOnLocal.DELETE_DB_DELETED`, or `ExtraOnLocal.DELETE_DB_MISSING`; and
+- `append-storage-only` is enabled by `ExtraOnLocal.APPEND_STORAGE_ONLY`.
+
+These names explain the table only. The source constants remain the API.
+
+## Action matrix
+
+| Pair state        | `DB_APPLY`                                                         | `NEWER_WINS`                                                                                                  |
+| ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `both`            | `update-storage`                                                   | `sync-newer`                                                                                                  |
+| `storage-only`    | `delete-local` when `delete-when-remote-missing`; otherwise `skip` | `delete-local` when `delete-when-remote-missing`; otherwise `update-db`                                       |
+| `db-only`         | `update-storage`                                                   | `update-storage`, subject to the device-local offline-deletion override described below                       |
+| `both-db-deleted` | `delete-local` when `delete-when-remote-deleted`; otherwise `skip` | `delete-local` when `delete-when-remote-deleted`; otherwise `update-db` when `append-storage-only`, or `skip` |
+| `db-only-deleted` | `skip`                                                             | `skip`                                                                                                        |
+
+`NEWER_WINS` changes a `db-only` action to `delete-db` only when the device-local last-seen map proves that the file existed on an earlier scan and that observed storage mtime is not older than the database mtime under `compareMTime`. This represents a file deleted while the scanner was offline. A database mtime copied from a failed reflection is not such evidence.
+
+The Cartesian `resolveFilePairAction` unit test is the executable counterpart of this matrix. Change the implementation, table, and test together.
+
+## Pair processing result
+
+Each selected pair finishes in one of three states:
+
+| Result      | Meaning                                                                               | Complete-scan result |
+| ----------- | ------------------------------------------------------------------------------------- | -------------------- |
+| `completed` | The selected action completed, or storage and the database were already equal         | Success              |
+| `skipped`   | Scanner policy deliberately left the pair unchanged                                   | Success              |
+| `failed`    | The selected action could not complete, returned a failure result, or raised an error | Failure              |
+
+Conflict guards, size limits, and the explicit `skip` action produce `skipped`. They allow the scan to finish successfully, but do not establish that database content was reflected to storage. In particular, skipping a `db-only` entry must not copy its database mtime into the device-local last-seen map.
+
+An actual storage file remains valid evidence of its own observed mtime even when another action for that pair is skipped. This is distinct from recording the database mtime after a successful database-to-storage reflection.
+
+## Database-to-storage reflection result
+
+When `update-storage` invokes `dbToStorage`, its result controls every success side effect:
+
+| `dbToStorage` outcome | Pair result | Success event and log | Last-seen entry for the database mtime | Later `NEWER_WINS` scan                           |
+| --------------------- | ----------- | --------------------- | -------------------------------------- | ------------------------------------------------- |
+| `true`                | `completed` | Emitted               | Recorded                               | May recognise a later absence as a local deletion |
+| `false`               | `failed`    | Not emitted           | Not recorded                           | Retries `update-storage` while the file is absent |
+| Throws                | `failed`    | Not emitted           | Not recorded                           | Retries after the failed scan can be run again    |
+
+The same result applies when `sync-newer` finds an existing storage file and attempts to reflect a newer database entry. A `false` result must not be converted into `completed`, emit a success event, or replace the observed storage mtime with the database mtime.
+
+By default, the complete scan returns `false` when any pair is `failed`, and returns `true` when every pair is either `completed` or `skipped`. Quarantined entries do not enter this aggregate, so a strict `true` means that no selected pair failed rather than that every discovered entry was resolved or that storage and the database fully converge.
+
+`continueOnFileFailure` is an explicit host completion policy. When it is `true`, the scanner still processes every selected pair, logs each failed path at verbose level, preserves every failed pair and its retry state, and then returns `completed-with-file-failures` from the aggregate boundary. The existing completion log records the total failed count. The option does not turn a failed pair into `completed`, create success events or last-seen evidence, bypass a rejected scan precondition, or accept an exception raised before the aggregate boundary.
+
+`VaultScanResult` therefore has three outcomes: `false` for a rejected or strict failure, `true` for a complete scan without pair failures, and `completed-with-file-failures` when the caller explicitly accepts readiness after one or more pair failures. The non-boolean outcome lets the host present an actionable warning without making Commonlib responsible for user-facing notices.
+
+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.
+
+## Result-state verification
+
+Focused two-pass coverage starts with a `DB_APPLY` reflection whose file handler returns `false`, persists the resulting scanner state, and then runs `NEWER_WINS`. It verifies that:
+
+- both scans report failure;
+- the failed path is retried through `dbToStorage`;
+- no success event or success log is emitted;
+- the database mtime does not enter the last-seen map; and
+- `deleteFileFromDB` is not called.
+
+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`.
+
+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.
+
+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

@@ -40,6 +40,10 @@ Commonlib's confirmation contract can also convey a host-neutral vertical action
 
 Self-hosted LiveSync's Obsidian and browser dialogue hosts now share an application-owned `SvelteDialogSession` lifecycle. They continue to consume Commonlib's dialogue types and manager base, but no maintained LiveSync path uses `SvelteDialogMixIn`. The dynamic-inheritance helper remains available through the compatibility boundary and is deprecated in favour of host-owned composition.
 
+Commonlib's storage-event tests verify that a current file with the same canonical document ID suppresses a watcher deletion, while observed absence still permits deletion and inspection failure preserves Metadata. Rename-derived deletions retain their destination and distinguish deliberate target exclusion from transient filename collision rejection, including after snapshot restoration. A separate reflection test preserves incoming logical-deletion behaviour. These injected-boundary tests establish the [storage-event admission contract](storage-events-and-reflection.md), not the native event ordering of an external folder rename in a particular Obsidian version.
+
+The downstream `E2E_OBSIDIAN_ONLY_PARENT_CASE_DELETION` scenario additionally exercises an external parent-directory case change in real Linux Obsidian 1.12.7. With released Commonlib 0.1.21, native `create` events for the new paths followed by `delete` events for the old paths produce logically deleted Metadata. The `delete` notification carries no `renameTarget`; the guard preserves current same-ID storage without inferring a causal link from the earlier `create`. With the implementation included in Commonlib 0.1.23 installed from its checked package artefact, the same sequence preserves Metadata, Chunks, and unchanged content locally, in CouchDB, on a second Vault, and after restart. This establishes the tested build's deletion protection, not full directory rename support or confirmation in the reporter's Obsidian 1.13.7 environment.
+
 ## CLI
 
 The CLI extends the same neutral context with its database path and injected `StandardIo` in `src/apps/cli/services/NodeServiceContext.ts`. Its entry point creates the Node standard-I/O adapter once and passes it to command composition, while unit tests provide stream-independent fakes for parsing, prompts, standard output, and standard error.

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

@@ -0,0 +1,107 @@
+---
+date: 2026-09-05
+commonlib-version: "0.1.23"
+self-hosted-livesync-version: "1.0.25"
+---
+
+# 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.
+
+## Processing directions
+
+`StorageEventManager.appendQueue` receives watcher events, applies target and
+ignore policies, and queues `CREATE`, `CHANGED`, `DELETE`, or `RENAME` work. A
+rename from a selected path to a rejected path becomes a `DELETE` with an
+old-path deleted stub and the destination in `FileEventArgs.renameTarget`.
+A rename from an excluded path to a selected path becomes a `CREATE`.
+
+`renameTarget` is recorded only when one incoming `RENAME` is converted in
+this way. It is not inferred by pairing independent `CREATE` and `DELETE`
+notifications. A `DELETE` without it cannot establish that a current same-ID
+file is the deliberately excluded destination of a rename. The ordinary
+current-storage check therefore suppresses that deletion, even when the
+current file's path would itself be excluded from synchronisation.
+
+`ServiceFileHandlerBase` serialises this work by the canonical document ID
+derived from each path. Before a watcher `DELETE` reaches `deleteFileFromDB`,
+the handler rechecks current storage under that lock. Rename-derived deletions
+lock both source and destination document IDs. This direction updates database
+Metadata; it does not remove the physical file from storage.
+
+An event marked `restoredFromPreviousRuntime` is separately revalidated against
+current storage and selection before the full offline scan. An ordinary
+restored deletion requires current absence; one retaining `renameTarget` uses
+the rename-exclusion checks below as well as current source selection. Older
+snapshots without that field keep their conservative absence-only rule.
+
+Database-to-storage work follows the opposite direction. Replicated Metadata
+reaches `_anyProcessReplicatedDoc`, which applies target and size checks,
+obtains a storage stub, and calls `dbToStorage`. Logical deletion, conflicts,
+and unsynchronised storage content retain their existing reflection rules.
+The watcher guard does not intercept this path or general explicit database
+deletion operations.
+
+## Event intent and current storage state
+
+| Event intent | Current storage observation | Admitted operation |
+| --- | --- | --- |
+| Watcher `CREATE` or `CHANGED` | A selected regular file is present | Keep the existing storage-to-database write. |
+| Watcher `DELETE` without `renameTarget` | A current file resolves to the same canonical document ID, including at an excluded path, or a folder occupies the path | Suppress the database deletion; no rename destination is known. |
+| Watcher `DELETE` without `renameTarget` | The host lookup reports no current item, or a file belonging to a distinct document ID | Use the existing deletion operation. |
+| Watcher `DELETE` without `renameTarget` | Lookup fails | Leave the database unchanged; failure is unknown, not absence. |
+| `RENAME` converted to `DELETE` | The destination is still selected when case-collision rejection is omitted | Suppress the database deletion. |
+| `RENAME` converted to `DELETE` | The destination is deliberately excluded, and the source is absent | Apply the old document's deletion. |
+| Case-only `RENAME` converted to `DELETE` | Source lookup resolves to the exact deliberately excluded destination, not the original path | Apply the old document's deletion despite the shared ID. |
+| Restored `DELETE` without `renameTarget` | A current item occupies the saved path | Keep the existing restored-event suppression. |
+| Replicated logical deletion | Storage contains a file | Keep the existing database-to-storage conflict and preservation rules. |
+
+## Rename exclusion and preservation
+
+The retained destination distinguishes deliberate exclusion from temporary
+rejection by the filename collision check, which counts the host's indexed
+paths. The handler queries `isTargetFile` with `skipCaseCollisionCheck` only
+for that classification; other target policies, built-in exclusions, and the
+current file-size limit still apply. This option does not authorise storing a
+duplicate file.
+
+A target lookup which resolves to another spelling or a folder is ambiguous
+and preserves the database entry. A file recreated at the exact original path
+also prevents deletion. The same-ID exception in the table applies only when
+source lookup resolves to the exact excluded destination instead.
+
+Suppression leaves storage and Metadata unchanged and records a notice. It
+does not automatically write content, schedule a retry, or converge path
+spelling. A later scan or event may reconcile the state, subject to its own
+policy. The storage lookup may be a host index rather than an operating-system
+existence check: the observation is made under the application lock, not in
+an atomic filesystem transaction.
+
+## Verification and scope
+
+Focused unit tests cover a current canonical file, absence, lookup failure,
+distinct document IDs, an excluded same-ID file without inferred rename
+intent, retained rename destinations, transient collision rejection,
+deliberate exclusion, and source recreation. Live and restored deletions are
+exercised separately. A database-to-storage test also verifies that an
+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.
+
+The maintained host's real-runtime comparison is recorded in
+[Proven in maintained hosts](proven-in-use.md#obsidian-plug-in), separately
+from these unit-test guarantees.
+
+## Related documents
+
+- [Full offline scan](offline-scanner.md), especially [Stored event interpretation](offline-scanner.md#stored-event-interpretation).
+- [Conflict resolution and file provenance](conflict-resolution.md).
+- [Commonlib development](development.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",