lyng/lynglib/docs/lynon_class_resolution.md

Lynon class-name resolution: current behavior and roadmap for fully-qualified names

Current behavior (as of Dec 2025)

• The Lynon encoder writes the class name for user-defined objects as a simple name taken from obj.objClass.classNameObj (e.g., "Vault"). It does not encode the fully-qualified path (e.g., "ns.sub.Vault").
• During decoding, LynonDecoder.decodeClassObj must resolve this simple name to an ObjClass using the provided Scope.
• Historically, decodeClassObj relied only on scope.get(name). In some scopes this missed symbols that were import-visible at compile time, while scope.eval(name) could still find them. This mismatch caused occasional failures such as:
  • scope.eval("Vault") ← returns ObjClass
  • scope.get("Vault") ← returns null

To address this, the decoder now uses a robust, import-aware resolution strategy:

1. Try scope.get(name)
2. Try scope.chainLookupWithMembers(name)
3. Find the nearest ModuleScope and check its locals and its parent/root locals/members
4. Check scope.currentImportProvider.rootScope globals (e.g., stdlib)
5. As a last resort, try scope.eval(name) and validate the result is an ObjClass

This resolves the previously observed mismatch, including simple names like "Vault" defined in modules or visible via imports.

Notes:

• Tests confirm that the simple-name path is stable after this change.
• Tests for fully qualified names were avoided because the encoder does not currently emit qualified names, and runtime namespaces (like a value-bound ns) are not guaranteed to exist for eval("ns.sub.Vault") in all scopes.

Limitations

• Decoder receives only simple names. If two different classes with the same simple name exist in different packages/modules, decoding could be ambiguous unless the surrounding scope makes the intended one discoverable.
• Using eval as last fallback implies compilation at decode-time in rare cases. While this is robust, a purely structural resolution is preferable for determinism and performance.

Roadmap: support fully-qualified class names

If/when we decide to encode fully-qualified names, we should implement both encoder and decoder changes in lockstep.

Proposed plan:

1. Encoder changes

   • When serializing a user-defined object, emit the fully-qualified class path (e.g., "ns.sub.Vault") alongside or instead of the simple class name.
   • Consider a feature flag or versioning in Lynon type records to maintain backward compatibility with existing streams that carry only the simple name.

2. Decoder changes

   • If the encoded name contains dots, treat it as a dotted path. Implement a path resolver that:
     • Splits the name by . into segments: [ns, sub, Vault].
     • Resolves the first segment with the same multi-scope strategy used today for simple names (steps 1–4 above), without relying on eval.
     • For remaining segments, traverse members/namespace tables:
       • If the current object is an ObjNamespace or similar container, look up the next segment in its members map.
       • If the current object is an ObjClass, look up the next segment with getInstanceMemberOrNull (for nested classes or class-level members), if applicable.
     • Continue until the final segment is reached; verify the target is an ObjClass.
   • If this structural path resolution fails, optionally fall back to scope.eval(fullyQualifiedName) in development modes, but prefer to avoid it in production for determinism.

3. Runtime namespace objects (optional but recommended)

   • Introduce or formalize an ObjNamespace (or reuse existing) that represents packages/modules at runtime and can be placed in scope bindings, enabling deterministic traversal of ns.sub without compiling code.
   • Ensure imports or package declarations materialize such namespace objects in accessible scopes when required, so dotted paths can be resolved purely structurally by the decoder.

4. Backward compatibility and migration

   • Maintain decoding support for simple names for older data.
   • Prefer fully-qualified names when writing new data once the feature is available.
   • Provide configuration to control which form to emit.

5. Testing strategy

   • Add tests that:
     • Encode/decode with simple names (legacy) and confirm existing behavior.
     • Encode/decode with fully-qualified names (new) and confirm dotted-path traversal works without eval.
     • Cover ambiguity resolution when same simple name exists in multiple namespaces.

Summary

Today, Lynon encodes and decodes class names using simple names only. The decoder’s name resolution was strengthened to be import-aware and robust, fixing cases where eval sees a class that get does not. To support fully-qualified names in the future, we plan to emit dotted class paths and implement a structural dotted-path resolver in the decoder (with optional runtime namespace objects) to avoid relying on eval and to keep decoding deterministic and unambiguous.