feat(virtual-entities): support plain BaseModel roots end-to-end (#87)

[allmonday]

Summary

Three orthogonal capabilities close Issue #87 — make plain pydantic.BaseModel subclasses first-class participants in NexusX resolution and ER visualization, eliminating the _subset_registry hack.

1. ErManager.add_virtual_entities([...]) — new method on ErManager. Registers plain BaseModel classes as virtual entities in _registry. Validates: must be a BaseModel (TypeError), must NOT be a SQLModel (TypeError — SQLModel goes through __init__), duplicates rejected (ValueError), calls after first create_resolver() rejected (RuntimeError — registry frozen).
2. DefineSubset source widening — DefineSubset.__subset__ source widens from type[SQLModel] to type[BaseModel]. "Subset" = schema subset (selection of model_fields); both SQLModel and BaseModel fit. Difference is data provisioning: SQLModel via ORM (_orm_to_dto invoked), BaseModel constructed directly by user.
3. Resolver unified source-resolution — _scan_auto_load_fields and _get_loader gain a unified fallback (~15 LOC): when get_subset_source(node_type) returns None, check whether node_type itself is in _registry (plain BaseModel virtual root). Downstream _registry.get_relationships(source) is source-type-agnostic.

Plus ER/Voyager rendering: ErDiagram.from_er_manager(er) classmethod handles both SQLModel and virtual entities; ErDiagramDotBuilder already iterates _registry uniformly so virtual entities appear as schema nodes automatically.

Design artifacts (specs/004-non-sqlmodel-roots/)

• spec.md — 17 FRs, 9 edge cases, 3 user stories
• plan.md / research.md (R1–R8 decisions recorded)
• contracts/api.md — 6 public API contracts
• quickstart.md — 11 runnable scenarios + Coverage Matrix
• tasks.md — 36 tasks, all [X]

Test plan

• +35 new tests pass (1060 total, was 1025 → +35; 6 skipped pre-existing)
• 0 regressions — all 1025 prior tests unchanged
• ruff clean on all touched files (21 pre-existing errors in other test files are unrelated, exist on master)
• Tests cover all 17 FRs + 6 edge cases (see traceability table at bottom of tasks.md)

Test files:

• tests/test_virtual_entities.py (22 tests): Layer 1 API contract (9), Layer 2 capability parity (9), Layer 3 invariants (4)
• tests/test_definesubset_basemodel.py (6 tests): schema subsetting, DTO + registered source → auto-load fires
• tests/test_virtual_entities_er.py (7 tests): ER diagram + Voyager DOT rendering with mixed SQLModel + virtual entities

Sample test (Layer 1, the most representative):

class CurrentUserRoot(BaseModel):    # plain BaseModel, no NexusX base class
    oid: str
    name: str
    agents: list[AgentDTO] = []

    __relationships__ = [
        Relationship(fk="oid", target=list[AgentDTO], name="agents",
                     loader=_load_agents_by_oid),
    ]

er = ErManager(entities=[Agent], session_factory=...)
er.add_virtual_entities([CurrentUserRoot])   # new API
resolver = er.create_resolver()()
result = await resolver.resolve(CurrentUserRoot(oid="user-1", name="Alice"))
assert {a.name for a in result.agents} == {"A1", "A2"}

Backward compatibility

• ✅ ErManager.__init__ signature unchanged (base= / entities= still required)
• ✅ DefineSubset.__subset__ shape unchanged (just accepts wider source type)
• ✅ Resolver accepts BaseModel today already (tests/test_resolver.py:22-32); this PR adds the registration mechanism and unified source-resolution
• ✅ All 1025 prior tests pass without modification

🤖 Generated with Claude Code