Skip to content

CLAUDE.md

Latest commit

 

History

History
316 lines (289 loc) · 19.4 KB

CLAUDE.md

File metadata and controls

316 lines (289 loc) · 19.4 KB
Raw

CLAUDE.md — OGAR (Open Graph of Active Record)

Auto-loaded session preamble. The canon pins live here; the detail lives in docs/. Read docs/DISCOVERY-MAP.md (what was found) and docs/INTEGRATION-MAP.md (how it composes) before proposing anything.

P0 — THE CANONICAL GUID (operator-pinned; counted in HEX, not bits)

⊘ SUPERSEDED — MIGRATION MANDATORY (operator, 2026-07-04). The flat family-basin-leaf(6) + identity(6) tail below — two contiguous u24 bit-groupings (family:u24 ++ identity:u24) — is V1-LEGACY and forbidden for new units. Every new unit is the V3 content-blind 4+12 facet (E-V3-FACET-4-PLUS-12, lance-graph soa_layout/le-contract.md §3, operator-locked 2026-07-02): classid(4) + 12-byte payload, the 12 bytes an axis-grouped byte register — 6×(u8:u8) / 4×(u8:u8:u8) / 3×(u8:u8:u8:u8) — whose reading (part_of:is_a / X:Y / palette256:palette256 / segment:taxonomy / typed content) the classid's ClassView holds all at once and picks per read. u8:u8 stays two separate bytes — never widened to u16 or u24. A flat u24 has no axis and cannot carry a rail; that is why it is retired. Append-only: the pin is NOT deleted — the u24 tail stays read-only for pre-flip GUIDs, regraded V1-legacy in place. Producer already V3 in code: ruff_spo_address::Facet (facet_classid:u32 + 6×FacetTier{lo:u8,hi:u8}) via ogar-from-ruff mint/emit. Paired follow-ups (mandatory): promote docs/V3-TRANSPILER-ADR.md RFC→adopted; reconcile ogar-fma-skeleton::Guid classid 2→4 (F-2); invert docs/NODEGUID-CANON-AUDIT.md F-3 (see its dated note).

Grace-period amendment (operator, 2026-07-13 — D‑V1‑GRACE‑CARVINGS): an un-migrated class does NOT crash — it gets a legal V3 waiting room: three wide contiguous carvings of the same 96-bit content-blind register (G1 3×u16+2×u24 / G2 4×u24 / G3 3×u32), strongly discouraged if god-object-related or lacking proper bucket rollover; migrate to cosine-replacement palette256 (L4). Not a tail revival — one register read coarsely; the V1 family:identity u24 fragment is the degenerate G1/G2 case. Code home: lance-graph lance_graph_contract::legacy_outliers; catalogue: le-contract.md §3a; ledger: docs/DISCOVERY-MAP.md D‑V1‑GRACE‑CARVINGS.

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
classid    HEEL   HIP    TWIG   family-basin-leaf(6) + identity(6)  ← V1-LEGACY tail (read-only; new units use the V3 4+12 facet, above)
8 hex      4 hex  4 hex  4 hex  12 hex

32 hex = 128 bit = the GUID itself. The UUID's own dash-groups ARE the semantic delimiters — every printed GUID is self-describing at sight. 1 hex digit = 1 nibble = 1 level of the 16-ary tree (FAN_OUT=16). Widths are codebook cardinalities; scale = the next cascade level, never field-widening. Wrappers (e.g. lance-graph NodeGuid, #480) are audited against this canon group-by-group — never the reverse.

