# epiphany-ops

The Epiphany **concurrent semantics**: the operations through which the score
graph becomes a *live* model, and the deterministic reduction by which a set of
operations becomes a materialized score state. Implements the normative
requirements of **Chapter 6 (Semantic Operations and Concurrent Reduction)** of
the core specification (`spec/core_spec.pdf`). This is Agent C's crate per
`spec/QUICKSTART.md`, building on Agent A's `epiphany-determinism` and Agent B's
`epiphany-core`.

> A score's state is defined by the set of operations committed to it. Any
> materialized graph is a deterministic reduction of that set; caches,
> snapshots, and partial reductions are acceleration structures, never the
> source of truth.
> — Chapter 6, Design Principles

## The thesis in one paragraph

The replicated operation set is a grow-only **CRDT**: replicas accumulate
[envelopes](src/envelope.rs) and converge on the same set. The materialized
graph is **not** a CRDT — it is the deterministic reduction of that set in a
single **canonical order** (causal-first, then the HLC tuple). Any permutation
of the same envelopes reduces to byte-identical materialized state. That
property is the determinism heart of the architecture, and the
[reduction fuzzer](src/fuzz.rs) is its tripwire.

## What's here

| Area | Items | Spec |
|------|-------|------|
| Stamps | `HybridLogicalClock`, `OperationStamp`, the reduction & monotonicity tuples | Ch. 6 §"Operation Identity and Stamps" |
| Causal context | `CausalContext` (dotted version vector), `covers`, the missing-predecessor signal | Ch. 6 §6.2 |
| Payloads | `OperationKind`, the discriminator-only `OperationKindTag`, `OperationPayload`, the §6.10 representative ops | Ch. 6 §"Operation Envelopes", §6.10 |
| Envelopes | `OperationEnvelope`, `EnvelopeHash` (`MUSCENVH`), `well_formed` (incl. `stamp.id == id`) | Ch. 6 §6.4 |
| Slots | `OperationSlot::{Single, Equivocated}`, the order-independent (Pass-10) transitions | Ch. 6 §6.5 |
| Anomalies | `AnomalousReplicaSegment`, `IntegrityAnomaly`/`Kind`, the HLC-monotonicity detector | Ch. 6 §6.6; Ch. 5 §"System-Derived Counter Collisions" |
| Effects | `OperationEffect`, `NoOpReason`, the typed `PreconditionFailureReason`, `RepairRecord`/`RepairKind` | Ch. 6 §6.3.2, §6.5 |
| Conflicts | `ConflictRecord`, `ConflictKind`, content-derived `ConflictId` (`derive_conflict_id`), the registry, resolution | Ch. 6 §6.4 |
| Transactions / undo | `TransactionDescriptor` with the causal-prior-descriptor rule, `UndoTransactionPayload` / `UndoPolicy` | Ch. 6 §6.6, §6.8 |
| Operation set | `OperationSet`: accept pipeline (well-formedness → slot → causal), grow-only | Ch. 6 §"Envelope Acceptance" |
| Reduction | `canonical_reduction_order` (single function), `MaterializedState`, the reduction driver | Ch. 6 §6.3 |

## The determinism this crate enforces

1. **A single reduction-order function.** `canonical_reduction_order` performs
   deterministic causal topological ordering, using the intrinsic stamp tuple
   `(physical, logical, replica, counter)` only among ready operations.
2. **Order-independent equivocation.** A duplicate `OperationId` with different
   canonical bytes transitions its slot to `Equivocated` regardless of which
   envelope arrived first (Pass 10). Equivocated slots contribute nothing to
   reduction; dependents are held pending.
3. **Content-derived facts.** `ConflictId` and `IntegrityAnomalyId` are derived
   from content, so two replicas reducing the same set agree on every conflict
   and anomaly id — the conflict registry and anomaly register are deterministic
   materialized facts, not local bookkeeping.
4. **Byte-identical materialized state.** `MaterializedState::canonical_bytes`
   serializes the effect log, conflict registry, anomaly register, object
   existence, spellings, and LWW fields in their normative orders.
5. **Real graph materialization.** `OperationSet::reduce_onto(&base_score)`
   returns `GraphMaterialization { state, score }`. The graph is mutated in the
   same canonical order and compares by canonical event identity, independent
   of arena storage order.

## Hand-off gates

Run the gate harnesses (QUICKSTART, Agent C):

```
cargo test -p epiphany-ops
cargo run --release -p epiphany-ops --example fuzz_reduction          # 10k iters, seed 0
cargo run --release -p epiphany-ops --example fuzz_reduction 100000 7 # soak, seed 7
```

- **Reduction determinism** — every randomized envelope set reduces to
  byte-identical materialized state under any acceptance order (v0 acceptance
  criteria 1 and 5).
- **Equivocation order-independence** — every duplicate-id-with-different-bytes
  scenario equivocates regardless of arrival order (v0 acceptance criterion 3).

The integration tests (`tests/concurrent_reduction.rs`) exercise these plus
transaction atomicity, descriptor precedence, anomaly exclusion, and forward
undo through the public API.

## Scope and decisions

Chapter 6 specifies the framework and a *representative* selection of
operations; the full ~60–80-primitive catalog is an explicit open question
(§6.11) deferred to the Operation Catalog companion. This crate implements the
framework in full and the representative operations, which is sufficient to
exercise every reduction discipline. The representative operations can also
reduce onto an `epiphany_core::Score`: insert/delete, voice promotion, supported
cross-cutting structures, system breaks, migration checks, transaction
rollback, and undo mutate the real graph while preserving Agent B's invariants.
`reduce()` remains the base-free CRDT/bookkeeping API; `reduce_onto()` is the
graph-aware editing path. See `DECISIONS.md` for remaining payload boundaries.

Per QUICKSTART "Don't do these": undo is the spec's **forward** compensating
operation, never inverse-based; `unsafe` is forbidden; everything is sync.