[Phase 1] Define Link and LinkStore interfaces/traits (API Contract)

[konard]

Summary

Implements the core Link and LinkStore interfaces/traits as the API contract for both JavaScript and Rust implementations. This is the foundation for all subsequent implementations as specified in #7.

Key Features

• Link Interface/Struct: Core data structure with id, source, target, and optional values array
• LinkRef Type: Flexible references that can be either an ID or nested Link (supports arbitrary recursion)
• LinkStore Interface/Trait: CRUD operations with pattern matching support
• LinkPattern: Query patterns with Any wildcard for flexible matching
• Generic ID Types:
  • TypeScript: number | bigint | string
  • Rust: Generic T: LinkType (supports u8, u16, u32, u64, usize, i8-i64)

Design Goals

• ✅ Compatible with links-notation: Supports nested/recursive structures via values array
• ✅ Compatible with doublets-rs: Source/target model with generic ID types
• ✅ Extensible: Universal links with any number of references via optional values array
• ✅ API Parity: Consistent interfaces between JavaScript and Rust

Files Changed

JavaScript (js/src/):

• types.ts - Full TypeScript interface definitions with comprehensive JSDoc
• index.d.ts - Type declarations for public API
• index.js - Runtime implementations (createLink, matchesPattern, utility functions)
• examples/basic-usage.js - Updated examples demonstrating new API
• tests/index.test.js - 36 tests covering all new functionality

Rust (rust/src/):

• traits.rs - Core traits: LinkType, Link, LinkRef, LinkPattern, LinkStore, Any
• lib.rs - Public re-exports
• examples/basic_usage.rs - Updated examples
• tests/integration_test.rs - 26 integration tests

Example Usage

TypeScript:

import { createLink, matchesPattern, Any } from 'links-mq-js';

// Simple link
const link = createLink(1, 2, 3);

// Nested link
const inner = createLink(2, 3, 4);
const outer = createLink(1, inner, 5);

// Pattern matching
const pattern = { source: 5, target: Any };
matchesPattern(link, pattern); // true

Rust:

use links_mq::{Link, LinkRef, LinkPattern, Any};

// Simple link
let link = Link::new(1u64, LinkRef::Id(2), LinkRef::Id(3));

// Nested link
let inner = Link::new(2u64, LinkRef::Id(3), LinkRef::Id(4));
let outer = Link::new(1u64, LinkRef::link(inner), LinkRef::Id(5));

// Pattern matching
let pattern = LinkPattern::new().source(Any).target(5u64);
pattern.matches(&outer); // true

Test Plan

• All 36 JavaScript tests pass (npm test)
• All 57 Rust tests pass (cargo test - 31 unit + 26 integration)
• JavaScript linting passes (npm run lint)
• Rust clippy passes (cargo clippy)
• Examples run successfully

Enables Parallel Work

Once merged, the following can be worked on in parallel:

• JavaScript in-memory LinkStore implementation
• Rust in-memory LinkStore implementation

Fixes #7

---

🤖 Generated with Claude Code

[konard]

🤖 Solution Draft Log

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

💰 Cost estimation:

• Public pricing estimate: $7.348865 USD
  📎 Log file uploaded as Gist (1248KB)
  🔗 View complete solution draft log

---

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

[konard]

Resolve conflicts, double check everything works fine against our ROADMAP, and make sure tests passing.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2026-01-11T04:10:55.665Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

[konard]

🤖 Solution Draft Log

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

💰 Cost estimation:

• Public pricing estimate: $7.890844 USD
• Calculated by Anthropic: $5.400513 USD
• Difference: $-2.490331 (-31.56%)
  📎 Log file uploaded as Gist (933KB)
  🔗 View complete solution draft log

---

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

[konard]

🤖 AI Work Session Started

Starting automated work session at 2026-01-13T21:10:10.936Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

[konard]

🤖 Work Session Complete

Verification Summary

All checks passing:

• ✅ JavaScript tests: 36/36 pass
• ✅ Rust tests: 31 unit + 26 integration + 12 doc tests = 69 total (all pass)
• ✅ Rust clippy: No warnings
• ✅ CI: Passing on latest commit (97b5574)
• ✅ Branch is up-to-date with main

PR Review Against Issue #7 Requirements

The PR implements all requirements from Issue #7:

JavaScript:

• Link interface with id, source, target, and optional values properties
• LinkStore interface with full CRUD operations
• LinkPattern interface with Any wildcard for pattern matching
• Utility functions: createLink, matchesPattern, isLink, isLinkId, isLinkRef, getLinkId
• Compatible with links-notation (nested structures) and doublets-rs (source/target model)

Rust:

• Link<T> struct with id, source, target, and optional values
• LinkStore<T> trait with full CRUD operations
• LinkPattern<T> struct with Any wildcard
• LinkRef<T> enum for ID or nested Link references
• LinkType trait for generic ID types (u8-u64, i8-i64, usize, isize)
• Comprehensive error types (LinkError, LinkResult)

Notes

This PR establishes the API contract (interfaces/traits) as specified in Issue #7. The in-memory implementations are listed separately in the ROADMAP and will be addressed in follow-up work.

---

PR is now marked as ready for review.

[konard]

⚠️ Solution Draft Finished with Errors

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

💰 Cost estimation:

• Public pricing estimate: $1.772517 USD
• Calculated by Anthropic: $0.000000 USD
• Difference: $-1.772517 (-100.00%)

Note: The session encountered errors during execution, but some work may have been completed. Please review the changes carefully.

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

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