epiphany/CONFORMANCE.md

# Determinism Conformance Statement

This is the published conformance statement required by the core
specification's Determinism Contract (`core_spec` Appendix D,
§"Conformance Statement", `sec:det:conformance`). It covers the reference
implementation in this repository — the `epiphany-*` workspace crates — as of
the tree that carries this file. Every claim below is anchored by a test named
in the Canonical Byte-Layout Reference (Appendix E) or cited inline.

## Platform and floating-point library

The reference build and CI platform is Linux on x86-64, compiled with stable
Rust (MSRV pinned in `Cargo.toml`, `rust-version = "1.77"`), default target
options — no `fast-math`-class flags anywhere in the workspace.

Canonical state contains no *computed* floating-point values. Every float that
enters canonical state is a stored `CanonicalF64` (finite by construction,
`-0.0` canonicalized) serialized as its 8 little-endian IEEE 754 bytes
(`epiphany-determinism/src/float.rs`); no canonical algorithm derives new
float values into canonical state.

**Transcendental functions.** The only transcendentals in the workspace are
`f64::ln`/`f64::exp` from the platform's `std`/libm, used exclusively by tempo
integration (`epiphany-core/src/tempo.rs`, speed-linear and exponential
segments). Per the contract's required disposition, those conversion outputs
are declared **advisory and non-canonical**: musical time is the exact
rational, wall-clock time is exact integer nanoseconds, and no tempo-derived
float is stored in canonical chunks or hashed into canonical identity. If a
future feature promotes tempo-derived values into canonical state, adopting a
documented portable math library (or quantizing at the canonical boundary) is
a precondition, not an afterthought.

Content hashing is BLAKE3 (the `blake3` crate, workspace-pinned), which is
bit-exact by specification on all platforms.

## Parallel execution strategy

None. Every canonical algorithm — reduction, materialization, pre-passes,
encoding, hashing, layout solving — is single-threaded by construction; the
workspace contains no `rayon`, `std::thread::spawn`, or other concurrency in
any canonical path. The implementation *is* the single-threaded baseline, so
equivalence to that baseline holds by identity. Any future parallel execution
must demonstrate byte-identical output against this baseline before it ships.

## `-0.0` canonicalization and NaN/infinity rejection

`CanonicalF64::new` rejects NaN and ±infinity at runtime in **all build
profiles** (not just debug assertions) and canonicalizes `-0.0` to `+0.0`
before storage, so both are unrepresentable in canonical state. Decoding
treats non-finite float bytes as corruption (typed error, never silent
acceptance), and hash preimages accept only `CanonicalF64` values. Locked by
the unit tests in `epiphany-determinism/src/float.rs` and
`src/serialize.rs`.

## Rounding

Round-to-nearest-ties-to-even is used at every canonical quantization
boundary: `QuantizedCoord` (1/1024 staff space) quantizes via
`round_ties_even` and rejects NaN/infinity/overflow rather than saturating
(`epiphany-determinism/src/coord.rs`), and `ResolvedLayoutIR` quantizes its
f32 working coordinates through the same type at canonical emission.

Declared deviation, inside the advisory surface only: the non-canonical
wall-clock conversion in `tempo.rs` rounds nanoseconds with `f64::round`
(half-away-from-zero). It shares the tempo-integration surface declared
non-canonical above; it must be converted to ties-to-even if that surface is
ever promoted.

## Canonical iteration orders

All canonically-serialized collections iterate in the contract's orders
(§`sec:det:ordering`):

- Generic containers are `BTreeMap`/`BTreeSet` or explicitly sorted through
  `CanonicalMap`/`CanonicalSet`/`sort_canonical`, whose element types must
  implement the `CanonicalByteOrder` marker — a type whose `Ord` does not
  match its canonical byte order is rejected at compile time
  (`epiphany-determinism/src/order.rs`).
- Operation envelopes reduce in the canonical order: causal (Kahn topological
  over DVV coverage), then the HLC tuple
  (`epiphany-ops/src/reduce.rs::canonical_reduction_order`), property-tested
  for permutation invariance at 1,000 envelopes × 10 orders plus a
  10,000-set fuzz gate.
- Conflicts serialize ascending by `ConflictId`; integrity anomalies ascending
  by `IntegrityAnomalyId`; chunk references by `(kind, hash, offset)`;
  extension declarations by `(ExtensionId, SemVer)` as numeric tuples —
  each rejected (not normalized) on decode when out of order.

`HashMap`/`HashSet` appear only in non-canonical lookup indexes, caches, and
diagnostics, or are projected through a sort before any canonical output.

## NFC normalization

Unicode normalization uses the `unicode-normalization` crate
(workspace-pinned, `0.1.x`). Catalog identifiers NFC-normalize at
construction (`epiphany-core/src/pitch.rs`); envelope string fields
NFC-normalize before hashing (`epiphany-ops/src/encode.rs`, test
`nfc_normalizes_before_hashing`); system-derived pitch identity NFC-normalizes
at the derivation boundary. Free-text fields are raw UTF-8 by the ratified
codec convention (`req:format:codec-conventions`) and are not folded.

## Declared open-question algorithms

Per §"Open Algorithm Hooks", every open-question area is either
profile-declared with a versioned identifier or errors rather than
substituting a vendor heuristic:

- **Spelling**: `SpellingAlgorithmId` `"default"` — a Temperley-style
  line-of-fifths preference algorithm, v1 (`epiphany-core/src/prepass.rs`).
  The identifier is ratified normative (Pass 12,
  `req:pitch:spelling-algorithm`). A profile requesting any other id errors;
  nothing is silently substituted.
- **Notational decomposition**: `DecompositionAlgorithmId` `"default"` — the
  integer-grid metric splitter, v1, with its scope bounds ratified as
  normative bounds of the versioned algorithm (Pass 12,
  `req:time:decomposition-algorithm`: single governing meter, `MAX_DOTS = 1`,
  tuplet-nesting deferred; a wider algorithm is a version bump).
  Same no-substitution rule.
- Both pre-pass outputs are **canonical derived annotations**: deterministic
  functions of `(materialized graph, profile, algorithm id)` recomputed on
  materialization, never stored canonical state — so an algorithm version
  change deterministically invalidates derived output without state
  migration.
- **Tempo curves**: `TempoShape::Curve` integration is unimplemented and
  declared as such — conversion returns `CurveIntegrationUnsupported`
  rather than a wrong or vendor-specific answer. The linear/exponential
  segment integration and the `wallclock_to_musical` inverse (deterministic
  continued-fraction with documented iteration/denominator bounds and a
  typed `TempoIntegration`-class tolerance) are advisory, per the
  floating-point declaration above.