Skip to content

Commit fdcc862

Browse files
committed
docs(substrate): fix §8 ValueSchema framing — ClassView reading, not a new variant (Codex P2 #610)
Codex P2 + verified against canon: §8.1 and the SoA migration plan framed the homogeneous facet as a free additive ValueSchema::Homogeneous variant, which violates the #496 §0 anti-invention guardrail + #500 no-new-variant contract test (core-first-transcode-doctrine.md:72; genetics + OCR plans ride Full/ Compressed via classid → ClassView, never a new variant). - §8.1 reframed: the homogeneous facet is a classid → ClassView reading over an existing preset; ValueSchema enum + 16/16/480 layout both untouched. A new preset is an operator-lifted #496/#500 decision, never a thesis default. - migration plan §1/§3/§5: same correction; added the #500 guardrail as an explicit per-tenant gate; step 1 is now a ClassView reading, not a variant. - §8.3: softened 'no adapter, no serialization' — the per-port codebook lookup still mediates; only the bespoke A→B translation boundary disappears (CodeRabbit minor). - §8.1 fence given a 'text' language tag (markdownlint, CodeRabbit minor). - EPIPHANIES E-HOMOGENEOUS-FACET-IS-CLASSVIEW-NOT-VARIANT prepended. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CcpLeEC3XK8Eye53GKBVvi
1 parent 0a3fe05 commit fdcc862

3 files changed

Lines changed: 90 additions & 29 deletions

File tree

‎.claude/board/EPIPHANIES.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,39 @@ failure were caught and fixed without compounding drift.
2929

3030
**Closes:** the 11-class cross-axis gap. **Next:** odoo-rs alignment_pin
3131
tighten + pin bump to OGAR main (5089c1e8 → 597ecb12 family).
32+
## 2026-06-24 — E-HOMOGENEOUS-FACET-IS-CLASSVIEW-NOT-VARIANT — the §8 homogeneous facet is a `classid → ClassView` reading, NEVER a new `ValueSchema` enum variant
33+
34+
**Status:** FINDING (caught by Codex P2 on PR #610, verified against canon).
35+
36+
The thesis §8.1 + the SoA value-tenant migration plan v1 originally framed the
37+
homogeneous-facet value as a *new additive* `ValueSchema::Homogeneous` variant
38+
"alongside" the existing tenants, sold as layout-preserving + no-version-bump.
39+
**That contradicts a locked guardrail.** Adding a `ValueSchema` enum case is a
40+
*contract-surface* addition even when the byte layout is untouched, and the
41+
canon forbids a plan/thesis from minting one:
42+
43+
- `core-first-transcode-doctrine.md:72` — "`classid → ClassView` … **No new
44+
layer, no new `ValueSchema` variant.**"
45+
- `genetic-research-substrate-integration-v1.md:14-16` — the #496 §0
46+
anti-invention guardrail + the **#500 no-new-variant contract test**:
47+
rows ride `Full` / `Compressed`; specialisation is via `classid → ClassView`
48+
mint, not a variant.
49+
- `ocr-canonical-soa-integration-v1.md:93-102` — "do **NOT** add a 5th
50+
`ValueSchema::Ocr` … the rule that holds is **no new enum variant from a
51+
plan**."
52+
53+
**Corrected framing (both docs fixed in the same PR):** the homogeneous facet is
54+
a **ClassView reading that interprets the value bytes of an existing preset** —
55+
the `ValueSchema` enum AND the 16/16/480 layout both stay untouched, no
56+
`ENVELOPE_LAYOUT_VERSION` bump, no #500 violation. IF a dedicated preset is ever
57+
judged necessary, that is an **operator decision lifting #496/#500** with the
58+
contract test updated in the same change — never a free additive a thesis
59+
assumes. **Lesson:** "layout-preserving" ≠ "contract-surface-preserving"; an
60+
enum-variant add is the latter even when the bytes don't move. The default for
61+
any new value shape is a ClassView reading over `Full`/`Compressed`, not a new
62+
`ValueSchema` case. (Same PR also softened the §8.3 "no adapter" claim — the
63+
per-port codebook lookup still mediates; only the bespoke A→B *translation*
64+
boundary disappears — and tagged a bare markdown fence per CodeRabbit.)
3265

3366
## 2026-06-23 — E-OGAR-API-EDIT-PULL-FIRST — API-based file edits MUST pull-then-splice; uploading pre-edited local files regresses upstream main
3467

‎.claude/knowledge/substrate-unification-thesis.md‎

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -191,23 +191,34 @@ it is graded `[H]` where it reuses shipped structure and `[S]` where it bets on
191191
unbuilt tooling. **Nothing here is canon yet** — it is the north-star's far end,
192192
written down so the rungs point somewhere.
193193

194-
### 8.1 The homogeneous facet `[H]` — layout-preserving, not layout-breaking
194+
### 8.1 The homogeneous facet `[H]` — a ClassView reading, NOT a new contract variant
195195

196196
Carve the 480-byte value as **N × 16-byte facets**, each facet itself a
197197
`(part_of:is_a)` cascade in the §2-Structure algebra:
198198

199-
```
199+
```text
200200
facet (16 B) = facet_classid(4) | 6 × (8:8 part_of:is_a tile, 2 B each = 12)
201-
value (480 B) = up to 30 homogeneous facets ← ValueSchema::Homogeneous
201+
value (480 B) = up to 30 homogeneous facets ← read by classid → ClassView
202202
```
203203

204-
The key insight is **compatibility, not replacement**: this is a new
205-
`ValueSchema::Homogeneous` variant *alongside* the existing `ValueTenant` SoA
206-
columns — the 16/16/480 split (`canonical_node.rs`) is **untouched**, so it is
207-
layout-preserving and needs no `ENVELOPE_LAYOUT_VERSION` bump (contrast a *key*
208-
re-carve, which is canon-level and separate). The value's facets are read by
209-
the *same* prefix-and-table arithmetic as the path tiers (§2), so "read the
210-
value" becomes the same operation as "route the key."
204+
**Guardrail (do not misread this as a free additive).** The canon forbids a
205+
plan or thesis from minting a `ValueSchema` enum variant: the #496 §0
206+
anti-invention guardrail + the **#500 no-new-variant contract test**, and
207+
`core-first-transcode-doctrine.md` ("`classid → ClassView` … **no new layer,
208+
no new `ValueSchema` variant**"). The genetics and OCR plans both ride the
209+
existing `Full` / `Compressed` presets and specialise via `classid → ClassView`
210+
mint — *not* a new variant. So the homogeneous facet is **a ClassView reading
211+
that interprets the value bytes of an existing preset**, never a
212+
`ValueSchema::Homogeneous` enum case. Both the 16/16/480 layout
213+
(`canonical_node.rs`) **and** the `ValueSchema` enum stay untouched; no
214+
`ENVELOPE_LAYOUT_VERSION` bump, no contract-surface addition. The value's
215+
facets are read by the *same* prefix-and-table arithmetic as the path tiers
216+
(§2), so "read the value" becomes the same operation as "route the key."
217+
218+
**If** a dedicated variant is ever judged necessary (a leaner homogeneous
219+
preset the existing ones can't express), that is an explicit **operator
220+
decision lifting the #496/#500 guardrail** — with the contract test updated in
221+
the same change — never an additive a thesis assumes for free.
211222

212223
**The conflation trap, named up front (`[H]` gate):** not every facet is a
213224
`part_of:is_a` mereology/taxonomy pair. Scalars (a susceptance, a price, a
@@ -246,10 +257,11 @@ GATED` in spirit: same prefix, two semantics, must never silently diverge).
246257
### 8.3 LEGO across domains `[S]` — EdgeBlock click via shared codebook
247258

248259
If two programs (an ERP, a OCR pipeline) mint nodes against the *same* OGAR
249-
concept codebook, their `EdgeBlock` slots are **directly clickable**: an
250-
out-of-family edge from domain A's node resolves, by `canonical_concept_id`,
251-
into domain B's node — no adapter, no serialization, because both speak the one
252-
codebook. "Compile on OGAR classes and do LEGO with class shapes" becomes:
260+
concept codebook, their `EdgeBlock` slots are **conceptually clickable through
261+
the shared codebook**: an out-of-family edge from domain A's node resolves, by
262+
`canonical_concept_id`, into domain B's node — the per-port codebook lookup
263+
still mediates, but the extra *translation* boundary (a bespoke A→B adapter, a
264+
serialization hop) disappears, because both already speak the one codebook. "Compile on OGAR classes and do LEGO with class shapes" becomes:
253265
**compile = SPO manifest → ClassView**; **run = SoA under `UnifiedStep` /
254266
semiring** (§2-Composition). `[S]` — this is the OGAR core-first doctrine's
255267
end state, explicitly CONJECTURE until `PROBE-OGAR-ADAPTER-UNICHARSET` is green.

‎.claude/plans/soa-value-tenant-migration-v1.md‎

Lines changed: 31 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -43,11 +43,14 @@ The canonical node is `key(16) | edges(16) | value(480)` = 512 B
4343
(`canonical_node.rs`, operator-LOCKED, RESERVE-DON'T-RECLAIM). A **value
4444
tenant** is a typed claim on some of those 480 value bytes — the `ValueSchema`
4545
says how the slab is carved, a `ValueTenant` is one carve. The §8 strong form
46-
(`substrate-unification-thesis.md`) proposes an *additive* `ValueSchema::
47-
Homogeneous` (N × 16-byte `(part_of:is_a)` facets) **alongside** the existing
48-
tenants. The migration question for each existing tenant is therefore:
49-
**KEEP as-is / homogenize to a facet / PQ-code it / deprecate** — and whether
50-
that move is layout-preserving.
46+
(`substrate-unification-thesis.md`) reads the homogeneous facet as a
47+
`classid → ClassView` *interpretation over an existing preset* (`Full` /
48+
`Compressed`) — **not** a new `ValueSchema` enum variant (the #496 §0
49+
anti-invention guardrail + the #500 no-new-variant contract test forbid a plan
50+
from minting one; see §3). The migration question for each existing tenant is
51+
therefore: **KEEP as-is / homogenize via a ClassView facet reading / PQ-code it
52+
/ deprecate** — and whether that move stays within the existing presets or
53+
requires an operator-lifted guardrail.
5154

5255
---
5356

@@ -106,12 +109,21 @@ The harvest must Read, fully, in this order:
106109
For each tenant the harvest touches, hold these in mind — they are the
107110
acceptance criteria the §6 panels will check:
108111

109-
- **Layout class.** Is the proposed move *layout-preserving* (a new
110-
`ValueSchema` variant alongside; offsets unchanged) or *layout-breaking* (the
111-
480 bytes re-carved)? Breaking ⇒ canon-level ⇒ needs `ENVELOPE_LAYOUT_VERSION`
112-
bump **and** the operator's nod. The 16/16/480 split and the `const _` asserts
113-
do not move without that. (RESERVE-DON'T-RECLAIM: a zeroed/unused region is
114-
*not consulted*, never *compacted away*.)
112+
- **Contract-surface class (the #500 guardrail).** A plan may **NOT** mint a
113+
`ValueSchema` enum variant — that is a contract-surface addition against the
114+
#496 §0 anti-invention guardrail, enforced by the **#500 no-new-variant
115+
contract test** (`core-first-transcode-doctrine.md`: "`classid → ClassView`
116+
… no new `ValueSchema` variant"; the genetics + OCR plans both ride `Full` /
117+
`Compressed` and specialise via `classid → ClassView` mint). So the default
118+
move is a **ClassView reading over an existing preset**, offsets and enum both
119+
unchanged. A genuinely new preset is an **operator decision lifting #496/#500**
120+
(with the contract test updated in the same change), never a plan default.
121+
- **Layout class.** Even within the existing enum, is the byte carve
122+
*preserving* (offsets unchanged) or *breaking* (the 480 bytes re-carved)?
123+
Breaking ⇒ canon-level ⇒ needs `ENVELOPE_LAYOUT_VERSION` bump **and** the
124+
operator's nod. The 16/16/480 split and the `const _` asserts do not move
125+
without that. (RESERVE-DON'T-RECLAIM: a zeroed/unused region is *not
126+
consulted*, never *compacted away*.)
115127
- **`I-LEGACY-API-FEATURE-GATED`.** The same accessor name must never mean two
116128
things under two feature flags. Any v1 accessor over bytes a v2 layout
117129
reclaims ⇒ route through the canonical mapping OR feature-gate to a documented
@@ -168,10 +180,14 @@ hidden. Silent truncation reads as "covered everything" when it didn't.
168180

169181
Direction, fixed; specifics, deferred to the filled inventory:
170182

171-
1. **Additive contract first.** Land `ValueSchema::Homogeneous` + a
172-
`FacetCascade` type (`facet_classid(4) | 6×(8:8)=12` = 16 B) as a *new
173-
variant alongside* `ValueTenant` — layout-preserving, no version bump. Behind
174-
a feature flag. Field-isolation matrix tests from day one.
183+
1. **ClassView reading first (no new contract variant).** Land the
184+
`FacetCascade` *reading* (`facet_classid(4) | 6×(8:8)=12` = 16 B) as a
185+
`classid → ClassView` interpretation over an existing preset (`Full` /
186+
`Compressed`) — the `ValueSchema` enum and the 16/16/480 layout both
187+
untouched, no version bump, no #500 violation. Behind a feature flag.
188+
Field-isolation matrix tests from day one. (A dedicated `ValueSchema` preset
189+
is out of scope for this plan — it is an operator-lifted #496/#500 decision,
190+
filed separately if the existing presets prove insufficient.)
175191
2. **Per-tenant, in migration_class order:**
176192
- `homogenize-to-facet` tenants (those that already ARE `part_of:is_a`) move
177193
first — lowest risk, prototype is `cascade_key` V3.

0 commit comments

Comments
 (0)