---
type: rule
summary: Before publishing anything, ask whether a caller would have to unlearn it — that outranks cost, latency and convenience
---

# Would the caller have to UNLEARN it?

**Rule:** Before adding, keeping or changing anything on the published surface, ask: *would an application coding against this learn something it has to **unlearn** at migration?* If yes, it is a deviation — whatever it buys in cost, latency or ergonomics. Both halves are binding: the **surface** must be as close as possible to the future SDK, and the **implementation** as close as possible to what NextGraph actually plans. Where upstream's behaviour is known, it is a specification, not a reference.

"Known" is narrow: read in `nextgraph-rs`, or stated by its author. Never inferred from what an npm package happens to expose, and **never inferred from an absent implementation** — *"the engine does not do X"* says nothing about whether the target will.

**Why:** this library's entire value is that an application keeps its code. A layer that teaches a false model destroys exactly what it was built to produce, and it does so silently: nothing fails, the application simply learns a habit that has no successor. Two instances, both caught only by asking the question — *"every document has a native inbox"*, written from general reasoning, false, and already an implementation; and a per-document inbox pointed at its owner's inbox to absorb a measured cost, emulating a many-to-one relation the target cannot express and which would have made applications tag their deposits, for nothing.

**The pressure to deviate never announces itself as one.** It arrives as a cost, a latency, an ergonomic wrinkle — all real, all legitimate. That disguise is what makes it dangerous. When shape and cost conflict: keep the shape and attack the cost elsewhere (usually the lever is *who* pays and *when*). If the cost is genuinely unsolvable, say so rather than bending the model quietly.

**How to apply:** the tell is a symbol that makes the caller handle something the target will never hand it — a key, an inbox address, a store id, its own identity. Two secondary tells, both of which have produced real holes here:

- **A named exception stops being one the moment it is published.** A door documented as *"only this internal caller uses it"* is a door any application can open; the note is not a mechanism. Move it out of the published surface instead.
- **A symbol kept because it was already there is not a decision.** At every surface change, re-ask whether an application still needs each neighbouring symbol; inertia has repeatedly left published what nothing calls.

Applies to the published surface first, but also to internal choices that shape it: an emulation whose relation the target cannot express will surface as a habit sooner or later. When a deviation is genuinely necessary, it must be **deliberate, documented and invisible to the caller** — what is forbidden is the silent one, adopted because it was convenient.