first commit

docs/persistence/storage/storage-uri-plugin-fallback/src/ops/delete.md

@@ -0,0 +1,68 @@
+# ops/delete
+
+## Purpose
+
+The `ops/delete` module implements `fallbackDelete`, the mirror-aware
+removal operation. It dispatches `remove` to every candidate via
+`Promise.allSettled`. Under the default `deleteMode: "any-success"` it
+returns `true` when at least one candidate confirmed removal; under
+`"all"` it throws `WRITE_MIRROR_FAILED` if any candidate rejects. The
+result matches `StorageLike.delete`'s boolean contract while preserving
+structured failure metadata.
+
+## Features
+
+- Mirror fan-out via `Promise.allSettled`.
+- `deleteMode: "any-success"` (default) and `"all"` matrix.
+- Pre-aborted signal short-circuit under `stopOnAbort`.
+- Foreign throwables wrapped in `MirrorOutcome.error` per leg.
+- Surfaces total failure with `WRITE_MIRROR_FAILED` when every leg fails.
+
+## Usage: Basic Example
+
+```ts
+import { fallbackDelete } from "@suaveplan/storage-uri-plugin-fallback/ops";
+
+const removed = await fallbackDelete(
+    uri,
+    { resolver, policy, events },
+    signal,
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { fallbackDelete } from "@suaveplan/storage-uri-plugin-fallback/ops";
+
+try {
+    await fallbackDelete(
+        uri,
+        {
+            resolver,
+            policy: { ...policy, deleteMode: "all" },
+            events,
+        },
+        signal,
+    );
+} catch (e) {
+    if ((e as { code?: string }).code === "FALLBACK_URI.WRITE_MIRROR_FAILED") {
+        console.error("delete left a stale mirror behind");
+    }
+}
+```
+
+## API Reference
+
+- `fallbackDelete(uri, deps, signal): Promise<boolean>`
+- `DeleteDeps` — `{ resolver, policy, events }`.
+
+## Implementation Notes
+
+`any-success` resolves `false` when every candidate cleanly reported the
+key was absent (no failures, no removals). It only throws when every leg
+actively rejects. `deleteMode: "all"` upgrades any leg failure to a
+structured throw so callers needing strict mirror parity can pattern
+match on the code.
+
+This module is part of the universal fallback URI plugin family. It coordinates with the recursion, walk, ops, observability, and classification modules through small, narrowly-typed value contracts. The implementation deliberately keeps surface area small so each piece can be substituted or instrumented independently without touching consumers. Refer to the package README for the end-to-end picture and to the spec delta for the requirement matrix this module helps satisfy.