Initial Commit

packages/persistence/storage/storage-uri-plugin-fallback/src/walk/parallel.md

@@ -0,0 +1,68 @@
+# walk/parallel
+
+## Purpose
+
+The `walk/parallel` module implements the `Promise.any`-style race
+strategy activated when `policy.maxParallel > 1`. It dispatches up to
+`maxParallel` candidates concurrently, returns the first to resolve, and
+aborts every pending candidate via a composed `AbortSignal` so they can
+release any held resources. Failures arriving before the first success
+are collected; if every candidate ends in transient failure, the walk
+throws `ALL_CANDIDATES_FAILED` with the per-leg cause chain populated.
+
+## Features
+
+- Concurrency cap honouring `policy.maxParallel` and the candidate count.
+- Composed abort propagation via `anySignal([callerSignal, internal])`.
+- Per-candidate counter and `attempt-failed` / `attempt-succeeded` events.
+- Semantic failures surface immediately, halting the race.
+- Honours `policy.stopOnAbort` on pre-aborted caller signals.
+
+## Usage: Basic Example
+
+```ts
+import { walkParallel } from "@suaveplan/storage-uri-plugin-fallback/walk";
+
+const bytes = await walkParallel(
+    {
+        uri,
+        candidates,
+        ctx,
+        policy: { ...policy, maxParallel: 3 },
+        events,
+        signal,
+    },
+    async (candidate, s) => resolver.read(candidate, s),
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { walkParallel } from "@suaveplan/storage-uri-plugin-fallback/walk";
+
+await walkParallel(
+    { uri, candidates, ctx, policy, events, signal },
+    async (candidate, s) => {
+        const res = await fetch(candidate, { signal: s });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return new Uint8Array(await res.arrayBuffer());
+    },
+);
+```
+
+## API Reference
+
+- `walkParallel<T>(opts: ParallelWalkOptions, dispatch: Dispatch<T>): Promise<T>`
+- `ParallelWalkOptions` — `{ uri, candidates, ctx, policy, events, signal }`.
+
+## Implementation Notes
+
+The walk uses an internal `AbortController` that fires as soon as one
+candidate resolves; pending candidates observing the composed signal
+abort cooperatively. Completion bookkeeping (`completed >= total`) is the
+only path that throws `ALL_CANDIDATES_FAILED` after exhausting the work
+queue, ensuring the structured error always carries one entry per
+attempted candidate.
+
+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.