Implement virtual links structures concept

[konard]

Summary

This PR implements the concept of virtual links structures as described in issue #599. Virtual links structures allow traditional table data (like strings, numbers, or binary data) to be accessed through a links-like interface without being physically stored in the links space.

What are Virtual Links Structures?

Virtual links structures are a design pattern that:

• Store data in optimized formats (e.g., strings in a dictionary/table)
• Present a links-like interface for uniform access
• Are traversable like real links
• Do not occupy space in the physical links database

Implementation Details

Core Components

1. IVirtualLinksStructure (IVirtualLinksStructure.cs)

   • Defines the interface for virtual links structures
   • Provides GetSource(), GetTarget(), Contains() methods
   • Enables uniform access patterns across real and virtual links

2. VirtualStringTable (VirtualStringTable.cs)

   • Example implementation for efficient string storage
   • Stores strings in a Dictionary (simulating a table)
   • Accessible through links interface without physical link storage
   • Demonstrates the core concept with a practical use case

Documentation & Examples

3. Comprehensive Documentation (virtual-links-structures.md)

   • Detailed explanation of the concept
   • Use cases and benefits
   • Integration patterns
   • Future enhancement possibilities

4. Demonstration Code (VirtualLinksStructureDemo.cs)

   • Interactive demonstration showing how virtual structures work
   • Examples of adding, accessing, and traversing virtual links
   • Educational tool for understanding the concept

5. Integration Example (VirtualLinksIntegrationExample.cs)

   • Shows how virtual links integrate with real links systems
   • Practical scenario with entity relationships and string labels
   • Demonstrates ID space partitioning

Key Benefits

• ✅ Efficient Storage: Data stored in optimal format for its type
• ✅ Uniform Access: Same interface for real and virtual links
• ✅ Traversable: Virtual structures can be navigated like real links
• ✅ Reduced Overhead: No need to decompose complex data into individual links
• ✅ Type Specialization: Different virtual structures for different data types

How It Addresses Issue #599

Issue #599 states:

"Each row in additional table can be represented as virtual links structure. It is possible to traverse this structure, but it not actually stored."

This implementation:

• ✅ Represents table rows (strings) as virtual links
• ✅ Allows traversal through GetSource() and GetTarget()
• ✅ Stores data in a table (Dictionary), not in links space
• ✅ Provides example with strings, but extensible to other data types

Example Usage

// Create a virtual string table with base ID of 1,000,000
var stringTable = new VirtualStringTable<long>(
    baseId: 1_000_000L,
    increment: x => x + 1,
    greaterThanOrEqual: (a, b) => a >= b,
    lessThan: (a, b) => a < b,
    subtract: (a, b) => a - b,
    add: (a, n) => a + n
);

// Add strings (stored in table, not as links)
var link1 = stringTable.Add("Hello");
var link2 = stringTable.Add("World");

// Access like links
var source = stringTable.GetSource(link1);  // Virtual source
var target = stringTable.GetTarget(link1);  // Virtual target
var exists = stringTable.Contains(link1);   // true

// Traverse virtual structure
stringTable.Traverse(link1, (link, src, tgt) => {
    Console.WriteLine($"Link: {link}, Source: {src}, Target: {tgt}");
});

Testing

• ✅ Code compiles successfully (dotnet build passes)
• ✅ Follows existing codebase patterns and style
• ✅ Includes comprehensive examples and documentation

Future Enhancements

This foundation enables:

• Virtual number tables for numeric data
• Virtual binary tables for blob/file storage
• Virtual time series for temporal data
• Lazy virtual structures that generate links on-the-fly
• Integration with external data sources

Related Issue

Fixes #599

---

🤖 Generated with Claude Code

[konard]

🤖 Solution Draft Log

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

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

---

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