diff --git a/crates/ogar-vocab/src/lib.rs b/crates/ogar-vocab/src/lib.rs index 053386c..f706a37 100644 --- a/crates/ogar-vocab/src/lib.rs +++ b/crates/ogar-vocab/src/lib.rs @@ -1404,6 +1404,33 @@ const CODEBOOK: &[(&str, u16)] = &[ /// Reserved high-byte slots are listed with their intended domain name /// even before any concept lands in that block, so consumers can branch /// on them today and the meaning is stable as concepts arrive. +/// +/// # The domain byte carries ALTITUDE, not just identity +/// +/// Operator ruling, 2026-08-18 (*"Java is an entire different layer that's +/// why I chose another higher level"*): a slot's **magnitude** encodes how +/// high the thing sits in the stack, so placement is neither mnemonic nor +/// next-free. +/// +/// - `0x00`–`0x0F` — the canonical business/reference ontology. +/// - `0x17` — the substrate's own orchestration tier (`ogar-loco`'s call +/// ABI; see [`Blocks`](Self::Blocks) for the label's narrowed reading). +/// - `0xC0`+ — the **C-band: strata ABOVE the Rust substrate**, i.e. foreign +/// host layers the substrate reaches into rather than owns. +/// +/// This is cheap in exactly the right way: the domain byte is the first two +/// nibbles of the classid, so its **top nibble is a 16-way altitude +/// selector** — one mask separates "substrate ontology" from "host layer" +/// with no lookup and no value decode, which is the canon's *the key +/// prerenders nodes with zero value decode* applied to layering. A +/// first-nibble split is the most expensive split the 16-ary cascade has; +/// spending it on altitude is what makes it worth spending. +/// +/// **Do not cluster by subject matter.** Two vocabularies that share a +/// SHAPE (both are opcode palettes, both are call sequences) do not thereby +/// share a domain — shape-similarity is not domain-identity. A frontend may +/// freely reuse `ogar-loco`'s node shape while owning its own domain; +/// borrowing the container is not joining the domain. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] #[non_exhaustive] @@ -1499,8 +1526,67 @@ pub enum ConceptDomain { /// transcribing a GPL/AGPL implementation, so this public codebook stays /// unencumbered while GPL consumers link it freely. Blocks, + /// `0xC0XX` — **Java runtime** (Project Panama + Project Valhalla): the + /// managed-runtime membrane over the SoA substrate. The **floor of the + /// C-band** — the door every other tenant of that layer arrives through. + /// Carries ZERO vocabulary rows today — same reserved posture as + /// [`Osint`](Self::Osint) / [`Genetics`](Self::Genetics) / + /// [`Blocks`](Self::Blocks): the slot returns a stable domain tag before + /// any concept mints (operator ruling, 2026-08-18). + /// + /// First named consumer: `lance-graph-java`'s planned schema/classid + /// field on `LgjResourceInfo` / `LgjLaneDesc`, by which a native + /// resource names WHICH layout contract its bytes obey instead of + /// implying it via `kind` — the membrane naming itself from inside its + /// own stratum, not a substrate concept borrowed downward. + /// + /// Deliberately **not** generalized to a vendor-neutral `HostRuntime`: + /// no second managed runtime is in scope, and pre-widening a reserved + /// slot for a hypothetical consumer is the speculative move this + /// codebook avoids. A CLR/other-runtime layer, if it ever lands, gets + /// its own C-band slot rather than diluting this one. + JavaRuntime, + /// `0xC1XX` — **Analytics**: the analyst estate — addressable tabular + /// units (the shared concept behind an OGAR *brick* and a lakehouse + /// table alike) plus the catalog ontology around them. Carries ZERO + /// vocabulary rows today; reserved posture as above (operator ruling, + /// 2026-08-18). + /// + /// The domain names the **shared tabular concept**, never a vendor: + /// `ogar-bricks` and a Databricks/Unity-Catalog consumer are two app + /// prefixes over ONE vocabulary — the same fence + /// [`Blocks`](Self::Blocks) carries, and the same shape as the + /// OpenProject/Redmine showcase in `docs/APP-CLASS-CODEBOOK-LAYOUT.md` + /// §2. The *pipeline* that transforms such units is a separate register + /// (a call vocabulary), not a concept in this domain. + Analytics, + /// `0xC4XX` — **Binary lifting**: normalized machine-code IR and the + /// artifact ontology around it (program image, function, section, + /// symbol). Bolted onto [`JavaRuntime`](Self::JavaRuntime) — Ghidra is + /// itself a JVM application — so it is a *tenant* of C0's layer, not a + /// peer of C0. Carries ZERO vocabulary rows today; reserved posture as + /// above (operator ruling, 2026-08-18). + /// + /// The slot number is deliberate: **C4, for the blast radius** of + /// turning any binary into addressable substrate rows. + /// + /// The domain names the **shared lift concept**, never a tool: Ghidra + /// and `r2sleigh` are two consumers of the same SLEIGH specs, hence two + /// app prefixes over ONE vocabulary (the [`Blocks`](Self::Blocks) fence + /// again). + /// + /// **Provenance fence, and it is load-bearing here:** concepts minted + /// in this domain must derive from permissively-licensed or + /// specification sources (Ghidra core is Apache-2.0 — its `opcodes.hh` + /// and the SLEIGH processor specs are usable; the `GPL/` subtree is + /// not needed for lifting) — never by transcribing a GPL/AGPL or + /// LGPL implementation. That keeps this public codebook unencumbered + /// while a GPL consumer links it freely, and lets the GPL boundary sit + /// entirely in the consumer repo. + BinaryLifting, /// Any high-byte slot not yet assigned a domain (`0x05XX`–`0x06XX`, - /// `0x10XX`–`0x16XX`, `0x18XX`+). + /// `0x10XX`–`0x16XX`, `0x18XX`–`0xBFXX`, `0xC2XX`–`0xC3XX`, + /// `0xC5XX`+). Unassigned, } @@ -1524,6 +1610,9 @@ pub fn canonical_concept_domain(id: u16) -> ConceptDomain { 0x0E => ConceptDomain::Genetics, 0x0F => ConceptDomain::Geo, 0x17 => ConceptDomain::Blocks, + 0xC0 => ConceptDomain::JavaRuntime, + 0xC1 => ConceptDomain::Analytics, + 0xC4 => ConceptDomain::BinaryLifting, _ => ConceptDomain::Unassigned, } } @@ -5640,7 +5729,36 @@ mod tests { assert_eq!(canonical_concept_domain(0x1701), ConceptDomain::Blocks); assert_eq!(canonical_concept_domain(0x17FF), ConceptDomain::Blocks); assert_eq!(canonical_concept_domain(0x1800), ConceptDomain::Unassigned); - // Trailing unassigned tail (0x18+). + // ── The C-band (operator ruling 2026-08-18): strata ABOVE the Rust + // substrate. All three reserved-empty; the magnitude is the point — + // a higher slot means a higher layer, not a later mint. + assert_eq!(canonical_concept_domain(0xC000), ConceptDomain::JavaRuntime); + assert_eq!(canonical_concept_domain(0xC0FF), ConceptDomain::JavaRuntime); + assert_eq!(canonical_concept_domain(0xC100), ConceptDomain::Analytics); + assert_eq!(canonical_concept_domain(0xC1FF), ConceptDomain::Analytics); + assert_eq!( + canonical_concept_domain(0xC400), + ConceptDomain::BinaryLifting + ); + assert_eq!( + canonical_concept_domain(0xC4FF), + ConceptDomain::BinaryLifting + ); + // The C2-C3 gap stays unassigned BY INTENT, exactly like 0x10-0x16 + // below Blocks: C0/C1/C4 were chosen deliberately (C4 = the blast + // radius), not as consecutive free slots, so a later pass must not + // "tidy" a C-band domain downward into the hole. + assert_eq!(canonical_concept_domain(0xC200), ConceptDomain::Unassigned); + assert_eq!(canonical_concept_domain(0xC300), ConceptDomain::Unassigned); + // ...and the band's own edges: nothing leaks below C0 or above C4. + assert_eq!(canonical_concept_domain(0xBF00), ConceptDomain::Unassigned); + assert_eq!(canonical_concept_domain(0xC500), ConceptDomain::Unassigned); + // 0x0C Automation is NOT 0xC0 JavaRuntime — the two are a digit swap + // of each other, the one real legibility hazard in this allocation. + // Pinned so a transposition anywhere in the chain fails here first. + assert_eq!(canonical_concept_domain(0x0C01), ConceptDomain::Automation); + assert_eq!(canonical_concept_domain(0xC001), ConceptDomain::JavaRuntime); + // Trailing unassigned tail (0x18+, minus the C-band above). assert_eq!(canonical_concept_domain(0xFFFF), ConceptDomain::Unassigned); } diff --git a/docs/APP-CLASS-CODEBOOK-LAYOUT.md b/docs/APP-CLASS-CODEBOOK-LAYOUT.md index 23453a6..71eb88e 100644 --- a/docs/APP-CLASS-CODEBOOK-LAYOUT.md +++ b/docs/APP-CLASS-CODEBOOK-LAYOUT.md @@ -57,6 +57,40 @@ classid : u32 = [ hi u16 : in-codebook class ] [ lo u16 : APP / codebook name (`0x01` project, `0x02` commerce, `0x07` osint, `0x08` ocr, `0x09` health, `0x0A` anatomy, `0x0B` auth, `0x0C` automation). Within an app-private codebook the app owns its own `DD|CC` layout. + + **The domain byte carries ALTITUDE** (operator, 2026-08-18 — *"Java is an + entire different layer that's why I chose another higher level"*): a + slot's magnitude encodes how high the thing sits, so placement is neither + mnemonic nor next-free. `0x00`–`0x0F` is the canonical business/reference + ontology; `0x17` is the substrate's own orchestration tier (`ogar-loco`); + **`0xC0`+ is the C-band — strata ABOVE the Rust substrate**, foreign host + layers the substrate reaches into rather than owns: + + | slot | domain | why there | + |---|---|---| + | `0xC0` | `JavaRuntime` (Panama + Valhalla) | the managed-runtime membrane over the SoA substrate — the **floor** of the band | + | `0xC1` | `Analytics` | the analyst estate — addressable tabular units + catalog ontology (`ogar-bricks` and a lakehouse consumer are two app prefixes over ONE vocabulary) | + | `0xC4` | `BinaryLifting` | bolted onto `0xC0` (Ghidra is itself a JVM application), so a **tenant** of that layer rather than a peer; the slot number is the blast radius | + + All three are **reserved-empty** — zero concept rows, same posture as + `Osint` / `Genetics` / `Blocks` — so `canonical_concept_domain` returns a + stable tag before anything mints. `0xC2`–`0xC3` stay `Unassigned` **by + intent**, pinned by test, exactly as the `0x10`–`0x16` gap below `Blocks` + is: the slots were chosen deliberately, so a later pass must not tidy a + C-band domain downward into the hole. + + Structural note (why altitude is worth the space it takes): the domain + byte is the first two nibbles of the classid, so its **top nibble is a + 16-way altitude selector** — one mask separates "substrate ontology" from + "host layer" with no lookup and no value decode. That is §3.5's *the key + prerenders nodes with zero value decode*, applied to layering. A + first-nibble split is the most expensive split the 16-ary cascade has; + spending it on altitude is what makes it worth spending. + + Legibility hazard, recorded rather than rediscovered: **`0xC0` is a digit + swap of `0x0C` automation** (`0xC001_0000` vs `0x0C01_0000`). Raised, not + decisive, and pinned two-sided in `ogar-vocab`'s domain test so a + transposition anywhere in the chain fails there first. - **`lo u16` (0xAAAA) — APP prefix = codebook namespace selector.** Which 256⁶ semantic space / which centroid-codebook set the key resolves against (the longest-prefix codebook scoping already pinned diff --git a/docs/DISCOVERY-MAP.md b/docs/DISCOVERY-MAP.md index 206e2cb..43a2b85 100644 --- a/docs/DISCOVERY-MAP.md +++ b/docs/DISCOVERY-MAP.md @@ -1609,6 +1609,84 @@ isolation. The map's job is to keep them visible. (deliberately no compiler dep). Deferred, named: `DocOp` (editor authority), Lance-versioned `Revision(n)` lookup, `FieldView` enum widening. +- **[D-CBAND-ALTITUDE] the domain byte carries ALTITUDE — `0xC0`/`0xC1`/`0xC4` + reserved as the C-band, the strata ABOVE the Rust substrate** — `[G]` + (CODED, reserved-empty, 2026-08-18, operator ruling: *"Java is an entire + different layer that's why I chose another higher level"*) — home: + `ogar-vocab::ConceptDomain::{JavaRuntime, Analytics, BinaryLifting}` + + `canonical_concept_domain` (`0xC0`/`0xC1`/`0xC4` arms) — depends: + D-CLASSID-CANON-HIGH-FLIP, D-BLOCKS-DOMAIN (the reserved-empty + + pinned-gap posture this follows). + + **The ruling.** A domain slot's *magnitude* encodes how high the thing sits + in the stack; placement is neither mnemonic nor next-free. `0x00`–`0x0F` is + the canonical business/reference ontology, `0x17` is the substrate's own + orchestration tier (`ogar-loco`), and `0xC0`+ is the **C-band** — foreign + host layers the substrate reaches into rather than owns. Within the band: + **`0xC0` `JavaRuntime`** (Panama + Valhalla — the managed-runtime membrane, + and the FLOOR of the band, the door every other tenant arrives through); + **`0xC1` `Analytics`** (the analyst estate — addressable tabular units + + catalog ontology); **`0xC4` `BinaryLifting`** (bolted onto `0xC0`, since + Ghidra is itself a JVM application, so a *tenant* of that layer rather than + a peer of C0 — and the slot number is the blast radius of turning any binary + into addressable rows). All three carry ZERO concept rows. + + **Why altitude is worth its cost.** The domain byte is the first two nibbles + of the classid, so its top nibble is a 16-way altitude selector: one mask + separates "substrate ontology" from "host layer" with no lookup and no value + decode — `APP-CLASS-CODEBOOK-LAYOUT.md` §3.5's *the key prerenders nodes with + zero value decode*, applied to layering. A first-nibble split is the most + expensive split the 16-ary cascade has; spending it on altitude is what makes + it worth spending. + + **Three fences carried in the variant docs.** (1) *Naming*: each domain names + the shared CONCEPT, never a vendor or renderer — `ogar-bricks` and a + lakehouse consumer are two app prefixes over ONE `Analytics` vocabulary; + Ghidra and `r2sleigh` are two consumers of the same SLEIGH specs over ONE + `BinaryLifting` vocabulary (the D-BLOCKS-DOMAIN fence, reapplied). (2) + *Provenance*, load-bearing for `0xC4`: mints must derive from permissively- + licensed or specification sources (Ghidra core is Apache-2.0 — `opcodes.hh` + and the SLEIGH processor specs are usable; the `GPL/` subtree is not needed + for lifting), NEVER by transcribing a GPL/AGPL or LGPL implementation — so + the public codebook stays unencumbered while a GPL consumer links it freely + and the GPL boundary sits entirely in the consumer repo. (3) *No speculative + widening*: `0xC0` is deliberately `JavaRuntime` and not a vendor-neutral + `HostRuntime` — no second managed runtime is in scope, and another one would + get its own C-band slot rather than dilute this one. + + **`0xC2`–`0xC3` stay `Unassigned` BY INTENT**, pinned by test exactly as the + `0x10`–`0x16` gap below `Blocks` is: the slots were chosen deliberately (C4 = + the blast radius), not consecutively, so a later pass cannot "tidy" a C-band + domain downward into the hole. Two disable-runs confirm the guards are + load-bearing rather than decorative: dropping the `0xC4` arm turns the + `BinaryLifting` assertions red; minting into `0xC2` turns the gap assertion + red. Also pinned two-sided: **`0x0C` Automation is not `0xC0` JavaRuntime** — + a digit swap of each other, the one real legibility hazard in this + allocation, recorded rather than left to be rediscovered. + + **Storno — what this ruling corrects.** Three proposals made in the session + that produced it, all withdrawn, all the same error: seating P-code at + `0x1718` as an `ogar-loco` consumer slot (wrong tier — `0x17` is + lance-graph's *internal* orchestration: elixir-on-rails shaped, `rs-graph-llm` + as executor, Rig marking the replayability boundary between external LLM and + internal low-code — not a container for any palette whose ops fit in a byte); + putting P-code at `0x18` beside `Blocks` (same error, one slot over); and + proposing a separate substrate/layout-contract domain (not separate — it is + `0xC0`'s content). Root cause: clustering by **shape** (everything becomes + `(function : value)` calls in a 512-byte node) when the axis is **altitude**. + *Shape-similarity is not domain-identity.* What survives: **reuse + `ogar-loco`'s node shape, own your own domain** — loco's own doc says the + `FunctionBody` classid belongs at the substrate and a frontend references it + rather than minting its own. Borrowing the container is not joining the + domain. + + **First named consumer** (not built, not blocking): `lance-graph-java`'s W6 + schema/classid field on `LgjResourceInfo` / `LgjLaneDesc`, by which a native + resource names WHICH layout contract its bytes obey instead of implying it via + `kind` — a `0xC0` concept, the membrane naming itself from inside its own + stratum. Cross-ref: that repo's `.claude/board/EPIPHANIES.md` + `E-LGJ-THE-DOMAIN-BYTE-CARRIES-ALTITUDE-1`. + - **[D-BLOCKS-DOMAIN] `0x17XX` reserved as ConceptDomain::Blocks — the shared visual block-programming opcode vocabulary, ONE canon domain under two app prefixes** — `[G]` (CODED, reserved-empty, 2026-08-04, operator-chosen slot)