3×4 PATH — UNIFORM, RFC-WAIVED (reversed 2026-06-10; the operator's word arrived — the brief v8-native pin broke the uniform Morton stride): HEEL/HIP/TWIG are each 4 full nibbles — 3 tiers × 4 nibbles = 12 path levels, uniform. Tier-of-level = level >> 2 — a shift, never a branch. The cascade's shift/mask arithmetic is canon. The GUID is NOT RFC-stamped: RFC 9562 is a WRAPPER format, and wrappers adapt to the canon, never the reverse — any boundary that genuinely requires RFC-valid UUIDs owns that adaptation at its membrane and pays it explicitly; the canon does not pre-pay it in every key. Native/foreign discrimination lives where semantics live: in classid (foreign keys get a foreign family), not in a format constant. Wikidata-HHTL is the same canon either way — depth beyond 12 native levels was always the hierarchy's job (registry resolve + ref-escape). (The v8-native episode

  • reversal reasoning: INTEGRATION-MAP §9.10. The 4/3/3 carving was never codebook-motivated — it fell out of RFC mark positions — but it traded concrete hot-path uniformity for mostly-hypothetical interop: the key's real consumers — Lance, SurrealDB, EntityKey — are byte-agnostic.)

P0 — THE GUID IS THE KEY OF KEY-VALUE (operator-pinned, 2026-06-10)

The substrate is a key-value store whose key is the canonical GUID:

  • The key prerenders nodes — in any way — with zero value decode. classid → the class template (ClassView); HEEL/HIP/TWIG → the cascade position; basin+leaf → the family neighborhood; identity → the instance. A renderer/router/planner can lay out, group, route, and skeleton-render nodes from keys alone, before (or without ever) fetching a value.
  • A node is 4096 bits: key(128/GUID) + value(3968) — a 512-byte block, 16-byte key, 496-byte value; the value is simply everything the key isn't. The beauty: Lance is free to compress the value bits arbitrarily — columnar encodings, dictionary, PQ, anything — and the store still has a transparent view and address, because the key is never compressed and never needs the value decoded to be useful. Compression never costs addressability.

Tier interpretation — 256×256 CENTROID TILE (operator, 2026-06-10; [H] + named test)

Each tier's 64k space (4 nibbles = 16 bits) is read as a 256×256 centroid tile: two axes, each a byte-index into a 256-entry centroid codebook, nibble-interleaved. Receipts: path = HEEL+HIP+TWIG = 6 bytes = exactly the CAM-PQ 6×256 code (3 tiers × 2 axes = 6 subspaces); the 256×256 LUT is the stack's recurring structure (bgz17 palette distance/compose tables, helix DistanceLut, bgz-tensor attention-as- lookup) → path distance = 3 tier-table lookups, O(1); the HHTL legend already says HIP = palette. Condition that keeps prefix routing rigorous: 256 = 4⁴ — each codebook is built as a 4-level 4-ary centroid HIERARCHY, so a byte's nibbles are the centroid's ancestry (coarse→fine) and is_ancestor_of = centroid-tree containment; the x/y nibble-interleave = alternating-axis refinement (Morton in centroid space). Flat k-means-256 breaks this; hierarchical 4⁴ preserves it. Named test (F11-adjacent): hierarchical-4⁴ vs flat-256 fidelity ρ against the 0.9973/0.965 anchors. Consequence: D-BOTHCASC collapses — spatial mipmap and semantic centroid cascade are ONE address; domains bind the axes (OSM: literal x/y; semantic: PQ subspace pairs); the algebra is identical and domain-agnostic.

Codebook scoping = the class routing prefix (operator, 2026-06-10): the classid group sits in front of the path bytes, so the centroid codebooks are selected by the key's own prefix — longest-prefix binding, a radix lookup on the key being resolved. Every class gets its own 256⁶ ≈ 2.8×10¹⁴-cell semantic space for free (capacity through hierarchy, never widening); the axis binding (x/y vs PQ pairs) is a class-record property resolved by the same resolve read; codebooks mint with the class in the registry (next to ClassView / StructuralSignature — Phase B's shelf), trained once, amortized over all instances (D-AMORT). Finer scopes (a HEEL-subtree codebook) follow the same longest-prefix-wins rule — one rule, every level.

Perturbation encoding — DETERMINISTIC PHASE (operator, 2026-06-10)

