Skip to content

Commit 153246f

Browse files
claudeclaude
committed
docs: add DISCOVERY-MAP — the shape-preserving index of every discovery
Per operator request: "map all discoveries and ideas out so that they don't dilute shape once materialized in architecture." The anti-dilution thesis: shape dilutes from FRAGMENTATION, not from too few documents — each idea pinned in isolation loses its links, and a future reader sees N disconnected ADRs instead of one doctrine. This map is the one place the topology lives. Terse by discipline (pointers + structure + status, never re-explanation); append-only + status-tracked, mirroring the substrate's own versioned-audit shape (ADR-008/013). Structure: §1 doctrine spine — ADR-022/023/024/025 (+ 026 pending) + the one- sentence gestalt the individual ADRs lose §2 the discovery ledger — ~40 D-* entries across 9 areas, each: [ID] shape — grade (G/H/S) — status (IDEA/EPIPHANY/ADR/CODED) — home — depends. Covers addressing/cascade, selection/bounds, codec/codebooks, no-collapse precondition, amortization gate, storage, synergy catalog, the coded IR+adapters, domain instances. §3 materialization pipeline — what's READY to materialize now (G + EPIPHANY, no runtime gate -> draft ADR-026), what's BLOCKED on runtime confirmation, what's CODED, what's queued, what's do-not-build (OLED [S]). §4 the OGAR/runtime boundary — owned-vs-[per rt]; the five open ADR-026 confirmations; the two operator-closed items. §5 the shape graph — the ASCII topology the individual ADRs lose. §6 maintenance discipline — append-only, terse, grade-honest, index- not-content; the map mirrors the substrate (recursive = the tell the shape is intact). §7 cross-references. Status column makes the materialization state of every idea visible at a glance, so when ADR-026 (or future ADRs/crates) pin a subset, the rest stay tracked and linked instead of forgotten. The map is the durable shape; the ADRs/crates/synergy-doc are the content it indexes. Docs-only. PII abort-guard (word-boundary): CLEAN. cargo check: clean. https://claude.ai/code/session_01PBTGaPCSnnt6u3pjXpbLwY
1 parent 23cbb70 commit 153246f

1 file changed

Lines changed: 268 additions & 0 deletions

File tree

