Fix single-value property traversals returning arrays

[flyon]

Summary

Properties decorated with @objectProperty({maxCount: 1}) (e.g., bestFriend) now correctly return a single ResultRow (or null when absent) instead of ResultRow[] when accessed via traversal queries like Person.select(p => p.bestFriend.name).

Root Cause

The maxCount metadata from PropertyShape was never propagated through the IR pipeline. IRTraversePattern had no maxCount field, so the result mapping layer had no way to distinguish single-value from multi-value traversals, causing all nested groups to be returned as arrays.

Key Changes

• IntermediateRepresentation.ts: Added optional maxCount?: number field to IRTraversePattern
• IRDesugar.ts: Propagated maxCount from PropertyShape through DesugaredPropertyStep in segmentsToSteps() and desugarEntry()
• IRLower.ts: Extended getOrCreateTraversal() and PathLoweringOptions.resolveTraversal signatures to accept and apply maxCount to traverse patterns
• IRProjection.ts: Updated ProjectionPathLoweringOptions.resolveTraversal signature to forward maxCount from desugared steps
• resultMapping.ts:
  • Added maxCount?: number to NestedGroup type
  • Propagated maxCount through buildAliasChain(), insertIntoTree(), and buildNestingDescriptor()
  • Added assignNestedGroupValue() helper that unwraps single-value properties (where maxCount <= 1) from arrays to a single ResultRow or null
• Test fixtures & tests: Added comprehensive test coverage including 4 new single-value property tests and 1 golden snapshot test verifying maxCount propagation through the full pipeline

Implementation Details

• maxCount is propagated as an optional field through each layer of the IR pipeline, maintaining backward compatibility
• The unwrapping logic is applied only during result mapping post-processing, not during query building—single-value and multi-value properties generate identical SPARQL patterns
• Absent single-value traversals return null (consistent with singleResult behavior), not undefined or empty arrays
• Multi-value properties without maxCount constraints continue to return arrays as before

Breaking Change

Code accessing single-value traversal results as arrays (e.g., result.bestFriend[0]) must be updated to access the value directly (e.g., result.bestFriend).

https://claude.ai/code/session_017mqanCkMvA1VU8MVD7hkA1