F4 design: graphdb_rules data model (Phase A) + L7 prerequisite

[david-w-t]

Summary

Architectural design for F4 (E1) — graphdb_rules Rule Engine, the last remaining gen_server stub. F4 is decomposed into six phases; this PR ships only the design document — no code changes.

• Phase A is specified end-to-end: meta-ontology shape, AVP schemas, attachment mechanism, public API, validation catalog, ~30 CT cases.
• Phases B–F are outlined as future cycles (composition engine, reactive learning ×2, instantiation engine, connection constraints).
• L7 prerequisite documented in §1 — partition the Literals subtree (nref 7) by owning subsystem so each worker seeds its literal attributes under its own sub-group (Attribute Literals, Language Literals, Rule Literals). Clean-slate seeding; no runtime migration code.

Key architectural commitments

Tag	Decision
D1	P2 placement — Rule class root + leaf meta-classes under nref 3 (Classes)
D2	A2+B3 — rules are kind=instance whose class is a rule meta-class
D3	Y1 — general rules live in environment; project rules deferred to L6
D4	Unified ConnectionRule with 3-state mode (mandatory | auto | propose)
D5	Attachment via applies_to / applied_by arc pair from owning class
D6	Locked AVP schemas for CompositionRule + ConnectionRule
D7	Scope-aware API throughout; Phase A env-only with L6 placeholder error
D8	graphdb_rules direct entry point, not routed through graphdb_mgr
D9	Multiplicity attribute_type => term (union types are future M8 work)
D10	Supervisor reorder — graphdb_rules last child of graphdb_sup
D11	Literals subtree partitioned by owning subsystem (L7); no runtime migration

What ships in Phase A (Scope α) once it lands

• 12 new env nrefs (1 sub-group + 6 literals + applies_to/applied_by pair + Rule + CompositionRule + ConnectionRule)
• Public API: 11 exports (lifecycle + creation + retrieval)
• 11-error validation catalog
• ~30 CT cases including a `complex_scenarios` group probing rule-on-rule and taxonomy-isolation edge cases
• One supervisor child reorder, no public-API breaks

Surfaced follow-up tasks

• L6 — Multi-Project Sessions (Engineering Hygiene, new) — session state holds multiple open projects; cross-project nref disambiguation; project-scoped overlay tables.
• L7 — Literals Subtree Restructuring (Engineering Hygiene, new, gates Phase A) — partitions Literals by owning subsystem; clean-slate seeding only.

Test plan

This PR is design-only. CI runs `rebar3 compile` which passes (no code changes). Test plan for the implementation PR (separate, future):

• L7 lands as its own PR before F4 Phase A
• Phase A CT suite: ~30 cases (seeding 5, composition 5, connection 3, validation 11, retrieval 6, scope 2, cache_audit 1, complex_scenarios 3)
• `graphdb_mgr:verify_caches/0 = ok` after each test case
• No compile warnings
• All existing tests (267 CT + 103 EUnit) continue to pass

🤖 Generated with Claude Code