Allow treating links references as binary data

[konard]

Summary

Implements issue #508 to allow treating links references as binary data, enabling the doublets store to function as a file system, archive, or file storage database.

Changes

1. New Extension Methods (ILinksExtensions.cs)

Added EnsureReferenceExistsOrExternal methods that validate references while allowing external (binary data) references:

public static void EnsureReferenceExistsOrExternal<TLinkAddress>(
    this ILinks<TLinkAddress> links, 
    TLinkAddress reference, 
    string argumentName)

Behavior:

• ✅ Internal references → validated for existence (throws if not found)
• ✅ External references → allowed without validation (binary data)

2. New Decorator: LinksExternalReferenceValidator

Created LinksExternalReferenceValidator<TLinkAddress> decorator that:

• Overrides Each(), Update(), and Delete() methods
• Uses EnsureReferenceExistsOrExternal() for validation
• Enables mixed usage of internal (existing links) and external (binary data) references

Location: csharp/Platform.Data.Doublets/Decorators/LinksExternalReferenceValidator.cs

3. Comprehensive Test Suite

Added 7 tests in LinksExternalReferenceValidatorTests.cs (all passing ✅):

1. InternalReferenceValidationTest - Ensures internal references must exist
2. ExternalReferenceAllowedTest - Verifies external references work without validation
3. MixedInternalAndExternalReferencesTest - Tests combined usage
4. EachOperationWithExternalReferencesTest - Validates query operations
5. DeleteOperationValidationTest - Confirms delete still validates existence
6. ComparisonWithInnerReferenceValidatorTest - Demonstrates differences between validators
7. BinaryDataStorageScenarioTest - Real-world file system use case

Key Features

External Reference Support via Hybrid Type

Uses Hybrid<T> with isExternal: true to mark references as binary data:

var binaryData = new Hybrid<ulong>(0xDEADBEEF, isExternal: true);
var link = validator.Update(existingLink, source, binaryData);

Use Cases Enabled

• File System: Store file metadata as binary references
• Archive Storage: Variable-length reference sequences
• Binary Database: Raw data storage alongside graph structure
• Hybrid Data: Mix internal graph links with external binary pointers

Testing

Local Tests: ✅ All 7 tests passing
CI Status: ✅ Passing (auto-merge workflow succeeded)

Implementation Details

Validation Logic

// From EnsureReferenceExistsOrExternal
if (links.Constants.IsInternalReference(reference) && !links.Exists(reference))
{
    throw new ArgumentLinkDoesNotExistsException<TLinkAddress>(reference, argumentName);
}
// External references pass through without validation

Decorator Pattern

Follows existing pattern from LinksInnerReferenceExistenceValidator:

• Inherits from LinksDecoratorBase<TLinkAddress>
• Wraps ILinks<TLinkAddress> implementation
• Provides transparent validation layer

Backwards Compatibility

✅ Fully backwards compatible

• Existing code using LinksInnerReferenceExistenceValidator continues to work
• New LinksExternalReferenceValidator is opt-in
• No breaking changes to API or behavior

Related

• Fixes Allow treat links references as binary data #508
• Addresses TODO comments in LinksInnerReferenceExistenceValidator.cs (lines 10 and 80)
• Complements existing external reference infrastructure (commit c852f4f)

---

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

📎 Log file uploaded as GitHub Gist (653KB)
🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.