docs(framing): OGAR as IR — the compiler framing as a one-pager

[AdaWorldAPI]

What

A new docs/OGAR-AS-IR.md that names the architectural lens already in use: lance-graph is a multi-phase compiler whose IR is OGAR. The doc is a lens, not a new abstraction layer — it labels the layer already shipped, in vocabulary that has been field-tested for fifty years of compiler engineering.

Five sections

§	Content
1	The mapping — compiler phase → OGAR / lance-graph piece (front-end readers, IR, symbol table, linker, public ABI, semantic analysis, optimization passes, codegen back-ends, native codegen via jitson, runtime via lance-graph-callcenter)
2	Ten existing doctrine statements paired with their standard compiler primitives — e.g. "classid is pure address; magic is what it resolves to" = SSA value-id with a symbol table; "never producer → DDL" = no eval at codegen time; "BBB-barrier" = internal IR types vs public ABI
3	Six tests for new IR design — a checklist a proposal must pass: (1) SSA / dataflow-explicit; (2) effect annotations first-class; (3) typed signature not field bag; (4) lowering passes named, not implicit; (5) optimization passes declare a semantic-preservation guarantee; (6) the IR is the canonical artifact
4	Cross-references — eight existing docs labeled as already-compiler-shaped (THE-FIREWALL.md, OGAR-AST-CONTRACT.md, SURREAL-AST-AS-ADAPTER.md, APP-CLASS-CODEBOOK-LAYOUT.md, CLASSID-RBAC-KEYSTONE-SPEC.md, OGAR-CONSUMER-BEST-PRACTICES.md, CONSUMER-MIGRATION-HOWTO.md, SURREAL-AST-TRAP-PREFLIGHT.md), each paired with its compiler equivalent
5	Why the framing — vocabulary (fifty years of compiler engineering to draw from) + discipline (compiler IRs are designed to be optimized, lowered, analyzed; ontologies are designed to be queried; the work shipped in this repo is compiler work)

Registration

• New top row in the Design Guards table in README.md and README.de.md
• Doc-family entry docs: OGAR AST contract — the typed surface the ractor codegen lands on #9 in CLAUDE.md with a READ-BEFORE rule for any IR-surface addition

Verification

All 9 cross-referenced docs verified to resolve. Zero emoji / zero AI-pattern phrasing / zero named individuals. Docs-only.

What it does and does not do

The framing changes no existing decision — every doctrine and every shipped doc remains exactly as it was. It changes every future decision by giving contributors a vocabulary that has fifty years of design experience encoded in it. Saying "OGAR is a graph ontology" loses the SSA / lowering / optimization / linker shapes. Saying "OGAR is the IR of a compiler" recovers them.

---

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.