fix/feat: ensure getRemoteRelationship operates correctly, add sync belongsTo support to PolarisMode, add $key to PolarisMode defaults

[runspired]

resolves #10464

also resolves an issue where linksMode asserted too aggressively for sync belongsTo relationships.

Summary of Changes

1. Overall Purpose/Goal

This branch fixes how getRemoteRelationship handles sync belongsTo relationships, particularly in linksMode. The changes ensure proper distinction between "never set" (undefined), "explicitly null", and "has value" relationship states, while also allowing mutations of sync belongsTo fields in Polaris mode.

2. Key Files Modified

Core Logic Changes:

• warp-drive-packages/core/src/graph/-private/edges/resource.ts - Fixed remote relationship data retrieval logic
• warp-drive-packages/core/src/graph/-private/operations/replace-related-record.ts - Separated remote vs local hasReceivedData tracking
• warp-drive-packages/core/src/graph/-private/operations/update-relationship.ts - Removed automatic initialization of unset relationships
• warp-drive-packages/core/src/reactive/-private/kind/belongs-to-field.ts - Added support for editing sync belongsTo in Polaris mode
• warp-drive-packages/json-api/src/-private/validate-document-fields.ts - Improved validation logic for sync vs async linksMode relationships

Infrastructure:

• warp-drive-packages/core/src/graph/-private/-state.ts - Added debug logging for state tracking
• warp-drive-packages/core/src/reactive/-private/schema.ts - Added $key identifier field to schemas, enhanced documentation

Tests:

• tests/json-api/tests/integration/cache/cache.get-remote-relationship-test.ts - New file with comprehensive tests
• tests/core/tests/polaris-mode/belongs-to-field-read-test.ts - Updated/removed tests around undefined vs null handling
• tests/core/tests/schema-dsl/resource-decorator-test.ts - Added type assertions, removed duplicate test

3. Notable Additions, Deletions, or Refactorings

Additions:

• 333-line comprehensive test suite for getRemoteRelationship covering null, undefined, and dirty states
• Support for mutating sync belongsTo relationships in Polaris mode
• $key derived field added to all schemas
• Extensive JSDoc documentation for context types

Deletions:

• Removed test "we error in linksMode if the relationship data is undefined" (58 lines)
• Removed automatic initialization of unset async relationships to empty arrays/null
• Removed duplicate withDefaults test case

Key Refactorings:

• legacyGetResourceRelationshipData: Simplified conditional logic using ?? operator for cleaner null/undefined handling
• Validation logic now distinguishes between sync/async requirements (sync requires data OR link, async requires link only)
• Local mutations no longer set hasReceivedData flag (only remote updates do)

4. Potential Concerns & Important Details

⚠️ Behavioral Changes:

• Local relationship mutations no longer mark state as "hasReceivedData" - could affect code relying on this flag after local-only updates
• Removed automatic initialization means unset relationships stay truly undefined rather than being forced to null/empty - breaking change for code expecting initialization

⚠️ Type Safety:

• Added $key field to all schemas - may affect type inference or schema validation elsewhere

✅ Improvements:

• Better semantic distinction between "never received from server" vs "server sent null"
• More precise validation prevents invalid states in linksMode
• Comprehensive test coverage ensures edge cases are handled

Critical Logic Change:
The fix in legacyGetResourceRelationshipData ensures that when hasReceivedData is true, it returns the actual value (null or undefined) rather than conditionally checking both state and received data separately, preventing the "undefined when should be null" bug.