epic: ObjectRegistry Architectural Debt — Circular Dependency & Scalability

[willgriffin]

Epic: ObjectRegistry Architectural Debt

Background

The ObjectRegistry in packages/core/src/registry.ts has grown to 5,539 lines with 10+ distinct responsibilities. Issue #1001 exposed a latent failure where name resolution ambiguity causes false circular inheritance detection when enough packages (459 objects across 25 manifests) are loaded simultaneously.

This is not an isolated bug — it is structural debt that will worsen as more packages are added.

Root Cause Analysis

Three competing class identity resolution systems exist in the registry:

1. Prototype chain walking (buildInheritanceChain) — uses constructor references
2. Manifest extends field (getInheritanceChain) — uses string names
3. FK dependency graph (getInitializationOrder) — uses simple class names

These systems disagree under scale. Manifest-loaded classes have stub constructors (class extends SmrtObject) that bypass the declared extends hierarchy. When findClass() resolves an ambiguous simple name, getInheritanceChain() can produce circular chains like VideoShot → VideoShot → VideoShot.

Additionally, getInheritanceChain() has side effects — it calls registerFromManifest() during what should be a read operation, making the system non-deterministic based on call order.

Issues in This Epic

Immediate (fix #1001):

• Use qualified names in extends resolution to fix circular inheritance #1004 — Use qualified names in extends resolution
• Add findClassStrict() with package-aware disambiguation #1005 — Add findClassStrict() for inheritance resolution

Short-term (reduce risk):

• Split ObjectRegistry into focused modules #1006 — Split ObjectRegistry into focused modules
• Make manifest discovery a pure operation — no side effects during reads #1007 — Make manifest discovery a pure operation
• Add integration tests for high object counts (400+ registered objects) #1008 — Add integration tests for high object counts (400+)

Long-term (architecture evolution):

• Implement two-phase initialization model (discovery → registration) #1009 — Two-phase initialization model (discovery → registration)
• Build-time declarative schema generation #1010 — Build-time declarative schema generation
• Registry lockdown phase after initialization #1011 — Registry lockdown phase after initialization

Reference

• Architecture review: conducted 2026-03-08
• Historical circular dependency issues: fix: SmrtObject system properties causing circular serialization errors #75, feat(cli): extract CLI functionality into standalone package #142, smrt-cli should call loadConfig() before instantiating external package classes #543, bug(core): Circular inheritance false positive when extending upstream classes with same JS class name #871, bug: db:migrate crashes in MigrationTracker.initialize when smrt-commerce is registered #1001
• Key files: packages/core/src/registry.ts, packages/core/src/manifest/manifest-loader.ts