docs(OGAR): consumer best-practices guide + classid-is-address precision

[AdaWorldAPI]

What

Two coupled sharpenings, born from cross-session corroboration on the GUID layout question (parallel session shipped lance-graph #591 with the same address-vs-magic precision — two independent sessions converging on the framing is the muscle these docs together drill).

Four files

1. docs/OGAR-CONSUMER-BEST-PRACTICES.md (new) — the muscle-memory guide

Pattern-centric, example-heavy. Every claim shown with a real classid value and a real consumer. Designed for cross-session muscle memory, per operator request.

• §0 — the one-line invariant: "classid is pure address; magic is what it resolves to" + three drilled corollaries
• §1 — address anatomy: worked examples for 0x0000_0901 (canonical patient) · 0x0005_0901 (Medcare's render) · 0x0001_0102/0x0007_0102 (WorkPackage/Issue, same concept different render) · the five-way BILLABLE_WORK_ENTRY convergence pin (0x0003_0103/0x0004_0103/0x0001_0103/0x0007_0103/0x0002_0103). APP allocation table + domain byte table.
• §2 — the four canonical consumer patterns, each with ✅ canonical + ❌ anti:
  • Pattern 1: pull classid (Port::class_id(name)) — example calls across every consumer's PortSpec
  • Pattern 2: compose render classid (APP_PREFIX | concept) using OGAR feat(ogar-vocab): APP‖class machinery — typed PortSpec::APP_PREFIX + app render-classid composition #97's typed helper
  • Pattern 3: authorize by classid (interim guidance until the lance-graph-rbac keystone lands)
  • Pattern 4: distill/migrate from legacy bridge — 4a one-line import repoint vs 4b full structural drop
• §3 — anti-pattern catalogue (7 entries), each paired with its right-shape §reference
• §4 — worked migration narrative: Medcare's patient end-to-end through all four patterns
• §5 — Knowledge Activation triggers + agents that load Tier-1
• §6 — cross-refs (incl. lance-graph #591 as parallel-session sibling)

2. docs/SURREAL-AST-TRAP-PREFLIGHT.md — §0 prefix added

Sharpens the spellbook with the precision from #591: "the classid is pure address; the magic is what it resolves to." Explains why the trap is structurally impossible to fix from inside DDL — SurrealQL has the address but not the Core types behavior resolves to, so encoding lifecycle in DEFINE EVENT is putting the value into the key.

3. CLAUDE.md — registered

• Best-practices guide added to doc family as Sprint 7 muscle-memory: three-way alignment (Kanban/ractor/SurrealQL) + std::sync correction round-trip #8 (MANDATORY-before-rule)
• New non-negotiable: "Consumer call sites: classid is address, magic is at the resolution target" — companion to the existing SurrealQL non-negotiable

4. docs/APP-CLASS-CODEBOOK-LAYOUT.md — cross-ref added

Top-of-doc pointer to the muscle-memory guide; reinforces the hi-u16 = render magic ≠ class magic distinction (the precision I missed in my first pass).

The address-vs-magic precision (the sharpening)

classid : u32  =  0xAAAA ‖ 0xDDCC                       (8 nibbles, BOTH halves = address)
                    │         │
                    │         └─ lo u16: WHICH CONCEPT  (shared identity)
                    └─────────── hi u16: WHOSE RENDER   (per-app skin)

         ──────►  resolves to  ──────►
                     ├─ ClassView           the SKIN     (render — per-app, picked by hi)
                     ├─ Class               the SHAPE    (structural — canonical, picked by lo)
                     └─ ActionDef +         the MAGIC    (behavioral — lifecycle, callbacks,
                        KausalSpec                        validations; ALWAYS in OGAR Core,
                                                         NEVER in the address or in DDL)

The classid carries no magic. Class-magic (rails ActiveRecord-style callbacks, lifecycle, validations) is a property of the Core node the address resolves to — never of the address itself. The hi u16 picks render magic (which app's template), never class magic.

This is why the trap spellbook (#99) forbids smuggling behavior into DDL: DDL has the address but not the Core types it resolves to.

Cross-session convergence — same shape, two domains

Session	Spellbook	Cast for
OGAR #99 (mine)	docs/SURREAL-AST-TRAP-PREFLIGHT.md	spine governance
OGAR #100 (this PR)	docs/OGAR-CONSUMER-BEST-PRACTICES.md	consumer muscle memory
lance-graph #591 (parallel)	.claude/knowledge/ogar-consumer-preflight.md + ISS-CONTRACT-APP-PREFIX-MIRROR Core-gap entry	spine-side consumer

Doc-only PR. Nothing code-side touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EYvNjD8M8LMNYbRy3gq2FP

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.