The stacked-pyramid perturbation decomposes as (exponent, location, phase, magnitude) — and three of the four are already in the key: exponent = the pyramid level (tier nibbles, >>2); location = the implied sub-tile mantissa (√u / golden sub-placement, never stored); phase = deterministic recurrence from the address (never stored — phase is convention, not data); magnitude = the ONLY stored bits (palette-quantized envelope, coarser granularity than the phase varies). Cost scales with magnitude smoothness, not perturbation bandwidth. Fences: (a) lossless FOR SYNTHESIS by construction; for analysis, the unaligned remainder overflows to the next level or full-residual escalation, decided by the quorum certificate — never assumed; (b) D-QUANTGATE: in quantized layers the phase generator must be the coprime-integer walk (helix CurveRuler stride-4-over-17, bit-exact integer), golden recurrence only as build-time muscle-memory; the deterministic phase doubles as the anti-moiré dither. Receipts: helix = the shipped place/residue split (PLACE deterministic, RESIDUE stored). Full treatment: ndarray guid-prefix-shape-routing.md §4.

Bipolar-phase pyramid — Walsh-Hadamard on VSA (operator, 2026-06-10)

When the deterministic phase is signed (±1, one bit per address×level), the perturbation pyramid becomes the Walsh-Hadamard transform of the address tree, carried on the workspace's existing VSA-bipolar algebra:

  • Sign composition across levels = XOR = vsa_bind (multiply of ±1 = XOR of sign bits; one SIMD shift+xor).
  • Magnitude bundling = vsa_bundle (sum-and-threshold; Markov-respecting per I-SUBSTRATE-MARKOV).
  • Each cell = ⊕_L sign(addr, L) ·_VSA M(addr, L) — a resonance field, not combinatorial selection; Parseval gives "top gaussian preserved" level-to-level.

Quantum-shaped, fully deterministic: superposition (cells hold many bundled contributions; unbind with a role key to extract one), Heisenberg-shaped capacity bound (I-VSA-IDENTITIES Test 1: N ≤ √d/4 ≈ 32 distinct readouts; this IS the uncertainty principle for the substrate), roundtrip bit-exact (phase generated, not stored — same address ⟹ same sign sequence forever; Walsh-Hadamard is self-inverse up to scale). The "Schrödinger's cat" is in a glass box: superposition is real, identity recoverable by key, no measurement randomness.

D-MANTISSA finishes in coprime form: the bipolar phase IS the implied mantissa as 1 sign-bit/level; the CurveRuler stride-4-over-17 walk (integer, bit-exact, coprime ⟹ full permutation) is the generator — D-QUANTGATE-compliant by construction.

The TWO-ALGEBRA rule (load-bearing): sign side = XOR (write-back I1 allows it for single-target deltas), magnitude side = vsa_bundle NEVER MergeMode::Xor (raw-XOR-on-magnitudes breaks the Markov semigroup, I-SUBSTRATE-MARKOV). Two operators, two algebras, one pyramid. Fences: "quantum-like" is the bundling algebra, NOT measurement randomness (no headline drift); bipolar = 1-bit phase; multi-bit phases stack above it only when measured to be needed. Full treatment + probes in ndarray guid-prefix-shape-routing.md §4b.

Standing watch — 3×4 vs 4×3 (operator mandate, 2026-06-10)

"Correct me at any time": if evidence ever shows 3 tiers × 4 nibbles to be more expensive, lower-synergy, or higher-entropy than 4 tiers × 3 nibbles, say so immediately — standing permission and obligation.

Operator's rationale (recorded so it doesn't dilute): 3×4 is a modesty in levels that buys radix-tree cheapness and less horizontal difference, but a wider spread. Calculation ledger (2026-06-10) confirms it in mechanism: tier-of-nibble = n >> 2 (shift) vs n/3; tiers are u16-aligned vs 1.5-byte-straddling; dash-groups = tiers (self-describing print) vs dashes lying; Morton de-interleave = one byte per axis per tier vs sub-byte masking; 3 hops vs 4 (wide-radix cheapness); sibling XOR localizes to one aligned group. The one 4×3 synergy (tier index = one 4096-codebook slot) is recoverable inside 3×4 for free — codebooks attach at any nibble depth, so a 3-nibble prefix indexes a 4096 sub-table whenever wanted; the reverse recovery is impossible. Flip condition (falsifiable): a measured workload where 4-tier granularity beats 3-tier on the radix/de-interleave benches despite the alignment costs. Until measured: 3×4 stands.

