@happyvertical/smrt-core 0.52.0 → 0.53.0

package/dist/registry/name-resolver.d.ts

@@ -35,6 +35,8 @@ export declare function hasClassCaseInsensitive(name: string): boolean;
  *
  * Lookup priority:
  * 1. Direct hit on classes map (works for qualified names as keys)
+ *    1b. A deprecated qualified name declared in a class's
+ *        `previousQualifiedNames` resolves to that class (#3338)
  * 2. If input contains ':', prefer direct qualified lookup, then fall back
  *    to an exact/simple registration when runtime source imports registered
  *    the class before package-qualified promotion happened
@@ -42,7 +44,7 @@ export declare function hasClassCaseInsensitive(name: string): boolean;
  *    - Unambiguous (1 match) → return it
  *    - Ambiguous (>1 matches) → log warning, return first
  */
-export declare function findClass(name: string): RegisteredClass | undefined;
+export declare function findClass(name: string, source?: string): RegisteredClass | undefined;
 /**
  * Strict class lookup with package-aware disambiguation.
  *
@@ -70,8 +72,12 @@ export declare function getClass(name: string): RegisteredClass | undefined;
 export declare function getClassByConstructor(ctor: SmrtObjectConstructor): RegisteredClass | undefined;
 /**
  * Get a registered class by its qualified name (O(1) direct lookup).
+ *
+ * A deprecated qualified name declared in a class's `previousQualifiedNames`
+ * resolves to that class with a one-time deprecation warning naming
+ * `source` (#3338).
  */
-export declare function getClassByQualifiedName(qualifiedName: string): RegisteredClass | undefined;
+export declare function getClassByQualifiedName(qualifiedName: string, source?: string): RegisteredClass | undefined;
 /**
  * Get a registered class by package name and class name.
  */

package/dist/registry/name-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"name-resolver.d.ts","sourceRoot":"","sources":["../../src/registry/name-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ9E,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAyFtE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKtE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAuDnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB,eAAe,GAAG,SAAS,CAyC7B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,GACrB,MAAM,CAyDR;AAID;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAElE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,qBAAqB,GAC1B,eAAe,GAAG,SAAS,CAM7B;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,GACpB,eAAe,GAAG,SAAS,CAE7B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,eAAe,GAAG,SAAS,CAG7B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CActE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,CAgCjE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,GAClB,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAU9B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,cAAc,GACzB,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAW9B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAE/D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAGxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAqBjD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9C"}
+{"version":3,"file":"name-resolver.d.ts","sourceRoot":"","sources":["../../src/registry/name-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAS9E,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAyFtE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKtE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,eAAe,GAAG,SAAS,CA+D7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB,eAAe,GAAG,SAAS,CA0C7B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,GACrB,MAAM,CAyDR;AAID;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAElE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,qBAAqB,GAC1B,eAAe,GAAG,SAAS,CAM7B;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd,eAAe,GAAG,SAAS,CAK7B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,eAAe,GAAG,SAAS,CAG7B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CActE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,CAiCjE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,GAClB,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAU9B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,cAAc,GACzB,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAW9B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAE/D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAGxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAqBjD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9C"}

package/dist/registry/name-resolver.js

@@ -3,6 +3,7 @@ import { getRegistryGeneration } from "./generation.js";
 import { createQualifiedName, isQualifiedName, parseQualifiedName } from "../utils/qualified-names.js";
 import { getClasses, getConstructorIndex, verboseLog } from "./shared-state.js";
 import { getLocalTestManifestCache, getManifestCache, getTestManifestCache } from "../manifest/store.js";
+import { resolveQualifiedNameAlias } from "./qualified-name-aliases.js";
 //#region src/registry/name-resolver.ts
 /**
 * Name resolution module for the SMRT ObjectRegistry.
@@ -106,6 +107,8 @@ function hasClassCaseInsensitive(name) {
 *
 * Lookup priority:
 * 1. Direct hit on classes map (works for qualified names as keys)
+*    1b. A deprecated qualified name declared in a class's
+*        `previousQualifiedNames` resolves to that class (#3338)
 * 2. If input contains ':', prefer direct qualified lookup, then fall back
 *    to an exact/simple registration when runtime source imports registered
 *    the class before package-qualified promotion happened
@@ -113,10 +116,12 @@ function hasClassCaseInsensitive(name) {
 *    - Unambiguous (1 match) → return it
 *    - Ambiguous (>1 matches) → log warning, return first
 */
-function findClass(name) {
+function findClass(name, source) {
 	const classes = getClasses();
 	const registered = classes.get(name);
 	if (registered) return registered;
+	const aliased = resolveQualifiedNameAlias(name, source);
+	if (aliased) return aliased;
 	if (isQualifiedName(name)) {
 		const { packageName, className } = parseQualifiedName(name);
 		const keys = registryKeysBySimpleName(className);
@@ -151,7 +156,7 @@ function findClassStrict(name, fromPackage) {
 	const classes = getClasses();
 	const registered = classes.get(name);
 	if (registered) return registered;
-	if (isQualifiedName(name)) return;
+	if (isQualifiedName(name)) return resolveQualifiedNameAlias(name);
 	if (fromPackage) {
 		const qualifiedAttempt = createQualifiedName(fromPackage, name);
 		const byQualified = classes.get(qualifiedAttempt);
@@ -206,16 +211,19 @@ function getClassByConstructor(ctor) {
 }
 /**
 * Get a registered class by its qualified name (O(1) direct lookup).
+*
+* A deprecated qualified name declared in a class's `previousQualifiedNames`
+* resolves to that class with a one-time deprecation warning naming
+* `source` (#3338).
 */
-function getClassByQualifiedName(qualifiedName) {
-	return getClasses().get(qualifiedName);
+function getClassByQualifiedName(qualifiedName, source) {
+	return getClasses().get(qualifiedName) ?? resolveQualifiedNameAlias(qualifiedName, source);
 }
 /**
 * Get a registered class by package name and class name.
 */
 function getClassInPackage(packageName, className) {
-	const qualifiedName = createQualifiedName(packageName, className);
-	return getClasses().get(qualifiedName);
+	return getClassByQualifiedName(createQualifiedName(packageName, className));
 }
 /**
 * Find all registered classes with a given simple class name.
@@ -235,8 +243,9 @@ function findClassesByName(className) {
 */
 function resolveType(shortName) {
 	if (shortName.includes(":") && shortName.startsWith("@")) {
-		if (!getClassByQualifiedName(shortName)) throw new Error(`Class "${shortName}" is not registered. Make sure the package is installed and the class is decorated with @smrt().`);
-		return shortName;
+		const registered = getClassByQualifiedName(shortName);
+		if (!registered) throw new Error(`Class "${shortName}" is not registered. Make sure the package is installed and the class is decorated with @smrt().`);
+		return registered.qualifiedName ?? shortName;
 	}
 	const matches = findClassesByName(shortName);
 	if (matches.length === 0) throw new Error(`Class "${shortName}" is not registered. Make sure the package is installed and the class is decorated with @smrt().`);

package/dist/registry/name-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"name-resolver.js","names":[],"sources":["../../src/registry/name-resolver.ts"],"sourcesContent":["/**\n * Name resolution module for the SMRT ObjectRegistry.\n *\n * Handles class lookup, disambiguation, and qualified name resolution.\n * All functions operate on the shared globalThis state.\n *\n * Release B (#1133): classNameMap is gone — the eagerly-maintained\n * lowercase-simple-name → qualified-key[] index was removed in favor of\n * on-demand iteration over the `classes` Map. Production SMRT apps carry\n * a few hundred classes at most, so the linear scan is negligible and\n * removes an entire class of cache-sync bugs (#584, #847, #951).\n *\n * #3047: hydration resolves names per row, so the scan now runs once per\n * registry generation into a derived (never hand-maintained) index; see\n * `getSimpleNameIndex()` and `registry/generation.ts`.\n *\n * Extracted from registry.ts as part of issue #1006.\n * @see https://github.com/happyvertical/smrt/issues/1006\n * @see https://github.com/happyvertical/smrt/issues/1133\n */\n\nimport { ConfigurationError } from '../errors';\nimport {\n  getLocalTestManifestCache,\n  getManifestCache,\n  getTestManifestCache,\n} from '../manifest/store.js';\nimport type { QualifiedClassName, SmrtVisibility } from '../scanner/types.js';\nimport {\n  createQualifiedName,\n  isQualifiedName,\n  parseQualifiedName,\n} from '../utils/qualified-names.js';\nimport { getRegistryGeneration } from './generation';\nimport { getClasses, getConstructorIndex, verboseLog } from './shared-state';\nimport type { RegisteredClass, SmrtObjectConstructor } from './types';\n\n// ── Simple-name iteration (replaces classNameMap reads) ─────────────\n\n/**\n * Return every registry key whose registered class has the given simple\n * name (case-insensitive). Replaces the old eagerly-maintained\n * `__smrtRegistryClassNameMap` lookup: we iterate `classes` instead.\n *\n * Cost is O(n) over the classes map; production SMRT apps hold low-\n * hundreds of entries so this is trivially fast. Returned keys preserve\n * insertion order, which makes the \"first match wins\" behavior of the old\n * map-based lookup deterministic in the same way.\n *\n * De-duplicates by RegisteredClass object identity so a class registered\n * under both a simple key and a promoted qualified key (a transitional\n * state during manifest merge) counts as a single entry — matching the\n * old classNameMap's behavior of storing each canonical qualified key once.\n * When that happens, the qualified key wins over the simple one.\n */\nfunction registryKeysBySimpleName(simpleName: string): string[] {\n  const keys = getSimpleNameIndex().get(simpleName.toLowerCase());\n  return keys ? [...keys] : [];\n}\n\n/**\n * Lower-cased simple name → registry keys, rebuilt once per registry\n * generation (#3047).\n *\n * #1133 removed an eagerly-maintained name index because every writer had to\n * keep it in sync. This one is derived, not maintained: it is rebuilt from\n * the `classes` map whenever the registry generation moves, and every\n * registry mutation bumps the generation (the map itself is\n * generation-tracked; in-place identity changes bump explicitly). Hydration\n * resolves names several times per row, so the O(registered classes) scan\n * per lookup dominated large result sets.\n */\nlet simpleNameIndex:\n  | {\n      generation: number;\n      classes: Map<string, RegisteredClass>;\n      keysByName: Map<string, string[]>;\n    }\n  | undefined;\n\nfunction getSimpleNameIndex(): Map<string, string[]> {\n  const classes = getClasses();\n  const generation = getRegistryGeneration();\n  if (\n    simpleNameIndex &&\n    simpleNameIndex.generation === generation &&\n    simpleNameIndex.classes === classes\n  ) {\n    return simpleNameIndex.keysByName;\n  }\n\n  const byName = new Map<string, Map<RegisteredClass, string>>();\n  for (const [key, value] of classes.entries()) {\n    const lower = value.name?.toLowerCase();\n    if (!lower) continue;\n\n    let seen = byName.get(lower);\n    if (!seen) {\n      seen = new Map<RegisteredClass, string>();\n      byName.set(lower, seen);\n    }\n\n    const existing = seen.get(value);\n    if (!existing) {\n      seen.set(value, key);\n      continue;\n    }\n\n    // Two keys for the same object: prefer the qualified form.\n    if (key.includes(':') && !existing.includes(':')) {\n      seen.set(value, key);\n    }\n  }\n\n  const keysByName = new Map<string, string[]>();\n  for (const [lower, seen] of byName) {\n    keysByName.set(lower, [...seen.values()]);\n  }\n  simpleNameIndex = { generation, classes, keysByName };\n  return keysByName;\n}\n\n// ── Lookup functions ────────────────────────────────────────\n\n/**\n * Check if a class is already registered (case-insensitive).\n * Returns the canonical name if found, undefined otherwise. Returns\n * undefined if the simple name is ambiguous across multiple packages.\n */\nexport function getCanonicalClassName(name: string): string | undefined {\n  const keys = registryKeysBySimpleName(name);\n  if (keys.length === 1) return keys[0];\n  // Zero matches, or ambiguous with >1 entries\n  return undefined;\n}\n\n/**\n * Check if a class exists by name (case-insensitive).\n */\nexport function hasClassCaseInsensitive(name: string): boolean {\n  return getSimpleNameIndex().has(name.toLowerCase());\n}\n\n/**\n * Helper for class lookup with qualified name support.\n *\n * Lookup priority:\n * 1. Direct hit on classes map (works for qualified names as keys)\n * 2. If input contains ':', prefer direct qualified lookup, then fall back\n *    to an exact/simple registration when runtime source imports registered\n *    the class before package-qualified promotion happened\n * 3. Simple-name iteration by lowercase\n *    - Unambiguous (1 match) → return it\n *    - Ambiguous (>1 matches) → log warning, return first\n */\nexport function findClass(name: string): RegisteredClass | undefined {\n  const classes = getClasses();\n\n  // 1. Direct hit on classes map (fast path, works for qualified keys)\n  const registered = classes.get(name);\n  if (registered) {\n    return registered;\n  }\n\n  // 2. Qualified lookup fallback for source-registered classes.\n  // In workspace/dev mode a package can be imported from source before a\n  // manifest-promoted qualified key exists. If we already have exactly the\n  // requested package or a single unqualified registration for this class\n  // name, treat it as the same class instead of forcing node_modules manifest\n  // discovery.\n  if (isQualifiedName(name)) {\n    const { packageName, className } = parseQualifiedName(name);\n    const keys = registryKeysBySimpleName(className);\n\n    if (keys.length > 0) {\n      const exactPackageMatch = keys\n        .map((key) => classes.get(key))\n        .find((candidate) => candidate?.packageName === packageName);\n\n      if (exactPackageMatch) {\n        return exactPackageMatch;\n      }\n\n      if (keys.length === 1) {\n        const fallback = classes.get(keys[0]);\n        if (fallback && !fallback.packageName) {\n          return fallback;\n        }\n      }\n    }\n\n    return undefined;\n  }\n\n  // 3. Simple-name lookup\n  const keys = registryKeysBySimpleName(name);\n  if (keys.length > 0) {\n    if (keys.length === 1) {\n      return classes.get(keys[0]);\n    }\n    // Ambiguous — multiple packages define this class name\n    // Return first match but log a warning (use resolveType() for strict behavior)\n    verboseLog(\n      `[registry] findClass(\"${name}\") is ambiguous — ${keys.length} matches. ` +\n        `Use qualified name (e.g., ${keys[0]}) for precision.`,\n    );\n    return classes.get(keys[0]);\n  }\n\n  return undefined;\n}\n\n/**\n * Strict class lookup with package-aware disambiguation.\n *\n * Unlike `findClass()` which silently returns the first match when a simple\n * name is ambiguous, this method throws a `ConfigurationError` — making it\n * safe for inheritance-critical paths.\n *\n * @throws {ConfigurationError} When simple name is ambiguous and no package context resolves it\n * @see https://github.com/happyvertical/smrt/issues/1005\n */\nexport function findClassStrict(\n  name: string,\n  fromPackage?: string,\n): RegisteredClass | undefined {\n  const classes = getClasses();\n\n  // 1. Direct hit on classes map (fast path, works for qualified keys)\n  const registered = classes.get(name);\n  if (registered) {\n    return registered;\n  }\n\n  // 2. If input is a qualified name, no fallback — it's not found\n  if (isQualifiedName(name)) {\n    return undefined;\n  }\n\n  // 3. If fromPackage provided, try constructing qualified name for direct lookup\n  if (fromPackage) {\n    const qualifiedAttempt = createQualifiedName(fromPackage, name);\n    const byQualified = classes.get(qualifiedAttempt);\n    if (byQualified) {\n      return byQualified;\n    }\n  }\n\n  // 4. Simple-name lookup\n  const keys = registryKeysBySimpleName(name);\n  if (keys.length > 0) {\n    if (keys.length === 1) {\n      return classes.get(keys[0]);\n    }\n    // Ambiguous — multiple packages define this class name\n    // In strict mode, throw instead of silently returning first match\n    throw new ConfigurationError(\n      `Ambiguous class name \"${name}\" — found in ${keys.length} packages: ` +\n        `${keys.join(', ')}. ` +\n        `Use a qualified name (e.g., ${keys[0]}) to disambiguate.`,\n      'CONFIG_AMBIGUOUS_CLASS',\n      { className: name, candidates: keys },\n    );\n  }\n\n  return undefined;\n}\n\n/**\n * Qualify an `extends` value with the parent class's package name.\n *\n * @see https://github.com/happyvertical/smrt/issues/1004\n */\nexport function qualifyExtendsName(\n  extendsValue: string,\n  currentPackage: string,\n): string {\n  const classes = getClasses();\n\n  // Already qualified → pass through\n  if (isQualifiedName(extendsValue)) {\n    return extendsValue;\n  }\n\n  // Skip framework base classes (never registered with qualified names)\n  if (\n    extendsValue === 'SmrtObject' ||\n    extendsValue === 'SmrtClass' ||\n    extendsValue === 'SmrtCollection'\n  ) {\n    return extendsValue;\n  }\n\n  // Try same-package first (common case: child and parent in same package)\n  const samePackageQualified = createQualifiedName(\n    currentPackage,\n    extendsValue,\n  );\n  if (classes.has(samePackageQualified)) {\n    return samePackageQualified;\n  }\n\n  // The package's own manifest declares the parent but it is not registered\n  // yet (manifest entries register in file order, so a subclass can precede\n  // its base). It is still this package's class: another package's\n  // same-named registration must not become the parent (#3098).\n  const ownManifests = [\n    getManifestCache().get(currentPackage),\n    getLocalTestManifestCache(),\n    getTestManifestCache(),\n  ];\n  if (\n    ownManifests.some((manifest) => {\n      if (manifest?.packageName !== currentPackage) return false;\n      const entry = manifest.objects?.[samePackageQualified];\n      // An entry that itself extends this simple name is the subclass being\n      // registered (a same-named child of another package's base, e.g.\n      // support's ServiceTimeEntry), not a base of its own package.\n      const entryParent = entry?.extends?.split(':').pop();\n      return !!entry && entryParent !== extendsValue;\n    })\n  ) {\n    return samePackageQualified;\n  }\n\n  // Try to find the parent in any registered package\n  const keys = registryKeysBySimpleName(extendsValue);\n  if (keys.length === 1) {\n    return keys[0];\n  }\n\n  // Fallback: return unmodified (backward compat)\n  return extendsValue;\n}\n\n// ── Public lookup functions ─────────────────────────────────\n\n/**\n * Get a registered class by name (case-insensitive).\n */\nexport function getClass(name: string): RegisteredClass | undefined {\n  return findClass(name);\n}\n\n/**\n * Get a registered class by its constructor reference (O(1) WeakMap lookup).\n */\nexport function getClassByConstructor(\n  ctor: SmrtObjectConstructor,\n): RegisteredClass | undefined {\n  const registeredName = getConstructorIndex().get(ctor);\n  if (registeredName) {\n    return getClasses().get(registeredName);\n  }\n  return undefined;\n}\n\n/**\n * Get a registered class by its qualified name (O(1) direct lookup).\n */\nexport function getClassByQualifiedName(\n  qualifiedName: string,\n): RegisteredClass | undefined {\n  return getClasses().get(qualifiedName);\n}\n\n/**\n * Get a registered class by package name and class name.\n */\nexport function getClassInPackage(\n  packageName: string,\n  className: string,\n): RegisteredClass | undefined {\n  const qualifiedName = createQualifiedName(packageName, className);\n  return getClasses().get(qualifiedName);\n}\n\n/**\n * Find all registered classes with a given simple class name.\n */\nexport function findClassesByName(className: string): RegisteredClass[] {\n  // A source registration can retain its simple key while manifest hydration\n  // adds its canonical qualified key. Both aliases designate one class, so\n  // ambiguity means distinct RegisteredClass identities — which is what the\n  // index's per-name keys already are (one key per identity).\n  const classes = getClasses();\n  const matches: RegisteredClass[] = [];\n  for (const key of getSimpleNameIndex().get(className.toLowerCase()) ?? []) {\n    const registered = classes.get(key);\n    if (registered) {\n      matches.push(registered);\n    }\n  }\n  return matches;\n}\n\n/**\n * Resolve a short class name to its qualified name.\n * @throws {Error} If no class or ambiguous classes registered\n */\nexport function resolveType(shortName: string): QualifiedClassName {\n  // If already qualified, validate and return\n  if (shortName.includes(':') && shortName.startsWith('@')) {\n    const registered = getClassByQualifiedName(shortName as QualifiedClassName);\n    if (!registered) {\n      throw new Error(\n        `Class \"${shortName}\" is not registered. ` +\n          `Make sure the package is installed and the class is decorated with @smrt().`,\n      );\n    }\n    return shortName as QualifiedClassName;\n  }\n\n  // Find all classes with this short name\n  const matches = findClassesByName(shortName);\n\n  if (matches.length === 0) {\n    throw new Error(\n      `Class \"${shortName}\" is not registered. ` +\n        `Make sure the package is installed and the class is decorated with @smrt().`,\n    );\n  }\n\n  if (matches.length > 1) {\n    const packageList = matches.map((m) => `  - ${m.qualifiedName}`).join('\\n');\n    throw new Error(\n      `\"${shortName}\" is ambiguous. Found in multiple packages:\\n${packageList}\\n` +\n        `Use the fully qualified name instead.`,\n    );\n  }\n\n  return matches[0].qualifiedName as QualifiedClassName;\n}\n\n/**\n * Get all registered classes from a specific package.\n */\nexport function getClassesByPackage(\n  packageName: string,\n): Map<string, RegisteredClass> {\n  const result = new Map<string, RegisteredClass>();\n\n  for (const [name, registered] of getClasses().entries()) {\n    if (registered.packageName === packageName) {\n      result.set(name, registered);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Get all registered classes with a specific visibility level.\n */\nexport function getClassesByVisibility(\n  visibility: SmrtVisibility,\n): Map<string, RegisteredClass> {\n  const result = new Map<string, RegisteredClass>();\n\n  for (const [name, registered] of getClasses().entries()) {\n    const classVisibility = registered.visibility || 'public';\n    if (classVisibility === visibility) {\n      result.set(name, registered);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Get all public registered classes.\n */\nexport function getPublicClasses(): Map<string, RegisteredClass> {\n  return getClassesByVisibility('public');\n}\n\n/**\n * Get all registered classes.\n */\nexport function getAllClasses(): Map<string, RegisteredClass> {\n  return new Map(getClasses());\n}\n\n/**\n * Get class names (simple names, deduplicated).\n */\nexport function getClassNames(): string[] {\n  const names = Array.from(getClasses().values()).map((entry) => entry.name);\n  return Array.from(new Set(names));\n}\n\n/**\n * Get lookup names for every registered class without collapsing\n * cross-package simple-name collisions.\n *\n * Prefer each registration's qualified name when available, fall back to the\n * registry key, then to the simple class name for package-less registrations.\n * De-duplicates aliases that point to the same RegisteredClass object while\n * preserving distinct packages that intentionally share a simple class name.\n */\nexport function getQualifiedClassNames(): string[] {\n  const names: string[] = [];\n  const seenRegistrations = new Set<RegisteredClass>();\n  const seenNames = new Set<string>();\n\n  for (const [key, entry] of getClasses().entries()) {\n    if (seenRegistrations.has(entry)) {\n      continue;\n    }\n    seenRegistrations.add(entry);\n\n    const lookupName = entry.qualifiedName || key || entry.name;\n    if (seenNames.has(lookupName)) {\n      continue;\n    }\n\n    seenNames.add(lookupName);\n    names.push(lookupName);\n  }\n\n  return names;\n}\n\n/**\n * Check if a class is registered (case-insensitive).\n */\nexport function hasClass(name: string): boolean {\n  return findClass(name) !== undefined;\n}\n"],"mappings":"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"}
+{"version":3,"file":"name-resolver.js","names":[],"sources":["../../src/registry/name-resolver.ts"],"sourcesContent":["/**\n * Name resolution module for the SMRT ObjectRegistry.\n *\n * Handles class lookup, disambiguation, and qualified name resolution.\n * All functions operate on the shared globalThis state.\n *\n * Release B (#1133): classNameMap is gone — the eagerly-maintained\n * lowercase-simple-name → qualified-key[] index was removed in favor of\n * on-demand iteration over the `classes` Map. Production SMRT apps carry\n * a few hundred classes at most, so the linear scan is negligible and\n * removes an entire class of cache-sync bugs (#584, #847, #951).\n *\n * #3047: hydration resolves names per row, so the scan now runs once per\n * registry generation into a derived (never hand-maintained) index; see\n * `getSimpleNameIndex()` and `registry/generation.ts`.\n *\n * Extracted from registry.ts as part of issue #1006.\n * @see https://github.com/happyvertical/smrt/issues/1006\n * @see https://github.com/happyvertical/smrt/issues/1133\n */\n\nimport { ConfigurationError } from '../errors';\nimport {\n  getLocalTestManifestCache,\n  getManifestCache,\n  getTestManifestCache,\n} from '../manifest/store.js';\nimport type { QualifiedClassName, SmrtVisibility } from '../scanner/types.js';\nimport {\n  createQualifiedName,\n  isQualifiedName,\n  parseQualifiedName,\n} from '../utils/qualified-names.js';\nimport { getRegistryGeneration } from './generation';\nimport { resolveQualifiedNameAlias } from './qualified-name-aliases';\nimport { getClasses, getConstructorIndex, verboseLog } from './shared-state';\nimport type { RegisteredClass, SmrtObjectConstructor } from './types';\n\n// ── Simple-name iteration (replaces classNameMap reads) ─────────────\n\n/**\n * Return every registry key whose registered class has the given simple\n * name (case-insensitive). Replaces the old eagerly-maintained\n * `__smrtRegistryClassNameMap` lookup: we iterate `classes` instead.\n *\n * Cost is O(n) over the classes map; production SMRT apps hold low-\n * hundreds of entries so this is trivially fast. Returned keys preserve\n * insertion order, which makes the \"first match wins\" behavior of the old\n * map-based lookup deterministic in the same way.\n *\n * De-duplicates by RegisteredClass object identity so a class registered\n * under both a simple key and a promoted qualified key (a transitional\n * state during manifest merge) counts as a single entry — matching the\n * old classNameMap's behavior of storing each canonical qualified key once.\n * When that happens, the qualified key wins over the simple one.\n */\nfunction registryKeysBySimpleName(simpleName: string): string[] {\n  const keys = getSimpleNameIndex().get(simpleName.toLowerCase());\n  return keys ? [...keys] : [];\n}\n\n/**\n * Lower-cased simple name → registry keys, rebuilt once per registry\n * generation (#3047).\n *\n * #1133 removed an eagerly-maintained name index because every writer had to\n * keep it in sync. This one is derived, not maintained: it is rebuilt from\n * the `classes` map whenever the registry generation moves, and every\n * registry mutation bumps the generation (the map itself is\n * generation-tracked; in-place identity changes bump explicitly). Hydration\n * resolves names several times per row, so the O(registered classes) scan\n * per lookup dominated large result sets.\n */\nlet simpleNameIndex:\n  | {\n      generation: number;\n      classes: Map<string, RegisteredClass>;\n      keysByName: Map<string, string[]>;\n    }\n  | undefined;\n\nfunction getSimpleNameIndex(): Map<string, string[]> {\n  const classes = getClasses();\n  const generation = getRegistryGeneration();\n  if (\n    simpleNameIndex &&\n    simpleNameIndex.generation === generation &&\n    simpleNameIndex.classes === classes\n  ) {\n    return simpleNameIndex.keysByName;\n  }\n\n  const byName = new Map<string, Map<RegisteredClass, string>>();\n  for (const [key, value] of classes.entries()) {\n    const lower = value.name?.toLowerCase();\n    if (!lower) continue;\n\n    let seen = byName.get(lower);\n    if (!seen) {\n      seen = new Map<RegisteredClass, string>();\n      byName.set(lower, seen);\n    }\n\n    const existing = seen.get(value);\n    if (!existing) {\n      seen.set(value, key);\n      continue;\n    }\n\n    // Two keys for the same object: prefer the qualified form.\n    if (key.includes(':') && !existing.includes(':')) {\n      seen.set(value, key);\n    }\n  }\n\n  const keysByName = new Map<string, string[]>();\n  for (const [lower, seen] of byName) {\n    keysByName.set(lower, [...seen.values()]);\n  }\n  simpleNameIndex = { generation, classes, keysByName };\n  return keysByName;\n}\n\n// ── Lookup functions ────────────────────────────────────────\n\n/**\n * Check if a class is already registered (case-insensitive).\n * Returns the canonical name if found, undefined otherwise. Returns\n * undefined if the simple name is ambiguous across multiple packages.\n */\nexport function getCanonicalClassName(name: string): string | undefined {\n  const keys = registryKeysBySimpleName(name);\n  if (keys.length === 1) return keys[0];\n  // Zero matches, or ambiguous with >1 entries\n  return undefined;\n}\n\n/**\n * Check if a class exists by name (case-insensitive).\n */\nexport function hasClassCaseInsensitive(name: string): boolean {\n  return getSimpleNameIndex().has(name.toLowerCase());\n}\n\n/**\n * Helper for class lookup with qualified name support.\n *\n * Lookup priority:\n * 1. Direct hit on classes map (works for qualified names as keys)\n *    1b. A deprecated qualified name declared in a class's\n *        `previousQualifiedNames` resolves to that class (#3338)\n * 2. If input contains ':', prefer direct qualified lookup, then fall back\n *    to an exact/simple registration when runtime source imports registered\n *    the class before package-qualified promotion happened\n * 3. Simple-name iteration by lowercase\n *    - Unambiguous (1 match) → return it\n *    - Ambiguous (>1 matches) → log warning, return first\n */\nexport function findClass(\n  name: string,\n  source?: string,\n): RegisteredClass | undefined {\n  const classes = getClasses();\n\n  // 1. Direct hit on classes map (fast path, works for qualified keys)\n  const registered = classes.get(name);\n  if (registered) {\n    return registered;\n  }\n\n  // 1b. Deprecated qualified-name alias (#3338). Checked before the\n  // simple-name heuristics below: a declared alias is exact, and\n  // registration guarantees it never names a live class.\n  const aliased = resolveQualifiedNameAlias(name, source);\n  if (aliased) {\n    return aliased;\n  }\n\n  // 2. Qualified lookup fallback for source-registered classes.\n  // In workspace/dev mode a package can be imported from source before a\n  // manifest-promoted qualified key exists. If we already have exactly the\n  // requested package or a single unqualified registration for this class\n  // name, treat it as the same class instead of forcing node_modules manifest\n  // discovery.\n  if (isQualifiedName(name)) {\n    const { packageName, className } = parseQualifiedName(name);\n    const keys = registryKeysBySimpleName(className);\n\n    if (keys.length > 0) {\n      const exactPackageMatch = keys\n        .map((key) => classes.get(key))\n        .find((candidate) => candidate?.packageName === packageName);\n\n      if (exactPackageMatch) {\n        return exactPackageMatch;\n      }\n\n      if (keys.length === 1) {\n        const fallback = classes.get(keys[0]);\n        if (fallback && !fallback.packageName) {\n          return fallback;\n        }\n      }\n    }\n\n    return undefined;\n  }\n\n  // 3. Simple-name lookup\n  const keys = registryKeysBySimpleName(name);\n  if (keys.length > 0) {\n    if (keys.length === 1) {\n      return classes.get(keys[0]);\n    }\n    // Ambiguous — multiple packages define this class name\n    // Return first match but log a warning (use resolveType() for strict behavior)\n    verboseLog(\n      `[registry] findClass(\"${name}\") is ambiguous — ${keys.length} matches. ` +\n        `Use qualified name (e.g., ${keys[0]}) for precision.`,\n    );\n    return classes.get(keys[0]);\n  }\n\n  return undefined;\n}\n\n/**\n * Strict class lookup with package-aware disambiguation.\n *\n * Unlike `findClass()` which silently returns the first match when a simple\n * name is ambiguous, this method throws a `ConfigurationError` — making it\n * safe for inheritance-critical paths.\n *\n * @throws {ConfigurationError} When simple name is ambiguous and no package context resolves it\n * @see https://github.com/happyvertical/smrt/issues/1005\n */\nexport function findClassStrict(\n  name: string,\n  fromPackage?: string,\n): RegisteredClass | undefined {\n  const classes = getClasses();\n\n  // 1. Direct hit on classes map (fast path, works for qualified keys)\n  const registered = classes.get(name);\n  if (registered) {\n    return registered;\n  }\n\n  // 2. If input is a qualified name, the only fallback is a declared\n  // deprecated alias (#3338) — never a simple-name guess.\n  if (isQualifiedName(name)) {\n    return resolveQualifiedNameAlias(name);\n  }\n\n  // 3. If fromPackage provided, try constructing qualified name for direct lookup\n  if (fromPackage) {\n    const qualifiedAttempt = createQualifiedName(fromPackage, name);\n    const byQualified = classes.get(qualifiedAttempt);\n    if (byQualified) {\n      return byQualified;\n    }\n  }\n\n  // 4. Simple-name lookup\n  const keys = registryKeysBySimpleName(name);\n  if (keys.length > 0) {\n    if (keys.length === 1) {\n      return classes.get(keys[0]);\n    }\n    // Ambiguous — multiple packages define this class name\n    // In strict mode, throw instead of silently returning first match\n    throw new ConfigurationError(\n      `Ambiguous class name \"${name}\" — found in ${keys.length} packages: ` +\n        `${keys.join(', ')}. ` +\n        `Use a qualified name (e.g., ${keys[0]}) to disambiguate.`,\n      'CONFIG_AMBIGUOUS_CLASS',\n      { className: name, candidates: keys },\n    );\n  }\n\n  return undefined;\n}\n\n/**\n * Qualify an `extends` value with the parent class's package name.\n *\n * @see https://github.com/happyvertical/smrt/issues/1004\n */\nexport function qualifyExtendsName(\n  extendsValue: string,\n  currentPackage: string,\n): string {\n  const classes = getClasses();\n\n  // Already qualified → pass through\n  if (isQualifiedName(extendsValue)) {\n    return extendsValue;\n  }\n\n  // Skip framework base classes (never registered with qualified names)\n  if (\n    extendsValue === 'SmrtObject' ||\n    extendsValue === 'SmrtClass' ||\n    extendsValue === 'SmrtCollection'\n  ) {\n    return extendsValue;\n  }\n\n  // Try same-package first (common case: child and parent in same package)\n  const samePackageQualified = createQualifiedName(\n    currentPackage,\n    extendsValue,\n  );\n  if (classes.has(samePackageQualified)) {\n    return samePackageQualified;\n  }\n\n  // The package's own manifest declares the parent but it is not registered\n  // yet (manifest entries register in file order, so a subclass can precede\n  // its base). It is still this package's class: another package's\n  // same-named registration must not become the parent (#3098).\n  const ownManifests = [\n    getManifestCache().get(currentPackage),\n    getLocalTestManifestCache(),\n    getTestManifestCache(),\n  ];\n  if (\n    ownManifests.some((manifest) => {\n      if (manifest?.packageName !== currentPackage) return false;\n      const entry = manifest.objects?.[samePackageQualified];\n      // An entry that itself extends this simple name is the subclass being\n      // registered (a same-named child of another package's base, e.g.\n      // support's ServiceTimeEntry), not a base of its own package.\n      const entryParent = entry?.extends?.split(':').pop();\n      return !!entry && entryParent !== extendsValue;\n    })\n  ) {\n    return samePackageQualified;\n  }\n\n  // Try to find the parent in any registered package\n  const keys = registryKeysBySimpleName(extendsValue);\n  if (keys.length === 1) {\n    return keys[0];\n  }\n\n  // Fallback: return unmodified (backward compat)\n  return extendsValue;\n}\n\n// ── Public lookup functions ─────────────────────────────────\n\n/**\n * Get a registered class by name (case-insensitive).\n */\nexport function getClass(name: string): RegisteredClass | undefined {\n  return findClass(name);\n}\n\n/**\n * Get a registered class by its constructor reference (O(1) WeakMap lookup).\n */\nexport function getClassByConstructor(\n  ctor: SmrtObjectConstructor,\n): RegisteredClass | undefined {\n  const registeredName = getConstructorIndex().get(ctor);\n  if (registeredName) {\n    return getClasses().get(registeredName);\n  }\n  return undefined;\n}\n\n/**\n * Get a registered class by its qualified name (O(1) direct lookup).\n *\n * A deprecated qualified name declared in a class's `previousQualifiedNames`\n * resolves to that class with a one-time deprecation warning naming\n * `source` (#3338).\n */\nexport function getClassByQualifiedName(\n  qualifiedName: string,\n  source?: string,\n): RegisteredClass | undefined {\n  return (\n    getClasses().get(qualifiedName) ??\n    resolveQualifiedNameAlias(qualifiedName, source)\n  );\n}\n\n/**\n * Get a registered class by package name and class name.\n */\nexport function getClassInPackage(\n  packageName: string,\n  className: string,\n): RegisteredClass | undefined {\n  const qualifiedName = createQualifiedName(packageName, className);\n  return getClassByQualifiedName(qualifiedName);\n}\n\n/**\n * Find all registered classes with a given simple class name.\n */\nexport function findClassesByName(className: string): RegisteredClass[] {\n  // A source registration can retain its simple key while manifest hydration\n  // adds its canonical qualified key. Both aliases designate one class, so\n  // ambiguity means distinct RegisteredClass identities — which is what the\n  // index's per-name keys already are (one key per identity).\n  const classes = getClasses();\n  const matches: RegisteredClass[] = [];\n  for (const key of getSimpleNameIndex().get(className.toLowerCase()) ?? []) {\n    const registered = classes.get(key);\n    if (registered) {\n      matches.push(registered);\n    }\n  }\n  return matches;\n}\n\n/**\n * Resolve a short class name to its qualified name.\n * @throws {Error} If no class or ambiguous classes registered\n */\nexport function resolveType(shortName: string): QualifiedClassName {\n  // If already qualified, validate and return\n  if (shortName.includes(':') && shortName.startsWith('@')) {\n    const registered = getClassByQualifiedName(shortName as QualifiedClassName);\n    if (!registered) {\n      throw new Error(\n        `Class \"${shortName}\" is not registered. ` +\n          `Make sure the package is installed and the class is decorated with @smrt().`,\n      );\n    }\n    // A deprecated alias resolves to the class's CURRENT name (#3338).\n    return (registered.qualifiedName ?? shortName) as QualifiedClassName;\n  }\n\n  // Find all classes with this short name\n  const matches = findClassesByName(shortName);\n\n  if (matches.length === 0) {\n    throw new Error(\n      `Class \"${shortName}\" is not registered. ` +\n        `Make sure the package is installed and the class is decorated with @smrt().`,\n    );\n  }\n\n  if (matches.length > 1) {\n    const packageList = matches.map((m) => `  - ${m.qualifiedName}`).join('\\n');\n    throw new Error(\n      `\"${shortName}\" is ambiguous. Found in multiple packages:\\n${packageList}\\n` +\n        `Use the fully qualified name instead.`,\n    );\n  }\n\n  return matches[0].qualifiedName as QualifiedClassName;\n}\n\n/**\n * Get all registered classes from a specific package.\n */\nexport function getClassesByPackage(\n  packageName: string,\n): Map<string, RegisteredClass> {\n  const result = new Map<string, RegisteredClass>();\n\n  for (const [name, registered] of getClasses().entries()) {\n    if (registered.packageName === packageName) {\n      result.set(name, registered);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Get all registered classes with a specific visibility level.\n */\nexport function getClassesByVisibility(\n  visibility: SmrtVisibility,\n): Map<string, RegisteredClass> {\n  const result = new Map<string, RegisteredClass>();\n\n  for (const [name, registered] of getClasses().entries()) {\n    const classVisibility = registered.visibility || 'public';\n    if (classVisibility === visibility) {\n      result.set(name, registered);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Get all public registered classes.\n */\nexport function getPublicClasses(): Map<string, RegisteredClass> {\n  return getClassesByVisibility('public');\n}\n\n/**\n * Get all registered classes.\n */\nexport function getAllClasses(): Map<string, RegisteredClass> {\n  return new Map(getClasses());\n}\n\n/**\n * Get class names (simple names, deduplicated).\n */\nexport function getClassNames(): string[] {\n  const names = Array.from(getClasses().values()).map((entry) => entry.name);\n  return Array.from(new Set(names));\n}\n\n/**\n * Get lookup names for every registered class without collapsing\n * cross-package simple-name collisions.\n *\n * Prefer each registration's qualified name when available, fall back to the\n * registry key, then to the simple class name for package-less registrations.\n * De-duplicates aliases that point to the same RegisteredClass object while\n * preserving distinct packages that intentionally share a simple class name.\n */\nexport function getQualifiedClassNames(): string[] {\n  const names: string[] = [];\n  const seenRegistrations = new Set<RegisteredClass>();\n  const seenNames = new Set<string>();\n\n  for (const [key, entry] of getClasses().entries()) {\n    if (seenRegistrations.has(entry)) {\n      continue;\n    }\n    seenRegistrations.add(entry);\n\n    const lookupName = entry.qualifiedName || key || entry.name;\n    if (seenNames.has(lookupName)) {\n      continue;\n    }\n\n    seenNames.add(lookupName);\n    names.push(lookupName);\n  }\n\n  return names;\n}\n\n/**\n * Check if a class is registered (case-insensitive).\n */\nexport function hasClass(name: string): boolean {\n  return findClass(name) !== undefined;\n}\n"],"mappings":"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"}

package/dist/registry/qualified-name-aliases.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Deprecated qualified-name aliases (#3338).
+ *
+ * A class that moves package (or is renamed) changes its qualified name, and
+ * every persisted or declared reference to the old name — a polymorphic
+ * `metaType`, a `@crossPackageRef` target, a playbook `model:` — would stop
+ * resolving silently. `@smrt({ previousQualifiedNames })` declares the old
+ * names; this module turns them into lookup bridges.
+ *
+ * An alias is never a registry key. The `classes` map — and so
+ * `getAllClasses()`, schema/DDL, MCP, CLI and REST generation, and every other
+ * iteration — still holds exactly one entry per class. Qualified-name lookups
+ * consult the derived alias index only after a direct miss, so a live class
+ * always wins and an alias can never shadow one; registration refuses the
+ * collisions that would make that ambiguous.
+ *
+ * Like the simple-name index in `name-resolver.ts`, the alias index is
+ * derived, not maintained: it is rebuilt from `classes` once per registry
+ * generation (#3047).
+ */
+import type { SmartObjectManifest } from '../scanner/types.js';
+import type { RegisteredClass } from './types';
+export { isQualifiedNameAliasFormat, readPreviousQualifiedNames, } from '../utils/qualified-names.js';
+/** Error code for an alias that collides with a live class or another alias. */
+export declare const QUALIFIED_NAME_ALIAS_COLLISION = "CONFIG_QUALIFIED_NAME_ALIAS_COLLISION";
+/** Error code for a malformed `previousQualifiedNames` declaration. */
+export declare const QUALIFIED_NAME_ALIAS_INVALID = "CONFIG_QUALIFIED_NAME_ALIAS_INVALID";
+/** Diagnostic code recorded (once per alias) when a lookup uses an old name. */
+export declare const QUALIFIED_NAME_ALIAS_DEPRECATED = "QUALIFIED_NAME_ALIAS_DEPRECATED";
+declare global {
+    var __smrtRegistryWarnedQualifiedNameAliases: Set<string> | undefined;
+}
+/** Forget which aliases already warned (`ObjectRegistry.clear()`, tests). */
+export declare function resetQualifiedNameAliasWarnings(): void;
+/**
+ * The class a deprecated qualified name now resolves to, WITHOUT warning.
+ * Returns `undefined` for live names and unknown names alike.
+ */
+export declare function lookupQualifiedNameAlias(name: string): RegisteredClass | undefined;
+/**
+ * Resolve a deprecated qualified name to its current class, logging the
+ * one-time deprecation warning. `source` names the resolution site for that
+ * warning (e.g. `SmrtPolymorphicAssociation.hydrate`).
+ */
+export declare function resolveQualifiedNameAlias(name: string, source?: string): RegisteredClass | undefined;
+/**
+ * Warn — once per old name per process — that a lookup used a deprecated
+ * qualified name. Also recorded as a `warn` registry diagnostic so apps and
+ * tests can inspect it through `ObjectRegistry.getDiagnostics()`.
+ */
+export declare function warnDeprecatedQualifiedName(alias: string, current: string, source: string): void;
+/** Every declared alias → its class's current qualified name, sorted. */
+export declare function getQualifiedNameAliasMap(): Map<string, string>;
+/**
+ * Refuse a registration whose aliases would make a qualified name resolve to
+ * two classes. Called before a class is stored in `classes` — and, for an
+ * update of a live entry, with the PROPOSED entry and `replacing` set to the
+ * live one, before anything is mutated, so a refused update changes nothing.
+ *
+ * - every alias is a scoped `@scope/package:ClassName` string, distinct from the
+ *   class's own name, and declared once;
+ * - no alias is the key of a different live class;
+ * - no alias is also declared by a different class;
+ * - the class's own name is not another class's alias.
+ *
+ * @throws {ConfigurationError} `CONFIG_QUALIFIED_NAME_ALIAS_INVALID` or
+ *   `CONFIG_QUALIFIED_NAME_ALIAS_COLLISION`.
+ */
+export declare function assertQualifiedNameAliasesAvailable(registrationKey: string, entry: RegisteredClass, replacing?: RegisteredClass): void;
+/**
+ * What a set of manifests says about qualified names (#3338): which classes
+ * claim each old name, and which qualified names the manifests DEFINE as
+ * classes of their own (installed but possibly unregistered).
+ */
+export interface ManifestAliasInventory {
+    /** Old name → distinct current names claiming it. */
+    claims: Map<string, Set<string>>;
+    /** Every qualified name a manifest defines as a class. */
+    defined: Set<string>;
+}
+/**
+ * Index `manifests` (one manifest may appear twice, e.g. cached and static;
+ * the same class claiming twice is one claim). A re-exported constructor is
+ * not a definition: manifests list only classes a package declares.
+ */
+export declare function collectManifestAliasInventory(manifests: Iterable<SmartObjectManifest | null | undefined>): ManifestAliasInventory;
+/**
+ * THE manifest rule for old names (#3338). Throws when any of `aliases`:
+ *
+ * - is defined as a class by a manifest in `inventory` — an installed
+ *   (possibly stale) package still ships the old class, so the old name is
+ *   live, not deprecated;
+ * - is claimed by a class other than `owner` (or, with no `owner`, by more
+ *   than one class).
+ *
+ * @throws {ConfigurationError} `CONFIG_QUALIFIED_NAME_ALIAS_COLLISION`
+ */
+export declare function assertNoCompetingManifestClaims(aliases: Iterable<string>, inventory: ManifestAliasInventory, owner?: string): void;
+/**
+ * The single current owner of `alias` in an inventory, or `undefined` —
+ * also when a manifest defines `alias` as a class of its own.
+ * Two distinct claimants are refused rather than resolved first-match: an
+ * old name can resolve to only one class, on the lazy path as on the eager
+ * one.
+ *
+ * @throws {ConfigurationError} `CONFIG_QUALIFIED_NAME_ALIAS_COLLISION`
+ */
+export declare function resolveManifestQualifiedNameAlias(inventory: ManifestAliasInventory, alias: string): string | undefined;
+//# sourceMappingURL=qualified-name-aliases.d.ts.map

package/dist/registry/qualified-name-aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qualified-name-aliases.d.ts","sourceRoot":"","sources":["../../src/registry/qualified-name-aliases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAUH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAQ/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,6BAA6B,CAAC;AAErC,gFAAgF;AAChF,eAAO,MAAM,8BAA8B,0CACF,CAAC;AAE1C,uEAAuE;AACvE,eAAO,MAAM,4BAA4B,wCACF,CAAC;AAExC,gFAAgF;AAChF,eAAO,MAAM,+BAA+B,oCACT,CAAC;AAIpC,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,wCAAwC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;CACvE;AASD,6EAA6E;AAC7E,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AAyDD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,GACX,eAAe,GAAG,SAAS,CAG7B;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,MAAM,SAAyC,GAC9C,eAAe,GAAG,SAAS,CAU7B;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,IAAI,CAcN;AAED,yEAAyE;AACzE,wBAAgB,wBAAwB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAO9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mCAAmC,CACjD,eAAe,EAAE,MAAM,EACvB,KAAK,EAAE,eAAe,EACtB,SAAS,CAAC,EAAE,eAAe,GAC1B,IAAI,CAmGN;AAyBD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACjC,0DAA0D;IAC1D,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,QAAQ,CAAC,mBAAmB,GAAG,IAAI,GAAG,SAAS,CAAC,GAC1D,sBAAsB,CAmBxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,EACzB,SAAS,EAAE,sBAAsB,EACjC,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAsBN;AAYD;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,sBAAsB,EACjC,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,SAAS,CAKpB"}

package/dist/registry/qualified-name-aliases.js

@@ -0,0 +1,286 @@
+import { ConfigurationError } from "../errors.js";
+import { getRegistryGeneration } from "./generation.js";
+import { isQualifiedNameAliasFormat, readPreviousQualifiedNames } from "../utils/qualified-names.js";
+import { getClasses } from "./shared-state.js";
+import { recordRegistryDiagnostic } from "./diagnostics.js";
+import { getLocalTestManifestCache, getManifestCache, getStaticManifestCache, getTestManifestCache } from "../manifest/store.js";
+import { createLogger } from "@happyvertical/logger";
+//#region src/registry/qualified-name-aliases.ts
+/**
+* Deprecated qualified-name aliases (#3338).
+*
+* A class that moves package (or is renamed) changes its qualified name, and
+* every persisted or declared reference to the old name — a polymorphic
+* `metaType`, a `@crossPackageRef` target, a playbook `model:` — would stop
+* resolving silently. `@smrt({ previousQualifiedNames })` declares the old
+* names; this module turns them into lookup bridges.
+*
+* An alias is never a registry key. The `classes` map — and so
+* `getAllClasses()`, schema/DDL, MCP, CLI and REST generation, and every other
+* iteration — still holds exactly one entry per class. Qualified-name lookups
+* consult the derived alias index only after a direct miss, so a live class
+* always wins and an alias can never shadow one; registration refuses the
+* collisions that would make that ambiguous.
+*
+* Like the simple-name index in `name-resolver.ts`, the alias index is
+* derived, not maintained: it is rebuilt from `classes` once per registry
+* generation (#3047).
+*/
+/** Error code for an alias that collides with a live class or another alias. */
+var QUALIFIED_NAME_ALIAS_COLLISION = "CONFIG_QUALIFIED_NAME_ALIAS_COLLISION";
+/** Error code for a malformed `previousQualifiedNames` declaration. */
+var QUALIFIED_NAME_ALIAS_INVALID = "CONFIG_QUALIFIED_NAME_ALIAS_INVALID";
+/** Diagnostic code recorded (once per alias) when a lookup uses an old name. */
+var QUALIFIED_NAME_ALIAS_DEPRECATED = "QUALIFIED_NAME_ALIAS_DEPRECATED";
+var logger = createLogger({ level: "info" });
+function getWarnedAliases() {
+	if (!globalThis.__smrtRegistryWarnedQualifiedNameAliases) globalThis.__smrtRegistryWarnedQualifiedNameAliases = /* @__PURE__ */ new Set();
+	return globalThis.__smrtRegistryWarnedQualifiedNameAliases;
+}
+/** Forget which aliases already warned (`ObjectRegistry.clear()`, tests). */
+function resetQualifiedNameAliasWarnings() {
+	getWarnedAliases().clear();
+}
+/**
+* Two registrations describe the same class: one object, one constructor, or
+* one qualified name (a manifest stub later replaced by its real class, or
+* an HMR reload).
+*/
+function sameClass(left, right) {
+	return left === right || left.constructor === right.constructor || !!left.qualifiedName && left.qualifiedName === right.qualifiedName;
+}
+function ownName(entry, registrationKey) {
+	return entry.qualifiedName ?? registrationKey ?? entry.name;
+}
+var aliasIndex;
+/** Alias → registered class, rebuilt once per registry generation. */
+function getAliasIndex() {
+	const classes = getClasses();
+	const generation = getRegistryGeneration();
+	if (aliasIndex && aliasIndex.generation === generation && aliasIndex.classes === classes) return aliasIndex.byAlias;
+	const byAlias = /* @__PURE__ */ new Map();
+	for (const [key, entry] of classes) for (const alias of readPreviousQualifiedNames(entry.config)) {
+		if (classes.has(alias)) continue;
+		const existing = byAlias.get(alias);
+		if (!existing || sameClass(existing, entry) && key.includes(":")) byAlias.set(alias, entry);
+	}
+	aliasIndex = {
+		generation,
+		classes,
+		byAlias
+	};
+	return byAlias;
+}
+/**
+* The class a deprecated qualified name now resolves to, WITHOUT warning.
+* Returns `undefined` for live names and unknown names alike.
+*/
+function lookupQualifiedNameAlias(name) {
+	if (!name.includes(":")) return void 0;
+	return getAliasIndex().get(name);
+}
+/**
+* Resolve a deprecated qualified name to its current class, logging the
+* one-time deprecation warning. `source` names the resolution site for that
+* warning (e.g. `SmrtPolymorphicAssociation.hydrate`).
+*/
+function resolveQualifiedNameAlias(name, source = "ObjectRegistry qualified-name lookup") {
+	const registered = lookupQualifiedNameAlias(name);
+	if (registered) warnDeprecatedQualifiedName(name, registered.qualifiedName ?? registered.name, source);
+	return registered;
+}
+/**
+* Warn — once per old name per process — that a lookup used a deprecated
+* qualified name. Also recorded as a `warn` registry diagnostic so apps and
+* tests can inspect it through `ObjectRegistry.getDiagnostics()`.
+*/
+function warnDeprecatedQualifiedName(alias, current, source) {
+	const warned = getWarnedAliases();
+	if (warned.has(alias)) return;
+	warned.add(alias);
+	const message = `Qualified name "${alias}" is deprecated; it now resolves to "${current}" (resolved from ${source}). Store and declare "${current}" instead — the alias will be removed in a later breaking release. \`smrt doctor --db\` counts stored references that still use it.`;
+	const context = {
+		alias,
+		current,
+		source
+	};
+	recordRegistryDiagnostic("warn", QUALIFIED_NAME_ALIAS_DEPRECATED, message, { ...context });
+	logger.warn(`[smrt:${QUALIFIED_NAME_ALIAS_DEPRECATED}] ${message}`, context);
+}
+/** Every declared alias → its class's current qualified name, sorted. */
+function getQualifiedNameAliasMap() {
+	const entries = [...getAliasIndex()].map(([alias, registered]) => [alias, registered.qualifiedName ?? registered.name]);
+	entries.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+	return new Map(entries);
+}
+/**
+* Refuse a registration whose aliases would make a qualified name resolve to
+* two classes. Called before a class is stored in `classes` — and, for an
+* update of a live entry, with the PROPOSED entry and `replacing` set to the
+* live one, before anything is mutated, so a refused update changes nothing.
+*
+* - every alias is a scoped `@scope/package:ClassName` string, distinct from the
+*   class's own name, and declared once;
+* - no alias is the key of a different live class;
+* - no alias is also declared by a different class;
+* - the class's own name is not another class's alias.
+*
+* @throws {ConfigurationError} `CONFIG_QUALIFIED_NAME_ALIAS_INVALID` or
+*   `CONFIG_QUALIFIED_NAME_ALIAS_COLLISION`.
+*/
+function assertQualifiedNameAliasesAvailable(registrationKey, entry, replacing) {
+	const self = ownName(entry, registrationKey);
+	const declared = entry.config?.previousQualifiedNames;
+	if (declared !== void 0 && !Array.isArray(declared)) throw new ConfigurationError(`${self}: previousQualifiedNames must be an array of qualified names ("@package/name:ClassName").`, QUALIFIED_NAME_ALIAS_INVALID, {
+		className: self,
+		previousQualifiedNames: declared
+	});
+	const aliases = declared ?? [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const alias of aliases) {
+		if (!isQualifiedNameAliasFormat(alias)) throw new ConfigurationError(`${self}: previousQualifiedNames entry ${JSON.stringify(alias)} is not a qualified name ("@package/name:ClassName").`, QUALIFIED_NAME_ALIAS_INVALID, {
+			className: self,
+			alias
+		});
+		if (alias === self) throw new ConfigurationError(`${self}: previousQualifiedNames lists the class's own current name "${alias}".`, QUALIFIED_NAME_ALIAS_INVALID, {
+			className: self,
+			alias
+		});
+		if (alias === registrationKey) throw collision(`${self} declares previousQualifiedNames "${alias}", but a class is being registered under "${alias}". An alias may only name a class that no longer exists; remove the alias or the stale class/manifest.`, {
+			className: self,
+			alias
+		});
+		if (seen.has(alias)) throw new ConfigurationError(`${self}: previousQualifiedNames lists "${alias}" more than once.`, QUALIFIED_NAME_ALIAS_INVALID, {
+			className: self,
+			alias
+		});
+		seen.add(alias);
+	}
+	const classes = getClasses();
+	const identities = (other, key) => [
+		ownName(other, key),
+		key,
+		...other.packageName ? [`${other.packageName}:${other.name}`] : []
+	];
+	const selfIdentities = new Set(identities(entry, registrationKey));
+	for (const [key, other] of classes) {
+		if (other === replacing || sameClass(other, entry)) continue;
+		const otherName = ownName(other, key);
+		for (const identity of identities(other, key)) if (seen.has(identity)) throw collision(`${self} declares previousQualifiedNames "${identity}", but "${identity}" is a live registered class. An alias may only name a class that no longer exists; remove the alias or the stale class/manifest.`, {
+			className: self,
+			alias: identity,
+			liveClass: otherName
+		});
+		const otherAliases = readPreviousQualifiedNames(other.config);
+		if (otherAliases.length === 0) continue;
+		for (const alias of otherAliases) {
+			if (seen.has(alias)) throw collision(`previousQualifiedNames "${alias}" is declared by both ${self} and ${otherName}; an old name can resolve to only one class.`, {
+				className: self,
+				alias,
+				otherClass: otherName
+			});
+			if (selfIdentities.has(alias)) throw collision(`${otherName} declares previousQualifiedNames "${alias}", but ${self} is registered under that name. An alias may only name a class that no longer exists; remove the alias or the stale class/manifest.`, {
+				className: self,
+				alias,
+				otherClass: otherName
+			});
+		}
+	}
+	if (seen.size > 0) assertNoCompetingManifestClaims(seen, collectManifestAliasInventory(loadedManifests()), entry.qualifiedName ?? self);
+}
+function collision(message, details) {
+	return new ConfigurationError(message, QUALIFIED_NAME_ALIAS_COLLISION, details);
+}
+/** The current qualified name a manifest object registers under. */
+function manifestObjectQualifiedName(manifest, key, objectDef) {
+	if (objectDef.qualifiedName) return objectDef.qualifiedName;
+	if (key.includes(":")) return key;
+	const packageName = objectDef.packageName ?? manifest.packageName;
+	return packageName ? `${packageName}:${objectDef.className}` : void 0;
+}
+/**
+* Index `manifests` (one manifest may appear twice, e.g. cached and static;
+* the same class claiming twice is one claim). A re-exported constructor is
+* not a definition: manifests list only classes a package declares.
+*/
+function collectManifestAliasInventory(manifests) {
+	const claims = /* @__PURE__ */ new Map();
+	const defined = /* @__PURE__ */ new Set();
+	for (const manifest of manifests) {
+		if (!manifest?.objects) continue;
+		for (const [key, objectDef] of Object.entries(manifest.objects)) {
+			const current = manifestObjectQualifiedName(manifest, key, objectDef);
+			if (!current) continue;
+			defined.add(current);
+			for (const alias of readPreviousQualifiedNames(objectDef?.decoratorConfig)) {
+				const owners = claims.get(alias) ?? /* @__PURE__ */ new Set();
+				owners.add(current);
+				claims.set(alias, owners);
+			}
+		}
+	}
+	return {
+		claims,
+		defined
+	};
+}
+/**
+* THE manifest rule for old names (#3338). Throws when any of `aliases`:
+*
+* - is defined as a class by a manifest in `inventory` — an installed
+*   (possibly stale) package still ships the old class, so the old name is
+*   live, not deprecated;
+* - is claimed by a class other than `owner` (or, with no `owner`, by more
+*   than one class).
+*
+* @throws {ConfigurationError} `CONFIG_QUALIFIED_NAME_ALIAS_COLLISION`
+*/
+function assertNoCompetingManifestClaims(aliases, inventory, owner) {
+	for (const alias of aliases) {
+		if (inventory.defined.has(alias)) {
+			const claimants = [...inventory.claims.get(alias) ?? []];
+			if (owner && !claimants.includes(owner)) claimants.push(owner);
+			throw collision(`previousQualifiedNames "${alias}" is still defined as a class by an installed manifest (claimed by ${claimants.sort().join(", ") || "no class"}). An alias may only name a class that no longer exists; remove the stale package/manifest or the alias.`, {
+				alias,
+				claimants: claimants.sort(),
+				definedByManifest: true
+			});
+		}
+		const owners = new Set(inventory.claims.get(alias) ?? []);
+		if (owner) owners.add(owner);
+		if (owners.size > 1) {
+			const sorted = [...owners].sort();
+			throw collision(`previousQualifiedNames "${alias}" is declared by more than one class across installed manifests (${sorted.join(", ")}); an old name can resolve to only one class.`, {
+				alias,
+				claimants: sorted
+			});
+		}
+	}
+}
+/** Every manifest this process has loaded (package, static, test caches). */
+function loadedManifests() {
+	return [
+		...getManifestCache().values(),
+		getStaticManifestCache(),
+		getTestManifestCache(),
+		getLocalTestManifestCache()
+	];
+}
+/**
+* The single current owner of `alias` in an inventory, or `undefined` —
+* also when a manifest defines `alias` as a class of its own.
+* Two distinct claimants are refused rather than resolved first-match: an
+* old name can resolve to only one class, on the lazy path as on the eager
+* one.
+*
+* @throws {ConfigurationError} `CONFIG_QUALIFIED_NAME_ALIAS_COLLISION`
+*/
+function resolveManifestQualifiedNameAlias(inventory, alias) {
+	if (inventory.defined.has(alias)) return void 0;
+	assertNoCompetingManifestClaims([alias], inventory);
+	return [...inventory.claims.get(alias) ?? []][0];
+}
+//#endregion
+export { QUALIFIED_NAME_ALIAS_COLLISION, QUALIFIED_NAME_ALIAS_DEPRECATED, QUALIFIED_NAME_ALIAS_INVALID, assertNoCompetingManifestClaims, assertQualifiedNameAliasesAvailable, collectManifestAliasInventory, getQualifiedNameAliasMap, lookupQualifiedNameAlias, readPreviousQualifiedNames, resetQualifiedNameAliasWarnings, resolveManifestQualifiedNameAlias, resolveQualifiedNameAlias, warnDeprecatedQualifiedName };
+
+//# sourceMappingURL=qualified-name-aliases.js.map