Development Practices

Development Practices

Protocol work isn't library work. The contract's quality can only be proven by someone implementing against it, not by your own code passing.

---

Write the call sites before the spec

Start from how a host and a plugin author want to use it, then reverse-engineer the spec. Writing three pages of spec first guarantees clauses nobody needs.

Practically: Day 1 produces two files of code that don't run — the LlamaIndex pipeline as you wish it read, and a plugin's main loop as you wish it read. The spec skeleton is derived from those.

---

Fixtures define the protocol, prose only describes it

Every MUST in the spec gets a conformance case the same day. A clause you can't write a fixture for is one you haven't thought through — delete it.

Questions like "how do overlapping REDACT spans merge" take a paragraph in prose and stay ambiguous; a fixture settles them in three lines. That is why Open Questions lists what closes each item rather than arguing it out.

---

Attack your own runtime

rsp-chaos crashes, hangs, emits garbage, floods stdout, and returns out-of-range spans on demand. Each mode maps to a spec clause.

The out-of-range span case especially — if the host doesn't validate, a malicious plugin can DoS it through a slicing exception. A security protocol whose runtime can be killed by its own plugins is not a security protocol.

Expect Day 7 to rewrite the error-handling section. That's the point of scheduling it before the freeze, not after.

---

Version from day one

Handshake exchanges rsp_version. Rule: unknown fields MUST be ignored, never error. Without this, every future change is breaking. See D8.

---

Every clause carries a Rationale

Six months on you won't remember why spans are byte offsets rather than character offsets, and neither will anyone proposing to change it. The long-form reasoning lives in Design Decisions; the one-line version lives next to the clause.

---

Freeze last

Before tagging v0.1, delete every clause not exercised by an implementation and a fixture. Dead clauses are worse than missing ones — they mislead implementers, and an implementer misled by a security spec ships an insecure host.

---

The test that matters

Hand SPEC.md and the conformance kit to someone with no context and no access to the runtime source. If they ship a conforming plugin without asking a question, the spec is done. If they ask even one, that question is the next thing to fix.