Doc family (read in this order)

  1. docs/DISCOVERY-MAP.md — the discovery ledger (D-* entries, graded [G]/[H]/[S], append-only).
  2. docs/INTEGRATION-MAP.md — layers, seams (each with its contract TYPE), the phase DAG, falsification gates F1–F14.
  3. docs/INTEGRATION-TEST-PLAN.md — the probe-first execution companion: wave-ordered probes (Wave 0 runs entirely against shipped code), the three falsification joints J1–J3 with explicit KILL conditions, and the operating rule that no integration brick lands before its probe is green.
  4. docs/PROBE-SUBSTRATE-PROPOSAL.md (PROPOSAL, 2026-06-10) — the next architecture: the Living Probe Ledger — automating the loop the session opened (probe is truth; ledger mirrors probe; debt is visible). Wave A is a ~200 LOC parser; waves gated on operator green-light.
  5. .claude/handovers/2026-06-10-canon-arc-session-handover.md — honest attribution of the 2026-06-10 canon-arc session: what was the operator's architecture, what was my anti-dilution work, what failure modes the apparatus caught.
  6. docs/OGAR-AST-CONTRACT.md — the IR type surface (THINK arm Class / DO arm ActionDef+ActionInvocation / membrane KausalSpec).
  7. docs/SURREAL-AST-AS-ADAPTER.md — the carved decision: SurrealQL AST is an adapter, not the spine; behavioral arm cannot live in DDL. Operational pre-flight: docs/SURREAL-AST-TRAP-PREFLIGHT.md (the spellbook — five questions, 90 seconds, MANDATORY before any producer→IR / transcode / codegen / .surql authoring session).
  8. docs/OGAR-CONSUMER-BEST-PRACTICES.md — the muscle-memory guide for every consumer-side session (medcare-rs, woa-rs, smb-office-rs, odoo-rs, openproject-nexgen-rs, q2). One-line invariant: the classid is pure address; the magic is what it resolves to. Drilled with worked examples across every PortSpec, the four canonical patterns (pull classid · compose render · authorize · migrate), and an anti-pattern catalogue paired with the right shapes. MANDATORY before authoring any consumer call site that mentions class_id, APP_PREFIX, PortSpec, ClassView, or any *Bridge/UnifiedBridge.
  9. docs/OGAR-AS-IR.md — the compiler framing. lance-graph is a multi-phase compiler whose IR is OGAR; this doc names the phases (front-end / symbol table / linker / semantic analysis / optimization / codegen back-ends / native codegen / runtime), restates each existing doctrine in compiler vocabulary, lists six IR-shape tests new design must pass, and labels every prior design doc as already-compiler-shaped. READ BEFORE adding a field to Class, a variant to ActionDef, a slot to KausalSpec, a new lowering pass, or any other IR-surface change. The framing changes no existing decision; it changes every future one.
  10. docs/OGAR-TRANSPILE-SUBSTRATE.md — the power, in one doc. OGAR as the bidirectional per-class transpiler: pull-in (source → ogar-from-<lang> → ModelGraph → lift + mint → CompiledClass), rail-facet addressing (classid = (concept<<16)|APP_PREFIX, the 16-byte FacetCascade, cross-app convergence), pull-back (runtime wrapper contract like lance-graph-contract, or codegen emit like ogar-adapter-surrealql), and the 85/15 split (mechanical logic minted into OGAR; the "impossible" 15% = a per-language adapter + ClassView + ontological grounding). READ to understand why a consumer collapses to "a compiler-store caller + adapters, at the cost of an import." Worked example: account.move → 0x0202_0002. (Order flipped 2026-07-02 — canon HIGH / custom LOW; pre-flip docs and baked data use the legacy order — see docs/DISCOVERY-MAP.md D-CLASSID-CANON-HIGH-FLIP.)
  11. docs/ARCHITECTURAL-DECISIONS-2026-06-04.md — ADR-001..025 (ADR-026 pending).
  12. .claude/agents/ — the 5+3 hardening pattern (5 research savants + 3 brutally-honest reviewers). Run it before any claim enters the canon. Theorem-checker rule 0: pin the unit system first (bits vs hex vs bytes — born from a real failure). Sequencing + base case (operator-ruled 2026-08-04, recursion sweep): the pass is STRICTLY ordered — the 5 first streamline the open points into a hardened draft; only then do the 3 attack the already-hardened draft; what they catch is fixed; and if necessary the 5+3 can deliberately rule AGAIN on the result. Never the 3 in parallel with (or ahead of) the 5: most sessions' raw output is not yet hardened, and attacking unhardened material invites hallucinated, deflected, reactive coding — the reviewers must have a consolidated object to break, not a moving one. The recursion bound follows from the same ordering: each cycle terminates (streamline → attack → fix → land), and a further full pass is a deliberate re-invocation when warranted, never an automatic obligation — read literally, "before any claim" required a council on the council's own verdict, forever. (Test + provenance: lance-graph E-THE-HYGIENE-RULE-RECURSED-1.)

