// SPDX-License-Identifier: CC-BY-SA-4.0
= Overlay Protocol — Keep-Spec Decision
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
:updated: 2026-04-05
:decision: KEEP-SPEC-DEFER-IMPL

== Decision

**Keep the spec. Defer implementation.**

The overlay-protocol directory contains a 420-line specification
(`OVERLAY-PROTOCOL-SPEC.md`), an Idris2 ABI skeleton
(`src/abi/OverlayProtocol.idr`), and an empty Zig FFI scaffold. There is
no reference implementation, no tests, no consumer.

Three options were considered:

[cols="1,3,2",options="header"]
|===
| Option | Pros | Cons

| Complete
| Spec gets implementation + tests
| No consumer yet — risk of building to no requirements; significant work
  while other protocols (AVOW, Groove) have active consumers

| Archive
| Reduces standards-repo noise; removes dead code paths
| Loses the spec (420 lines of thinking); the topic may become relevant
  and reintroducing it later is costly

| **Keep spec, defer impl** (chosen)
| Spec remains discoverable and citable; zero maintenance cost until a
  real consumer appears; ABI scaffold documents the intended shape
| Standards repo lists a protocol that has no runtime — must mark clearly
|===

== Actions taken

1. This document records the decision
2. The spec remains at `OVERLAY-PROTOCOL-SPEC.md` (unchanged)
3. README and ROADMAP will mark overlay-protocol as `SPEC-ONLY` status
4. TOPOLOGY / PROTOCOLS listings should include the `SPEC-ONLY` tag
5. CRG grade for overlay-protocol: **E** (exploratory — spec exists, no
   field validation)

== When to revisit

Revisit this decision if ANY of these become true:

- A concrete consumer emerges that needs overlay-protocol semantics
- AVOW, Groove, or another adjacent protocol wants to delegate to overlay
- The spec itself becomes a citation target outside hyperpolymath

Until then, no effort is spent on overlay-protocol.

== Rationale for NOT archiving

The spec describes a class of problems (protocol overlays on existing
transports) that will recur. Keeping 420 lines of careful design thinking
costs nothing and preserves optionality. Archiving would mean rediscovering
the same design space later.
