Add Deleted constant functionality to mark unused links - fixes #389

[konard]

Summary

This PR addresses issue #389 by implementing a Deleted constant functionality that provides explicit marking of unused links. This enhancement works for both united and split trees and potentially allows indexes to be optional.

Key Features Added

1. LinksConstantsExtensions.cs

• GetDeleted(): Returns the deleted constant value
• IsDeleted(): Checks if an address represents the deleted constant

2. DeletedLinkMarker.cs

• MarkAsDeleted(): Marks a link as deleted by setting its source to the Deleted constant
• IsMarkedAsDeleted(): Checks if a link is marked as deleted
• ClearDeletedMark(): Clears the deleted mark from a link

3. EnhancedUnusedLinkDetection.cs

• IsUnusedLinkByDeletedMarker(): Enhanced unused link detection using Deleted markers
• ExistsWithDeletedCheck(): Link existence check using deleted markers

4. Comprehensive Test Suite

• DeletedConstantTests.cs: 8 comprehensive tests covering all functionality
• All tests are passing ✅

Benefits

🚀 Performance Improvement

Instead of complex list traversal to determine if a link is unused:

// Old approach - complex list traversal
protected virtual bool IsUnusedLink(TLinkAddress linkIndex) { ... }

// New approach - simple constant comparison  
protected virtual bool IsUnusedLink(TLinkAddress linkSource, TLinkAddress linkTarget) {
    var deleted = Constants.GetDeleted();
    return linkSource == deleted || linkTarget == deleted;
}

🔄 Universal Compatibility

Works identically for both:

• Split Memory Links: Uses separate data and index parts
• United Memory Links: Uses combined link structures

⚡ Optional Indexes

Provides a direct way to identify deleted links without traversing index structures, making tree indexes optional as requested in the issue.

📈 Explicit State Management

Links are explicitly marked with the Deleted constant, making the system more predictable and easier to debug.

Technical Implementation

The solution extends the existing LinksConstants<TLinkAddress> pattern by adding a Deleted constant that follows the same allocation pattern as other constants:

// Extension method approach (for backward compatibility)
public static TLinkAddress GetDeleted<TLinkAddress>(this LinksConstants<TLinkAddress> constants) 
    where TLinkAddress : IUnsignedNumber<TLinkAddress>
{
    return constants.Error - TLinkAddress.One;  // Follows existing allocation pattern
}

Platform.Data Dependency

The complete solution requires adding the Deleted constant to Platform.Data's LinksConstants class. A patch file has been provided: LinksConstants.cs.patch

Backward Compatibility

✅ Fully backward compatible:

• Existing constants remain unchanged
• Current unused link detection continues to work
• New functionality is additive only

Documentation

• Complete solution documentation: DELETED_CONSTANT_SOLUTION.md
• Detailed implementation guide and usage examples
• Migration path and integration instructions

Testing

All functionality is covered by comprehensive tests:

• Constant allocation verification
• Marking/unmarking functionality
• Enhanced detection algorithms
• Compatibility with existing constants

Test Results: 8/8 tests passing ✅

Version Update

Package version updated to 0.18.2 with appropriate release notes.

Related Issues

Fixes #389 - Add Deleted/Unused constant to mark links that are in Unused list

---

🤖 Generated with Claude Code