# Zudux-State Architecture

## Commit pipeline

Every command crosses the same deterministic boundary:

```text
queue → cancellation → policy → private draft → command → invariants → commit → audit → modules
                                      │              │
                                      └── failure ───┴──→ discard draft
```

The queue prevents two async commands from starting from the same revision and overwriting each other. The working draft is never returned to observers. Publication swaps one state reference and increments one revision.

## Atomic operations

`atomic()` owns one draft for all nested command invocations. Nested commands still pass through policy and module `before` hooks, while publication and the final audit record occur once at the atomic boundary. Any exception discards the complete draft.

## Trust boundaries

- **Commands** express allowed ways to propose changes.
- **Policies** decide whether identity and metadata may request a command.
- **Invariants** decide whether a proposed state is structurally valid.
- **Modules** export lifecycle signals but do not own state.
- **Ports** isolate storage and transport vendors from the core.

Client-side policies are useful for application correctness and UI governance, but they are not a replacement for server-side authorization.

## Immutability model

Zudux-State creates revocable proxies over the current snapshot. The first write to a path creates shallow copies of that path and its ancestors; untouched branches preserve identity. On success the finalized copy becomes the published snapshot and forward/inverse patches are retained. On failure the proxies are revoked and the copies become unreachable. Published snapshots are deeply frozen by default.

`structuredClone` is reserved for seeds, checkpoints, persistence boundaries, and explicit replacement. Command updates use the original copy-on-write runtime.

## Remote state and workflows

The resource hub separates server cache lifecycles from governed client state. The workflow engine and scheduler handle cancellation, concurrency, priorities, deadlines, retry, and circuit breaking outside the commit queue; successful effects can then enter a short domain command.

## Distribution

Replica messages contain patch operations and per-source counters. Event domains use versioned hash-linked facts. Multi-domain coordination is a saga-style compensation model because JavaScript state cannot provide database-level distributed isolation.

## Scaling domains

Prefer several business-aligned domains over one universal object. Keep data together when it must commit atomically; split it when ownership, lifecycle, access policy, or persistence requirements differ. Cross-domain workflows should be coordinated at the service/application layer.

## SSR model

There is no hidden registry. Create one domain per request and pass it to the rendering boundary. Never put request-specific state in a process-level singleton.

## Extension model

`DomainModule`, `PersistencePort`, `PersistenceCodec`, and `RelayPort` are intentionally small interfaces. Infrastructure integrations stay outside the core and can be replaced without changing business commands.