Non-negotiables

  • The Firewall (ADR-022/023): no serialization in the hot path; the IR is wire-truth; inter-mailbox state is Batons.
  • SurrealQL is an adapter, not a spine: before any producer→IR / transcode / codegen / .surql authoring session, read docs/SURREAL-AST-TRAP-PREFLIGHT.md (five-question pre-flight, 90 seconds). The behavioral arm cannot live in DDL — DEFINE EVENT … WHEN … THEN … carrying lifecycle is the "negative-beauty hijack" SURREAL-AST-AS-ADAPTER.md §0 rejects. Behavior flows producer → OGAR Class+ActionDef → adapter; never producer → DDL.
  • Consumer call sites: classid is address, magic is at the resolution target: before authoring consumer code that pulls a classid, composes a render address, authorizes, or migrates off a bridge, read docs/OGAR-CONSUMER-BEST-PRACTICES.md (the muscle- memory guide). The lo u16 chooses render skin (per-app ClassView/template), the hi u16 names the shared concept (RBAC + ontology); neither half carries behavior — class-magic (ActionDef+KausalSpec) is a property of the Core node the address resolves to, never of the address. (Order flipped 2026-07-02 — canon HIGH / custom LOW; pre-flip docs and baked data use the legacy order — see docs/DISCOVERY-MAP.md D-CLASSID-CANON-HIGH-FLIP.)
  • PII: never emit German PII labels (medcare-rs leaf-rename at the adapter is the guarantee). Word-boundary abort-guard before commit.
  • No model identifier in any committed artifact (chat only).
  • Evidence discipline (SUPERSEDES the shell rule): ⊘ the rule here was "grep/sed/tail/head/awk via Bash are prohibited — use the Grep/Read/Glob tools." That policed which Unix command is typed, not the failure it was written for. The governing rule is now epistemic: SEARCH IS NAVIGATION, NEVER EVIDENCE. A search may establish only "candidates are X, Y, Z" — never what a type means, what a function guarantees, that a consumer does not exist, who owns something, or which way a dependency runs. 0 hits proves nothing; a global negative needs a CLOSED, explicitly named search space; a partial Read is not evidence for a whole-file claim; and a search must never be the last tool result before an architectural conclusion. sed/head/tail/awk stay prohibited for SOURCE INSPECTION specifically (a numeric slice has no semantic boundary), while limiting a non-search command's output stays fine. Full law, the auto-deepen triggers, the paging rule and the delegation/escalation levels: lance-graph .claude/knowledge/FIRST-HAND-SOURCE-LAW.md, enforced by that repo's PreToolUse guard.
  • Append-only canon: never delete a ledger entry; regrade in place; corrections cite their pass (savant / G-pass / canon-pass).