loco: the shared basin codebook — one FnIndex for a whole palette

[AdaWorldAPI]

The measurement that decided the shape

The loco domain range 0x90..=0xFF is 112 function slots per vocabulary. ogar-ro mints 22 (0x90..=0xA5, read from the relation_palette! table, contiguous by design); recipe_vocab mints 34. A 144-entry relation palette therefore cannot be FnIndex bytes — 144 > 112, and no carving makes it fit.

So a large palette is not a set of functions. It is one function whose operand byte indexes a codebook.

The gap that blocked that

Two mechanisms each had one of the two properties a shared operand table needs, and neither had both:

	index	shape	ownership
ConstantPool	u8 1..=255	classid(4) + 12 V3 facet	owned, per-function
ValueCodebook	u8 id	none — advisory {id, name}	shared, basin-scoped

ValueCodebook's own contract is that the same call in sibling basins may resolve its operand against different codebooks — but it carries no table, so nothing could actually resolve. ConstantPool carries exactly the right table and is owned by ONE function, so a vocabulary-wide set held there would be copied into every function that names it.

crates/ogar-loco/src/basin.rs is the join: the pool's facet arithmetic under the codebook's ownership. ConstantPool::locate and ::slot_payload_offset are called, not reimplemented — pool.rs says the defects live in that arithmetic, so a second copy would be a second place for them to live.

Why this is not the shared-mutable sink pool refused

pool.rs rejects holding constants in the Inventory SoA because "Inventory is shared by every function, so a per-function pool living there is a shared-mutable sink with N writers." That objection is about mutability, not sharing — and it is answered structurally rather than by convention:

BasinCodebookBuilder is the only thing that can intern; seal() consumes it and yields a BasinCodebook with no &mut self method at all. One writer at mint time, zero afterwards. A body resolving an operand borrows &BasinCodebook and cannot reach a mutation it does not have.

The seam

BasinCodebooks::resolve_operand(vocab, call, i) asks the vocabulary which codebook the call's function declares, then resolves that byte against it. This is what makes Vocabulary::value_codebook load-bearing rather than advisory — before it, the declaration named a table nothing could reach.

What the entry classid buys

An entry is classid(4) + 12 — the V3 content-blind register — and the classid names the READING: 6×(u8:u8), 4×(u8:u8:u8), 3×(u8:u8:u8:u8) or 12×u8 over the same bytes. That is what makes an index into this table different in kind from an enum ordinal: a flat ordinal has no metric (nothing about 71 says it is near 72), whereas a quantizer code answers distance by table lookup.

No classid is minted here. As in pool, the classids stay PARAMETERS supplied by the caller, because minting a concept is an operator decision with a ledger entry.

Axis discipline

0x90 names three different things in this workspace, and this module touches two:

space	width	what 0x90 names
FnIndex (call codebook)	u8	DOMAIN_FLOOR, first vocabulary-local opcode
ogar_vocab concept domain	u16 hi byte	0x90XX, ROOT of the domain reference tree (0x90..=0x9D: Disease, Phenomenology, Lab, Imaging, Substance, Procedure, Form)
ValueCodebook::id	u8	which codebook a basin plugged in

They never meet — loco's own concepts are 0x1701/0x1702 in Blocks, and this module mints none. But ogar_vocab's domain table already documents a live instance of the overlap (0x9E = has_phenotype in ogar-ro's predicate space, which ogar-ro does mint, as an opcode). The second commit states which axis every 0x9x in basin.rs is on, so a reader who knows 0x90XX as the reference-tree root does not read a health-domain claim into a sentence about function indices.

Tests — 8, each disable-verified

Two were vacuous on first writing and were caught by their own falsifiers:

• Id-keyed resolution survived substituting "return the first book," because both basins listed the same table first. Rewritten to hold two tables in one basin with different bytes at index 1; the substitution now fails.
• The capacity guard survived removal, because u8::try_from returns Full anyway — but without the guard the 256th entry is pushed before rejection. Same error value, corrupted state. Now asserts the table length is unchanged after a refusal; the substitution now fails.

The other six falsifiers failed as intended: dropping classid from entry identity, treating 0 as a real index, writing the payload over the classid, letting a duplicate codebook id shadow, and ignoring the vocabulary's declaration in resolve_operand.

Scope

Additive. ogar-loco stays vocabulary-agnostic — it owns the ABI, the shapes, the pool and now this table, and knows nothing about what any byte means. A thinking IR is a caller that plugs its vocabulary and codebooks in through the same seams; nothing in this module knows one exists.

Ledger: D-BASIN-CODEBOOK in docs/DISCOVERY-MAP.md (append-only, [G]/CODED).

Open underneath, unchanged

W-RO-5 — LaneShape (Pairs/Triples/Quads) and CascadeShape (G6D2/G4D3/G3D4) are bit-for-bit the same carving in two repos, deliberately duplicated because loco is zero-dep. A shared rail codebook is written in one and read in the other, which makes it the first thing genuinely blocked by that duplication rather than merely inconvenienced. Operator call, not this PR's.

Verification

• cargo test -p ogar-loco — 63 passing (55 pre-existing + 8 new)
• cargo clippy -p ogar-loco --all-targets --no-deps — clean
• cargo check -p ogar-loco -p ogar-ro -p ogar-r2il --all-targets — clean

🤖 Generated with Claude Code

---

Generated by Claude Code

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_e26c6282-aafb-4f6b-8e30-90699bd85228)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dc94be7dc2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Resolve operands from the validated vocabulary table

When a caller passes a raw Vocabulary—as this module's new test does—this method re-reads value_codebook from live, unvalidated trait methods. An implementation can override the composed method for shared-core functions or return changing domain_value_codebook answers, causing operands to resolve against a table different from the frozen semantics in CheckedVocabulary/VocabularyTable; the registry also retains only that frozen table. Require a checked vocabulary or perform the lookup directly against VocabularyTable, as the other downstream semantic traversals do.

Useful? React with 👍 / 👎.