‎docs/DISCOVERY-MAP.md‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
# Discovery Map — the shape‑preserving index
2+
3+
> **Purpose.** A single append‑only index of every discovery, idea, and
4+
> decision in the substrate arc — each with its **grade**, **materialization
5+
> status**, **home**, and **dependencies** — so the *shape* (the connections
6+
> between ideas) survives when ideas materialize into individual ADRs and
7+
> crates.
8+
>
9+
> **The anti‑dilution thesis.** Shape dilutes not from too few documents but
10+
> from **fragmentation**: each idea pinned in isolation loses its links, and
11+
> a future reader sees N disconnected ADRs instead of one doctrine. This map
12+
> is the one place the **topology** lives. It is **terse by discipline** —
13+
> pointers + structure + status, never re‑explanation. The ADRs / crates /
14+
> docs are the *content*; this is the *index*. It is **append‑only +
15+
> status‑tracked**, mirroring the substrate's own versioned‑audit shape
16+
> (ADR‑008/013) — fitting, since a map of an append‑only audited substrate
17+
> should itself be append‑only audited.
18+
>
19+
> **How to read an entry:** `[ID] one‑line shape — grade — status — home —
20+
> depends`.
21+
> - **Grade:** `[G]` Grounded (real artifact/spec) · `[H]` Hypothesis
22+
> (sound, one side unconfirmed) · `[S]` Speculative (catalog only).
23+
> - **Status (materialization pipeline):** `IDEA` → `EPIPHANY` (graded,
24+
> captured in a synergy/epiphany doc) → `ADR` (pinned contract) → `CODED`
25+
> (crate + tests + CI).
26+
> - **`[per runtime session]`** = runtime‑owned; OGAR cannot verify.
27+
>
28+
> **Status: LIVING INDEX** (2026‑06‑08). Update entry *status* on
29+
> materialization; never delete (append‑only). One entry per discovery;
30+
> cross‑link, do not duplicate.
31+
32+
---
33+
34+
## 1. The doctrine spine — the load‑bearing floors
35+
36+
The ADR canon is the spine; every discovery in §2 hangs off the floor it
37+
specializes.
38+
39+
| ADR | Floor | Status | Home |
40+
|---|---|---|---|
41+
| **022** | **boundary** — no serialization in the hot path | `ADR` | `THE-FIREWALL.md` |
42+
| **023** | **IR** — `Class` is wire truth; dialects absorbed by adapters | `ADR` | `ARCH-DECISIONS` + `ogar-vocab/` |
43+
| **024** | **codec** — palette256 + HHTL; 1‑byte index, sub‑µs decode, ρ ≥ 0.99 | `ADR` | `ARCH-DECISIONS` |
44+
| **025** | **selection** — probe‑free closed‑form level (`r* = ⌈log₄(C/τ)⌉`) | `ADR` | `ARCH-DECISIONS` |
45+
| **026** | **(pending)** cascade + amortization gate + meta→content gradient + no‑collapse precondition + storage | `EPIPHANY → ADR` | `CASCADE-SYNERGIES-EPIPHANY.md` |
46+
47+
**The gestalt the spine forms (the one sentence the individual ADRs lose):**
48+
49+
> *The substrate is an **immaterialized Morton cascade with templated
50+
> payloads** — address is geometry (helix + HHTL), error is closed‑form
51+
> (jc), the codec is exact in the θ‑window, materialization is lazy and
52+
> columnar; the **only forbidden cost is non‑amortized per‑query.***
53+
54+
ADR‑022 (the boundary) + ADR‑025 (the probe) are both special cases of that
55+
last clause. ADR‑023 (address vs payload) + ADR‑024 (the codec) describe the
56+
two halves of a cell. ADR‑026 names the cascade that ties them.
57+
58+
---
59+
60+
## 2. The discovery ledger
61+
62+
### 2.1 Addressing & cascade
63+
64+
| ID | Shape | Grade | Status | Home | Deps |
65+
|---|---|:--:|:--:|---|---|
66+
| D‑MORTON | NiblePath nibble = one 4×4 Morton tile (2 x‑bits + 2 y‑bits interleaved) | G | EPIPHANY | SYN §0,§7.5 | 023,024 |
67+
| D‑XOR2 | one address‑XOR, two reductions: **popcount = perms** (024) / **CLZ = containment** (025) | G | EPIPHANY | SYN §0 | 024,025 |
68+
| D‑CASCADE | 64→256→1024→4096→16k→64k→256k = immaterialized Morton enumeration; every level = +1 nibble | G | EPIPHANY | SYN §7.5 | D‑MORTON |
69+
| D‑IMMAT | the cascade is a **coordinate transform, not a stored grid** (`(lat,lon)→quadkey` cheap) | G | EPIPHANY | SYN §7.5 | D‑CASCADE |
70+
| D‑NEIGH | neighbor‑XOR walk + parent‑prefix = structured‑sparse stencil (block‑banded, not sparse GEMM) | H | EPIPHANY | SYN §6 | D‑MORTON, `[per rt]` blasgraph |
71+
72+
### 2.2 Selection & bounds
73+
74+
| ID | Shape | Grade | Status | Home | Deps |
75+
|---|---|:--:|:--:|---|---|
76+
| D‑PROBEFREE | hot path takes zero data‑dependent branches; level is closed‑form | G | ADR | ADR‑025 | 022 |
77+
| D‑RSTAR | `r* = ⌈2·log_b(C/τ)⌉`; `b=16` ⟹ `⌈log₄(C/τ)⌉`; inclusive `≤ τ` | G | ADR | ADR‑025 (#45,#46) | D‑CASCADE |
78+
| D‑BOUNDS | tile `bounding_volume` is **derived** (address arithmetic), not stored | H | ADR | ADR‑025 | D‑MORTON, `[per rt]` helix |
79+
| D‑CESIUM‑PROBE | native Cesium SSE refine/collapse = the trial‑and‑error probe 025 removes | G | EPIPHANY | SYN §1 | D‑PROBEFREE |
80+
81+
### 2.3 Codec & codebooks
82+
83+
| ID | Shape | Grade | Status | Home | Deps |
84+
|---|---|:--:|:--:|---|---|
85+
| D‑PAL256 | palette256 = one PQ subspace's 256 centroids (CAM = 6×256, PR #477) | G | ADR | ADR‑024 | — |
86+
| D‑CAM | CAM‑PQ = 6 roles × 256 = 48‑bit fingerprint per word (`cam_codes.bin`) | G | EPIPHANY | SYN §3 | D‑PAL256 |
87+
| D‑CARD | cascade per‑axis cardinality ↔ codebook size: 256↔palette, 4096↔`MAX_VOCAB` | G | EPIPHANY | SYN §3,§7 | D‑CASCADE, D‑CAM |
88+
| D‑META64 | `CausalEdge64` = meta: `2⁶` role‑mask **+** 48‑bit CAM + 16‑bit headroom, one 64‑bit word | H | EPIPHANY | SYN §9.6 | D‑CAM, `[per rt]` CausalEdge64 |
89+
| D‑BITGATE | 48→64 headroom: store the seed **iff** irreducible‑beyond‑the‑address (else compute) | H | EPIPHANY | SYN §9.6 | D‑META64, D‑AMORT |
90+
| D‑RHO | ρ = 0.9973 vs cosine (arm‑discovery aerial codebook) — the empirical anchor | G | ADR | ADR‑024 | D‑PAL256 |
91+
92+
### 2.4 No‑collapse precondition (θ + golden)
93+
94+
| ID | Shape | Grade | Status | Home | Deps |
95+
|---|---|:--:|:--:|---|---|
96+
| D‑THETA | θ ∈ [1.45,1.6] (near‑orthogonal, cosθ∈[−0.03,0.12]) = the conditioning window | H | EPIPHANY | SYN §2; ADR‑025 ref | D‑PAL256, `[per rt]` jc |
97+
| D‑RHOENV | ρ ∈ [0.93 (band edge) .. 0.9973 (θ≈π/2)] = exactness envelope over θ | H | EPIPHANY | SYN §2 | D‑THETA, D‑RHO |
98+
| D‑GOLDEN | golden‑stride helix placement controls θ into the window **by construction** | H | EPIPHANY | SYN §2 | `[per rt]` helix |
99+
| D‑MOIRE | golden irrationality = X‑Trans‑grade anti‑moiré interlace ("x256 that can't collapse") | H | EPIPHANY | SYN §2 | D‑GOLDEN |
100+
| D‑NOCOLLAPSE | unify: near‑orthogonal **codebook** + aperiodic **lattice** = no degenerate beat in value‑ or position‑space | H | EPIPHANY → ADR‑026 §2 | SYN §9.1 | D‑THETA, D‑MOIRE |
101+
102+
### 2.5 Amortization gate
103+
104+
| ID | Shape | Grade | Status | Home | Deps |
105+
|---|---|:--:|:--:|---|---|
106+
| D‑AMORT | admission test = **amortize‑or‑don't‑spend** (not "free"); unifies 022 + 025 | G | EPIPHANY → ADR‑026 §3 | SYN §7 | 022,025 |
107+
| D‑AMORT‑AXES | two reuse axes: **mipmap cascade** (spatial) / **Semantik volumetric centroid** (semantic) | G | EPIPHANY | SYN §7 | D‑AMORT |
108+
| D‑BOTHCASC | store **both** freq + semantic cascades (SoA headroom affords it); "pick one axis" fork dissolved | G | EPIPHANY | SYN §7 | D‑AMORT‑AXES |
109+
| D‑FRACTAL | the gate is fractal: **storage** (§7.5) / **cascade** (§7) / **bit** (§9.6) — one rule, three scales | G | EPIPHANY | SYN §7 | D‑AMORT, D‑BITGATE |
110+
| D‑MAXAMORT | enrich the **coarse/meta** levels lavishly (amortize over everything below); be frugal only at the per‑query leaf | H | EPIPHANY | SYN §9 | D‑AMORT, D‑META64 |
111+
112+
### 2.6 Storage
113+
114+
| ID | Shape | Grade | Status | Home | Deps |
115+
|---|---|:--:|:--:|---|---|
116+
| D‑COLUMNAR | Morton‑keyed columnar rows + prefix pushdown = tile fetch (Delta `ZORDER`/Iceberg/BigQuery — deployed) | G | EPIPHANY | SYN §7.5 | D‑IMMAT |
117+
| D‑LANCE | "parquet‑shaped" = the columnar family; **Lance** is the instance (random tile access > Parquet row‑group scan) | G | EPIPHANY | SYN §7.5 | D‑COLUMNAR |
118+
| D‑PYRAMID | the unifying shape: columnar (parquet) + Morton rows (grid) + level cascade (pyramid) + closed‑form cell (shader) | H | EPIPHANY | SYN §7.5 | D‑COLUMNAR, D‑CASCADE |
119+
| D‑DELTA | delta frames = version‑diff = changed Morton cells = codec P‑frame (I/P map; B does not, append‑only log) | H | EPIPHANY | SYN §7.5,§1 | D‑LANCE |
120+
121+
### 2.7 Cross‑domain synergy catalog
122+
123+
| ID | Shape | Grade | Status | Home | Deps |
124+
|---|---|:--:|:--:|---|---|
125+
| D‑CTU | Morton cascade = x265/x266 CTU quadtree; codec RDO split = the probe | G | EPIPHANY | SYN §1 | D‑CASCADE, D‑CESIUM‑PROBE |
126+
| D‑ATTN | attention (bgz‑tensor WeightPalette 256) ranks tiles → drives `r*`; τ = min(certificate, attention) | H | EPIPHANY | SYN §4 | D‑RSTAR, D‑PAL256 |
127+
| D‑CONVERGE | 6 lineages (codecs/sensors/displays/attention/PQ/Cesium) → quadtree + 256‑palette + irrational | G | EPIPHANY | SYN §0 | — |
128+
| D‑OLED | OLED exciton ↔ substrate = weakest leg; only candidate diffusion‑length ↔ neighborhood; **do not build on** | S | EPIPHANY | SYN §3 | — |
129+
130+
### 2.8 IR & adapters — the coded layer
131+
132+
| ID | Shape | Grade | Status | Home | Deps |
133+
|---|---|:--:|:--:|---|---|
134+
| D‑VOCAB | `Class`/`Attribute`/`Association`/`EnumDecl`/`ActionDef`/`KausalSpec`/`Identity` IR | G | CODED | `ogar-vocab/` | 023 |
135+
| D‑IDENT | `class_identity(prefix,name)` = NiblePath; canonical‑form invariant | G | CODED | `ogar-ontology/` (#31) | D‑VOCAB |
136+
| D‑EMIT | `TripleEmitter` — 129 RDF predicates; SPO + TeKaMoLo | G | CODED | `ogar-emitter/` | D‑VOCAB |
137+
| D‑SURREALQL | SurrealQL DDL adapter, parse+emit, round‑trip, identifier‑quoted | G | CODED | `ogar-adapter-surrealql/` (#32,#36) | D‑VOCAB |
138+
| D‑TTL | Turtle (RDF/OWL) adapter, parse+emit, round‑trip | G | CODED | `ogar-adapter-ttl/` (#37) | D‑EMIT |
139+
| D‑CHDDL | ClickHouse DDL adapter, parse+emit, dotted‑name round‑trip | G | CODED | `ogar-adapter-clickhouse-ddl/` (#38,#40) | D‑VOCAB |
140+
| D‑KNOWABLE | `KnowableFromStore` + `register_class_knowable_from`; `surrealql-hint`; **`vart-backend`** | G | CODED | `ogar-knowable-from/` (#25,#33,#43) | D‑IDENT |
141+
| D‑HINT | `schema_ddl_hint` loop closed — self‑describing registry via emit | G | CODED | (#33) | D‑SURREALQL, D‑KNOWABLE |
142+
| D‑ELIXIR | Elixir/HIRO SchemaSource scaffold (`gen_statem`→Rubicon) | G | CODED (scaffold) | `ogar-from-elixir/` | D‑VOCAB |
143+
| D‑OSM | `ogar-from-osm-pbf` — Node/Way/Relation; quadkey NiblePath from resolved geometry | H | IDEA | (queued) | D‑VOCAB, `[per rt]` D‑OSM‑3 |
144+
| D‑PATTERN | `ogar-pattern` — recognition library + confidence (FMA‑D/FIBO/SKR/PROV‑O) | H | IDEA | (queued) | D‑TTL |
145+
| D‑ACTION | `ogar-actionable` — lifecycle → `ActionDef`/`KausalSpec` | H | IDEA | (queued) | D‑PATTERN |
146+
| D‑NSM | 4096‑dim Deep‑NSM encoder (Wierzbicka primes, `NUM_PRIMES=63`) calibration | H | IDEA | RDF‑OWL §4.10 | D‑CAM, `[per rt]` |
147+
148+
### 2.9 Domain instances (universality witnesses)
149+
150+
| ID | Shape | Grade | Status | Home |
151+
|---|---|:--:|:--:|---|
152+
| D‑DOM | 6 instances: chess / OpenProject / Elixir‑HIRO / Odoo‑ERP / HIPAA / OSM | G | ADR/doc | `DOMAIN-INSTANCES.md` (#27,#41,#42) |
153+
| D‑PII | label‑free contract IS the PII guarantee (HHTL leaf‑rename at Adapter) | G | doc | `HEALTHCARE-TRANSCODING.md §4` |
154+
| D‑LITMUS‑FMA | FMA bones‑rendering = compile‑time HHTL litmus (~75K static classes) | H | doc | `RDF-OWL-ALIGNMENT.md §6` |
155+
| D‑LITMUS‑GEO | OSM = geographic litmus; "Femur is_a LongBone AND Marienplatz is_in Munich" sub‑µs | H | doc | `DOMAIN-INSTANCES.md §2.6` |
156+
157+
---
158+
159+
## 3. The materialization pipeline — what's ready, what's blocked
160+
161+
```
162+
IDEA ──→ EPIPHANY ──→ ADR ──→ CODED
163+
(floated) (graded) (pinned) (crate+CI)
164+
```
165+
166+
**Ready to materialize now** (`G` + `EPIPHANY`, no runtime gate) → **draft
167+
ADR‑026**:
168+
- D‑AMORT, D‑AMORT‑AXES, D‑BOTHCASC, D‑FRACTAL (the amortization gate)
169+
- D‑MORTON, D‑XOR2, D‑CASCADE, D‑IMMAT (the addressing)
170+
- D‑COLUMNAR, D‑LANCE (the storage layer — almost entirely `[G]`)
171+
- D‑CTU, D‑CONVERGE (the grounded synergies)
172+
173+
**Blocked on runtime confirmation** (`H` + `[per runtime session]`) → ADR‑026
174+
lands these with `[per rt]` marks, receipts fill later:
175+
- D‑GOLDEN, D‑MOIRE, D‑THETA, D‑RHOENV (helix spacing + θ/ρ envelope — `jc`/`helix`)
176+
- D‑BOUNDS, D‑META64, D‑BITGATE (helix bounds + `CausalEdge64` layout)
177+
- D‑NEIGH (`blasgraph` scope)
178+
179+
**Coded, done** — §2.8 D‑VOCAB…D‑KNOWABLE (+ vart‑backend), the adapters.
180+
181+
**Queued code** (`IDEA`, gated): D‑OSM (runtime D‑OSM‑3), D‑PATTERN,
182+
D‑ACTION, D‑NSM.
183+
184+
**Do‑not‑build** (`S`): D‑OLED — catalog only.
185+
186+
---
187+
188+
## 4. The OGAR / runtime boundary
189+
190+
OGAR owns + verifies the **left**; the **right** is `[per runtime session]`
191+
(cited as authoritative under the same discipline as ADR‑024's ρ anchor).
192+
193+
| OGAR‑owned (verified) | Runtime‑owned `[per rt]` |
194+
|---|---|
195+
| `ogar-vocab` IR; all adapters; `ogar-knowable-from` + vart‑backend | `crates/helix` (placement template, golden stride) |
196+
| Morton/XOR/CLZ address algebra (D‑MORTON, D‑XOR2) | `crates/jc` (`weyl` + `jirak`; θ/ρ envelope) |
197+
| the amortization gate (D‑AMORT, fractal) | `cognitive-shader-driver` (the consumer) |
198+
| the storage framing (D‑COLUMNAR, D‑LANCE) | `blasgraph` scope (D‑NEIGH) |
199+
| ADR‑022/023/024/025 + the ADR‑026 spine | `CausalEdge64` layout (D‑META64); SoA headroom budget |
200+
201+
**The five open ADR‑026 confirmations** (`CASCADE-SYNERGIES-EPIPHANY.md
202+
§10`): helix spacing · θ‑window/ρ envelope · `blasgraph` scope ·
203+
shader tile‑contract · SoA headroom budget. (`CausalEdge64` cardinality
204+
+ the nesting‑axis fork are **closed** — operator‑resolved.)
205+
206+
---
207+
208+
## 5. The shape graph — the topology individual ADRs lose
209+
210+
```
211+
ADR-022 boundary
212+
│ (special case of)
213+
ADR-023 IR ───────────┼─────────── ADR-024 codec
214+
(address) │ (palette256/CAM)
215+
│ │ │
216+
D-MORTON D-AMORT D-PAL256 ── D-RHO
217+
D-XOR2 ───┐ (amortize gate) │ (ρ=0.9973)
218+
│ │ │ (unifies │
219+
D-CASCADE │ 022+025) D-THETA ── D-RHOENV
220+
│ │ │ │ (no-collapse)
221+
D-IMMAT │ D-FRACTAL D-GOLDEN ─ D-MOIRE
222+
│ │ (storage/cascade/bit) │ (X-Trans/φ)
223+
D-COLUMNAR│ │ D-NOCOLLAPSE
224+
D-LANCE │ │ │
225+
└─────┴───── ADR-025 selection ──────┘
226+
(probe-free r*)
227+
│
228+
ADR-026 (pending)
229+
= cascade + gate + meta→content + no-collapse + storage
230+
│
231+
┌───────────────┼───────────────┐
232+
D-CTU D-ATTN D-DELTA
233+
(x265/x266) (attn-driven LOD) (version=P-frame)
234+
```
235+
236+
The arrows are the links that vanish when you read ADR‑022..025 in
237+
isolation. The map's job is to keep them visible.
238+
239+
---
240+
241+
## 6. Maintenance discipline
242+
243+
1. **Append‑only.** New discovery → new `D‑*` entry. Never delete; on
244+
materialization, advance the *status* column (IDEA→EPIPHANY→ADR→CODED).
245+
2. **Terse.** One line per entry. The shape, not the explanation. Link to
246+
the home doc; do not duplicate its content here.
247+
3. **Grade honestly.** `[S]` stays `[S]` until a measurement promotes it.
248+
`[per runtime session]` until the runtime session confirms.
249+
4. **This is the index.** The doctrine (ADRs), the synergies
250+
(`CASCADE-SYNERGIES-EPIPHANY.md`), the IR (crates) are the content. The
251+
map points; it does not re‑derive.
252+
5. **The map mirrors the substrate.** Append‑only + status‑versioned, like
253+
the audit log it documents (ADR‑008/013). If that feels recursive, it
254+
is — and that's the tell that the shape is intact.
255+
256+
---
257+
258+
## 7. Cross‑references
259+
260+
- `docs/ARCHITECTURAL-DECISIONS-2026-06-04.md` — ADR‑022..025 (+ 026 pending).
261+
- `docs/CASCADE-SYNERGIES-EPIPHANY.md` — the synergy catalog + amortization
262+
gate + storage synthesis (the source of most §2 `EPIPHANY` entries).
263+
- `docs/RDF-OWL-ALIGNMENT.md` — the brutal‑upgrade sequencing (§10 phases)
264+
+ Deep‑NSM (§4.10).
265+
- `docs/DOMAIN-INSTANCES.md` — the 6 universality witnesses.
266+
- `docs/THE-FIREWALL.md`, `HEALTHCARE-TRANSCODING.md` — ADR‑022 + PII floor.
267+
- lance‑graph PR #470/#473/#474/#475/#476/#477/#478, bardioc #17/#18/#19 —
268+
the runtime‑side receipts (`[per runtime session]` sources).

0 commit comments

Comments
 (0)