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