Sharding a graph you cannot page: the tree, the chain, and why both decay

[blinkinglight]

Split out of #122, which has the spill numbers but never wrote down the mechanism. Measured against the live graph and source at 0e6f907 today.

Why the graph cannot be paged out of trouble

KGQueryInput is five fields:

type KGQueryInput struct {
	Entity    string
	Predicate string
	AsOf      string
	Direction string
	Status    string
}

Not one of them bounds the result. No Limit, no Offset, no cursor — and internal/mcpserver/kg.go holds zero references to responseBudget, the 40,000-rune ceiling the drawer side enforces. So a node's fan-out arrives whole or it does not arrive: there is no partial read, and no caller-side bound either. A caller who knows a node is huge still has no way to ask for less.

Two measured spills, different shapes, same failure:

query	rows	bytes
entity-wide (legacy root, outgoing)	109	62,952
predicate-wide (qualifies, no entity)	99	58,862

Past roughly 40KB the client spills the result to a file that never enters the model's context. The call succeeds. Nothing in the response says the answer is missing.

The tree bounds breadth — that part is written down

wing_<x>.root → .must / .ref → .<namespace> → <drawer id>, entity carries the path, predicate is the leaf name, invariant of no node over ~35 leaves. Argued in #122; not repeating it.

What a tree cannot bound is a node whose membership is defined by time or volume rather than topic. You cannot split "corrections filed on 2026-08-29" into sub-topics, because the split would have to know what the corrections are about — and the whole point of the index is to answer "what changed since I last looked" without reading them.

So the second structure is a chain, and this is the part nobody wrote up

The corrections index, live today:

corrections → 2026 → 2026-08 → 2026-08-29 → 5 leaves
                                              ├ qualifies → <record>
                                              ├ qualifies → <record>
                                              └ supersedes → <record>

Each leaf's predicate is the kind of correction and its object is the correcting record, so you can decide whether to fetch without fetching. The upper levels have a fan-out of 1 today, and the month level is bounded by the calendar — ≤31 children no matter how fast corrections accumulate, which is the level that structurally cannot overflow.

A day that fills does not sub-divide. It chains: <day> gets a next edge to <day>.2, which gets one to <day>.3. You follow next until it is absent.

Three properties, and they are the whole argument:

1. Append-only. Adding <day>.2 writes exactly one new edge and modifies nothing that exists. Sub-dividing by hour instead would mean relabelling the leaves already filed — a rewrite, with a window in which the structure points nowhere. This palace has already lost a front door that way.
2. No tail pointer. Nothing stores "the current tail", so nothing can be stale. The end of the chain is discovered, not recorded. Every stored pointer is one more thing that can be wrong.
3. Bucket granularity stops being critical. Pick "day" and be wrong, and the chain absorbs it. You do not have to guess the right bucket size in advance — which you cannot, because the volume is what you are trying to measure.

The honest costs, since this is a design thread and not an advert:

• Reads are serial. You cannot know the chain's length without walking it, and you cannot parallelise, because <day>.9's existence is only knowable from <day>.8. A heavy day is N round trips.
• Order is insertion, not importance. "The most recent correction" is at the far end of the last chain node — the single most expensive thing to reach, and often the thing you want most.
• A skip pointer would fix both — give <day> a last edge — and it reintroduces exactly the mutable tail the design removed. Below ~5 hops I do not think it pays; past that the calculation changes and I would want it measured rather than argued.

⚠ And both structures decay, because nothing in the product mints either

This is the part I would lead with if I were writing it again.

Measured today, 2026-08-30:

am_kg_query(entity: "corrections.2026-08-30")
  → resolution: "unknown_term"   count: 0

The index stops at 2026-08-29. I filed three correction edges today and not one of them is in it.

Not because the design failed — because the convention requires two edges per correction (the bare qualifies/supersedes predicate for the resolver, plus an index leaf for the sweep), and I wrote one each time. Nothing refused. Nothing warned. Every am_kg_add returned success. I am the author of both the corrections in question and this complaint.

That is the same defect as .root: a structure that exists only as hand-written data, maintained by whoever remembers the convention. #126 just closed the .root half by making the server mint the edge on write, from the room a drawer was filed into.

The corrections index has no equivalent — and I think it could. The objection would be that an index leaf needs the kind of correction, which is a judgement. It is not: am_kg_add(subject, "qualifies", object) already carries the kind in the predicate and the date in valid_from. The server has everything it needs to mint corrections.<date> --<predicate>--> <object> itself, without deciding anything.

Argument against, and it is a real one: that hardcodes a naming convention — the corrections.* namespace — into the server, which is exactly the line #126 declined to cross ("membership is deliberately untouched; which records are must-load is a judgement no code can make"). The distinction I would draw: membership in the must-tier is a judgement; "this edge is a correction" is a fact the predicate already states. But that boundary is worth arguing before anyone writes code.

What I would like argued back

• Is the chain right at all, or should a day node that fills simply refuse, the way the entry room now refuses a multi-chunk record? A refusal makes the operator split it deliberately; a chain makes overflow invisible, and invisible overflow is what got us here.
• If the server mints correction-index leaves, does it also end them when a fact is invalidated — and does that make the index a second source of truth that can disagree with the edges it indexes?
• Is there a case for kg_query gaining a plain limit as well as the tree? My instinct from Memory design: a front door that cannot grow with the corpus #122 is no — a bounded page is indistinguishable from an exhausted node, which is the same defect one size down — but that argument is weaker now that resolution exists and could carry a fourth value.

[blinkinglight]

Repairing the decay I just measured — which invalidates one figure in the post above.

The post says "the index stops at 2026-08-29 … I filed three correction edges today and not one of them is in it." That was true when I measured it and is no longer true, because I fixed it rather than leaving a demonstration standing in the corpus. Four writes:

corrections.2026-08 --30--> corrections.2026-08-30      (the day node)
corrections.2026-08-30 --qualifies--> 666522a2…          (Q3 framing, narrowed)
corrections.2026-08-30 --qualifies--> d125fa48…          (by-name tree is hand-authored)
corrections.2026-08-30 --qualifies--> d8842ff3…          (PR #126 blocker closed)

Verified: am_kg_query(entity: "corrections.2026-08-30") now returns resolution: "matched", count: 3.

Three things this changes, and one it does not.

The mechanism claim is unaffected — the index still decays by default, still has no minting path, and I still wrote three corrections without index leaves before noticing. The four writes above are me acting as the missing mechanism, which is precisely the argument for building one.

It also priced the thing I was speculating about. The repair took four am_kg_add calls and no judgement: the day node came from valid_from, each leaf's predicate came straight from the correction's own predicate, and each hint I had already written when filing the original edge. Nothing in it required knowing what the corrections were about. That is the strongest evidence I have that the server could mint these — I did it mechanically, from data the server already holds at write time.

And it exposed a wrinkle the post did not anticipate: the day node's source_file hint is authored per day — I wrote "Corrections filed on 2026-08-30…" by copying the 08-29 node's phrasing. A server minting these would need that string templated, which is fine, but it means the convention carries a small amount of prose the code would have to own. Minor, and worth naming before someone discovers it mid-implementation.

The chain half of the post remains untested in the corpus: no day has yet exceeded a node, so <day>.2 has never been minted and the next walk has never been exercised. Everything I wrote about it is design, not measurement, and should be read that way until a day fills.