A short tour of the decisions that shape the engine. Each one is a tradeoff made in favor of
predictability and type safety.

## Command in, events out

There is one way to change state — `dispatch(command)` — and one way to observe it —
`subscribe` for snapshots and `on` for typed events. Concentrating mutations behind a command
pipeline (command → reducer → new state → effects → events) makes the engine testable and
race-free, and gives plugins a single place to observe everything.

## Typed results end-to-end

The result generic `R` is threaded through the whole system rather than degrading to `unknown`:

* `Contracts.Api.Me.complete` returns `R`.
* Internal and public completion events carry `R`.
* `upload.completed` emits it; `completed` items keep it on `item.result`.

So UI code reads `item.result.url` with no cast — TypeScript already knows the shape.

## Dedupe without fake intents

When `findByChecksum` matches, the engine finishes the item through a dedicated `dedupe.ok`
event and marks it `completedBy: 'dedupe'`. It does **not** fabricate a synthetic intent or run
a strategy. State stays honest about what actually happened.

## Defaults resolved at construction

`createUploadStore` runs `resolveUploadConfig` once and installs `createXHRTransport()` when no
transport is given. After construction the runtime always holds a fully-specified config, so no
code path has to re-check optional fields.

## The core never imports React

The reducer and runtime are React-free. The React binding lives in `react/` and only reads the
public store interface (`subscribe`, `getSnapshot`, `dispatch`, `on`). No import cycles, and the
same store works in Node, a worker, Vue, or vanilla JS.

## Immutable state updates

Every reducer step returns a new state object; nothing mutates the `items` map in place. This
fixed `useSyncExternalStore` tearing — React can compare snapshots by reference and re-render
exactly when something changed. Cleanup and eviction return new state too.

## One event-emission layer

State-derived public events are emitted from a single point after transitions, not scattered
inside handlers. That removes duplicate emissions and keeps event semantics consistent across
the lifecycle.

## Strategies stay at the edge

The engine selects a strategy purely by the `strategy` field on the intent and calls its
`start`. It never imports a concrete strategy. You only ship the strategies you register, and
custom protocols slot in without forking the engine.

## Security-conscious by default

* Error **messages are static**; tainted values live on `context`, closing an XSS vector (see
  [Errors](/duck-upload/core/errors)).
* The multipart strategy validates every signed part URL — protocol, optional host allow-list,
  and private/loopback IP rejection — before handing it to the transport.
* Persisted snapshots are treated as untrusted: guarded by `isPurpose`/`isIntent` and stripped
  of prototype-polluting keys on the way in.