SdPath::Sidecar Variant Integration

Description

Integrate sidecars as a first-class SdPath variant, enabling unified addressing and standard file operations. This elevates sidecars from specialized infrastructure to full VDFS citizens.

See workbench/core/storage/VIRTUAL_SIDECAR_SYSTEM_V2.md Section "SdPath Integration" for complete specification.

Implementation Files

• core/src/domain/addressing.rs - Add Sidecar variant to enum
• core/src/domain/addressing/parser.rs - Parse sidecar:// URIs
• core/src/domain/addressing/display.rs - Display formatting
• core/src/domain/addressing/resolver.rs - Resolution logic
• core/src/ops/sidecar/types.rs - Ensure compatibility

Tasks

Add SdPath Variant

• Add Sidecar { content_id, kind, variant, format } to SdPath enum
• Implement SdPath::sidecar() helper method
• Add is_sidecar() predicate method
• Update Clone, Debug, PartialEq derives

URI Parsing

• Implement parse_sidecar() for sidecar:// scheme
• Parse format: sidecar://{uuid}/{kind_dir}/{variant}.{ext}
• Validate UUID, kind, variant, format
• Return helpful errors for malformed URIs

Display Implementation

• Implement Display trait for sidecar paths
• Format as sidecar://{uuid}/{kind}/{variant}.{ext}
• Handle special characters in variants
• Add to_uri() method

Resolution Integration

• Add resolve_sidecar() method to resolver
• Implement resolution modes (blocking, async, fetch-only)
• Integrate with existing SidecarManager::compute_path()
• Handle missing sidecars (enqueue generation)
• Handle remote sidecars (return device reference)

Testing

• Unit tests for URI parsing (valid/invalid cases)
• Unit tests for display formatting
• Unit tests for resolution with various modes
• Integration test: parse → resolve → access
• Edge cases: special chars, missing sidecars, remote devices

Acceptance Criteria

• SdPath::Sidecar variant exists with all required fields
• Can parse sidecar://uuid/kind/variant.ext strings
• Display format matches specification
• Helper methods work ergonomically
• Resolution integrates with SidecarManager
• Missing sidecars trigger generation in async mode
• Remote sidecars return device references
• All unit tests pass
• Documentation updated in docs/core/addressing.mdx

Example Usage

// Create sidecar path
let thumb = SdPath::sidecar(
    content_uuid,
    SidecarKind::Thumb,
    "grid@2x",
    SidecarFormat::Webp,
);

// Parse from URI
let parsed = SdPath::from_uri("sidecar://550e8400.../thumbs/[email protected]")?;
assert_eq!(parsed, thumb);

// Display as URI
assert_eq!(thumb.display(), "sidecar://550e8400.../thumbs/[email protected]");

// Resolve to physical path
let resolved = resolver.resolve(thumb).await?;
match resolved {
    ResolvedPath::Local(path) => read_file(path),
    ResolvedPath::Pending => wait_for_generation(),
    ResolvedPath::Remote(device_id, path) => fetch_from_device(device_id, path),
}

Implementation Notes

URI Format Specification

sidecar://{content_uuid}/{kind_directory}/{variant}.{extension}

Examples:
  sidecar://550e8400-e29b-41d4-a716-446655440000/thumbs/[email protected]
  sidecar://550e8400-e29b-41d4-a716-446655440000/ocr/ocr.json
  sidecar://550e8400-e29b-41d4-a716-446655440000/embeddings/all-MiniLM-L6-v2.json

Glob patterns:
  sidecar://*/thumbs/[email protected]              # All grid thumbnails
  sidecar://550e8400.../thumbs/*                # All thumbnails for one content
  sidecar://{uuid}/*                            # All sidecars for content

Resolution Modes

pub enum SidecarResolveMode {
    /// Error if not available locally
    LocalOnly,

    /// Generate locally, block until ready
    GenerateBlocking,

    /// Generate locally, return pending
    GenerateAsync,

    /// Fetch from remote if available, else generate
    FetchOrGenerate,

    /// Fetch only, never generate
    FetchOnly,
}

Integration with Existing Code

The SidecarManager service already exists with all the path computation logic. This task integrates it with the SdPath abstraction:

// Before: Direct SidecarManager usage
let path = sidecar_manager.compute_path(uuid, kind, variant, format)?;

// After: Through SdPath
let sidecar = SdPath::sidecar(uuid, kind, variant, format);
let resolved = resolver.resolve(sidecar)?;

Existing SidecarManager methods become implementation details behind the resolver.

Timeline

Estimated: 3-4 days focused work

• Day 1: Add enum variant, helper methods, basic parsing
• Day 2: Display implementation, resolution logic
• Day 3: Testing, edge cases, error handling
• Day 4: Documentation, examples, polish