Initial Commit

packages/persistence/storage/storage-uri-plugin-fallback/src/ops/write.md

@@ -0,0 +1,69 @@
+# ops/write
+
+## Purpose
+
+The `ops/write` module implements the write-side semantics of the
+fallback adapter: `fallbackSet` for byte writes and `fallbackWriteStream`
+for streamed writes. Under `policy.writeMode: "all"` (default) the
+operation fans out to every candidate via `Promise.allSettled` so reads
+from any leg subsequently observe the same content; under
+`"first-success"` it walks sequentially and returns on the first leg to
+succeed, letting remaining writes settle in the background.
+
+## Features
+
+- Mirror fan-out with structured `WRITE_MIRROR_FAILED` on any leg failure.
+- `first-success` mode with background remainder + best-effort partial
+  emission on the event bus.
+- AbortSignal short-circuit before dispatch under `stopOnAbort`.
+- Stream-input variant buffers chunks then routes through `fallbackSet`.
+- Foreign throwables wrapped per leg in `MirrorOutcome.error`.
+
+## Usage: Basic Example
+
+```ts
+import { fallbackSet } from "@suaveplan/storage-uri-plugin-fallback/ops";
+
+await fallbackSet(
+    uri,
+    new Uint8Array([1, 2, 3]),
+    ctx,
+    { resolver, policy, events },
+    signal,
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { fallbackWriteStream } from "@suaveplan/storage-uri-plugin-fallback/ops";
+
+await fallbackWriteStream(
+    uri,
+    body,
+    ctx,
+    {
+        resolver,
+        policy: { ...policy, writeMode: "first-success" },
+        events,
+    },
+    signal,
+);
+```
+
+## API Reference
+
+- `fallbackSet(uri, bytes, ctx, deps, signal): Promise<void>`
+- `fallbackWriteStream(uri, body, ctx, deps, signal): Promise<void>`
+- `WriteDeps` — `{ resolver, policy, events }`.
+
+## Implementation Notes
+
+Mirror writes preserve every leg's structured error inside
+`mirrorOutcomes[i].error` — foreign throwables are wrapped in
+`FALLBACK_URI.WRITE_MIRROR_FAILED` so consumers always receive a
+`SuaveplanError`. `first-success` mode emits a single
+`write-mirror-partial` event when at least one background remainder
+write fails so operators can detect mirror drift.
+
+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.