# Synced-Clock / Synced-Tick Research

Working notes for the **synced-clock / synced-tick** subsystem: how a sparse, peer-to-peer,
no-master mesh agrees on *"what tick is it right now"* across the hard distributed edge cases that the
original `oldest-epoch-wins` rule could not handle. These are design/research documents, not API docs —
they capture the reasoning, prior art, and honest limitations behind the implementation.

Anchored in the codebase by **`DECISIONS.md` #37** and the executable specs in
**`tests/synced-tick-distributed-spec.test.js`** (the EDGE 1–6 blocks).

## Contents (suggested reading order)

1. **[TIMER_RESEARCH_PLAN.md](./TIMER_RESEARCH_PLAN.md)** — the overall plan and framing: the 6 hard
   EDGE cases, constraints (sparse P2P, no server, monotonic tick), and the phased approach.
2. **[PRIOR_ART.md](./PRIOR_ART.md)** — survey of distributed-systems algorithm families with an
   explicit accept/reject for each against our constraints.
3. **[DESIGN_EDGE1_EDGE2_EDGE4.md](./DESIGN_EDGE1_EDGE2_EDGE4.md)** — the frame-authority token (the
   seniority "spine"): cold-start tie-break, group merge, seniority-beats-readiness.
4. **[DESIGN_EDGE3_EDGE6.md](./DESIGN_EDGE3_EDGE6.md)** — correction policy: slew small corrections vs
   abandon-and-resync (state, not just the tick counter) for large ones.
5. **[DESIGN_EDGE5A.md](./DESIGN_EDGE5A.md)** — defensive sibling of the spine: staleness
   self-demotion and the corroboration gate against a stale/forged seniority token.
6. **[HONEST_LIMITS.md](./HONEST_LIMITS.md)** — per CLAUDE.md §4: exactly what the deterministic
   harness can and cannot prove, and the minimal residual that needs a human.

> Note: the design notes and `HONEST_LIMITS.md` are point-in-time records of the research as it
> progressed; suite counts and "unsolved" framing reflect the state when each was written, not
> necessarily the current `main`/branch state.