jev-tree explained

jev-tree explained

255 is the wall.

TypeSafe’s Jev can name two hundred and fifty-five options in one choice question. A real incident catalog, SKU list, or workflow index is bigger than that. The library is a walk, not a wider question.

september 17, 2026you'll be doing the clicking5 machines
Click the ticket. Watch it walk a tree.
click
Jev
region
service
mode
ticket → leaf✓three choices of 8, not one choice of 320
Jev never sees more than eight options at a time

A choice in Jev is a small, typed question: here are N named options, pick one, and also give me a probability. N cannot be 320. If you truncate the catalog to 255, Cape Town simply does not exist. If you invent a leaf after a timeout, you have lied. jev-tree is the boring way out: give Jev a tree, ask one level at a time, and fail closed.

Machines cloned from mcpexplained. Same paper, same clicks. Different wall.

01The cap

Jev is not a chatbot you prompt into listing a thousand SKUs. The choice head has a hard ceiling: 255 criteria. Throw a 320-leaf catalog at one call and the packet hits the wall.

Goals
throw 320 options at one Jev call
One choice question, 320 names
320 leaves
Jev
320 options → one choice✕Jev will not list more than 255 criteria
TypeSafe’s choice API stops at 255. That is a hard cap, not a suggestion.

That is the whole product requirement. Everything else in the library is how you walk around the wall without pretending it isn't there.

02Ask smaller questions

Author a taxonomy. Region, then service, then failure mode. Eight, then eight, then five. Jev never sees more than eight names. Cape Town is leaf 280 in document order — past the cap — and the walk still lands.

Goals
walk Cape Town → postgres → lag
Authored tree: 8, then 8, then 5
ticket
Jev
8 regions
8 services
5 modes
3 calls × ≤8 options✓Cape Town is leaf 280. Truncation never names it.
replication risk service=postgres region=af-south-1 replay_lag=47m. primary still accepting writes.
on the wire · one level
→ choice among 8 regions
pick: af-south-1   p≈0.9

→ choice among 8 services in that region
pick: postgres   p≈0.9

→ choice among 5 modes
pick: data-loss risk
three calls. never 320 names. never 255 names.

03No tree? Bucket the list

A flat list of 320 leaves is legal input. Siblings over maxFanout (default 32, hard 255) get partitioned into labeled buckets: first label, last label, a count, an id range. Jev picks a bucket, then a leaf. The middle of a bucket is not named. That is why an authored tree beats auto-partition when the labels matter.

Goals
partition 320 leaves into buckets
No tree? Bucket the list.
320 leaves
Jev
us-east-1 … eu-west-1eu-central-1 … TokyoSão Paulo … Cape Town
flat 320 → buckets✓fallback. The bucket text names the edges, not the middle.
jev-tree never sends more than maxFanout (default 32) criteria in one call

04Do not invent a leaf

Timeouts, 429s, and nonsense answers return reason: "unavailable". The path stops on the last node actually reached. A guessed leaf is worse than a miss — it routes a human to the wrong queue.

Goals
timeout a choice and watch it refuse to guess
Timeouts do not mint a leaf
Jev
a leaf?
timeout → unavailable✕reason stays unavailable. path stops on the last real node.

05What actually happened

We built a 320-leaf multi-region incident catalog, labeled 180 synthetic tickets, and asked live Jev four ways: planted-field keyword, an authored tree, a flat partition, and a single 255-option truncation. Same Gateway key, zero data retention.

methodalltailwhy
keyword (planted fields)100%100%sanity check, not the product
authored tree100%100%8, then 8, then 5
flat + partition99.4%99.4%fallback when you have no tree
truncate to 25550%0%Cape Town does not exist
n=180, 320 leaves, seed 20260917. Jev on Vercel AI Gateway with ZDR. Truncate cannot name gold leaves at index ≥ 255.

Truncation is not “almost a tree.” On the tail it is a different product: the true type is not in the question. The tree is how you keep Cape Town on the map.

datasetSynthetic. Seed 20260917. Not production tickets. Numbers and JSONL live on Hugging Face: reachjalil/jev-tree-choice-cap. Library: github.com/reachjalil/jev-tree.

the wall is 255. walk around it.