# 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.