claude-code-swarm 0.0.1 → 0.3.3

package/references/opentasks/src/graph/provider-store.ts

@@ -0,0 +1,1077 @@
+/**
+ * Provider-Aware Graph Store
+ *
+ * Extends GraphStore with provider resolution and materialization capabilities.
+ * This wrapper adds the ability to resolve external URIs and materialize
+ * external nodes while keeping the base GraphStore implementation intact.
+ */
+
+import type { Node, ExternalNode } from '../schema/index.js';
+import type {
+  Provider,
+  ProviderNode,
+  ProviderCreateInput,
+  ProviderUpdateInput,
+  ProviderRegistry,
+  MaterializationConfig,
+  ProviderOperationContext,
+} from '../providers/types.js';
+import { ProviderError } from '../providers/types.js';
+import type { MaterializationManager } from '../providers/materialization.js';
+import { createProviderRegistry } from '../providers/registry.js';
+import { createNativeProvider } from '../providers/native.js';
+import { createMaterializationManager } from '../providers/materialization.js';
+import {
+  isWatchable,
+  type ProviderChangeEvent,
+  type ProviderNodeChangeEvent,
+} from '../providers/traits/Watchable.js';
+import {
+  isTaskManageable,
+  type TaskAction,
+  type ReadyTaskOptions,
+} from '../providers/traits/TaskManageable.js';
+import type { GraphStore } from './store.js';
+import type { CreateNodeInput, UpdateNodeInput, DeleteOptions } from './types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Options for resolving a node
+ */
+export interface ResolveOptions {
+  /** Force fresh fetch (ignore cache) */
+  refresh?: boolean;
+
+  /** Explicitly request materialization */
+  materialize?: boolean;
+
+  /** Include raw provider data in response */
+  includeRawData?: boolean;
+}
+
+/**
+ * Options for provider-routed create
+ */
+export interface ProviderCreateOptions {
+  /** Target provider scheme (overrides defaultProvider) */
+  scheme?: string;
+
+  /** Operational context forwarded to the provider */
+  context?: ProviderOperationContext;
+}
+
+/**
+ * Options for provider-routed get
+ */
+export interface ProviderGetOptions {
+  /** Operational context forwarded to the provider */
+  context?: ProviderOperationContext;
+}
+
+/**
+ * Options for provider-routed update
+ */
+export interface ProviderUpdateOptions {
+  /** Operational context forwarded to the provider */
+  context?: ProviderOperationContext;
+}
+
+/**
+ * Options for task transition operations
+ */
+export interface TaskTransitionOptions {
+  /** Operational context forwarded to the provider */
+  context?: ProviderOperationContext;
+}
+
+/**
+ * Options for querying ready tasks across providers
+ */
+export interface FederatedReadyTaskOptions extends ReadyTaskOptions {
+  /** Only query these providers (by name). If omitted, queries all task-capable providers. */
+  providers?: string[];
+
+  /** Operational context forwarded to providers */
+  context?: ProviderOperationContext;
+}
+
+/**
+ * Result from a task transition
+ */
+export interface TaskTransitionResult {
+  /** The updated node (materialized if external) */
+  node: Node;
+  /** The provider that handled the transition */
+  provider: string;
+  /** The action that was applied */
+  action: TaskAction;
+}
+
+/**
+ * Result from a provider-routed create
+ */
+export interface ProviderCreateResult {
+  /** The created/materialized node */
+  node: Node;
+  /** The provider URI (if created via external provider) */
+  uri?: string;
+  /** Which provider handled the create */
+  provider: string;
+}
+
+/**
+ * Configuration for provider-aware store
+ */
+export interface ProviderStoreConfig {
+  /** Pre-configured provider registry (optional) */
+  registry?: ProviderRegistry;
+
+  /** Materialization configuration */
+  materialization?: Partial<MaterializationConfig>;
+
+  /** Whether to auto-register native provider (default: true) */
+  autoRegisterNative?: boolean;
+
+  /** Default provider for CRUD operations ('native' = local GraphStore) */
+  defaultProvider?: string;
+}
+
+/**
+ * Callback for provider change events received by the store.
+ * Allows external consumers to react to provider-driven changes.
+ */
+export type ProviderChangeHandler = (providerName: string, event: ProviderChangeEvent) => void;
+
+/**
+ * Provider-aware graph store interface
+ */
+export interface ProviderAwareStore extends GraphStore {
+  /** Provider registry */
+  readonly providers: ProviderRegistry;
+
+  /** Materialization manager */
+  readonly materialization: MaterializationManager;
+
+  /**
+   * Resolve any node by ID or URI
+   * - Local IDs (s-, i-, f-, e-, x-) → getNode()
+   * - External URIs → provider.get() + optional materialize
+   */
+  resolveNode(idOrUri: string, options?: ResolveOptions): Promise<Node | ProviderNode | null>;
+
+  /**
+   * Materialize an external node from provider data
+   */
+  materializeNode(uri: string): Promise<ExternalNode>;
+
+  /**
+   * Refresh a materialized external node
+   */
+  refreshNode(id: string): Promise<ExternalNode | null>;
+
+  /**
+   * Start background sync for external nodes
+   */
+  startBackgroundSync(): void;
+
+  /**
+   * Stop background sync
+   */
+  stopBackgroundSync(): void;
+
+  /**
+   * Check if background sync is running
+   */
+  isBackgroundSyncRunning(): boolean;
+
+  /**
+   * Start watching all watchable providers for changes.
+   *
+   * For each provider that implements the Watchable trait, subscribes
+   * to change events and auto-refreshes materialized nodes.
+   * Non-watchable providers are skipped (use startBackgroundSync for those).
+   */
+  startProviderWatching(): void;
+
+  /**
+   * Stop watching all providers for changes.
+   */
+  stopProviderWatching(): void;
+
+  /**
+   * Register an external handler for provider change events.
+   * Called after the store has processed each event internally.
+   *
+   * @returns Unsubscribe function
+   */
+  onProviderChange(handler: ProviderChangeHandler): () => void;
+
+  // ===========================================================================
+  // Provider-Routed CRUD (Unified Interface)
+  // ===========================================================================
+
+  /**
+   * Create a node via provider dispatch.
+   * Routes to defaultProvider or explicit scheme. Always materializes.
+   */
+  providerCreate(
+    input: CreateNodeInput,
+    options?: ProviderCreateOptions,
+  ): Promise<ProviderCreateResult>;
+
+  /**
+   * Get a node by local ID or provider URI.
+   * For external nodes, refreshes if stale.
+   */
+  providerGet(idOrUri: string, options?: ProviderGetOptions): Promise<Node | null>;
+
+  /**
+   * Update a node by local ID or provider URI.
+   * For external/materialized nodes, routes update to the owning provider
+   * and refreshes the local materialized copy.
+   */
+  providerUpdate(
+    idOrUri: string,
+    updates: UpdateNodeInput,
+    options?: ProviderUpdateOptions,
+  ): Promise<Node>;
+
+  /**
+   * Delete a node by local ID or provider URI.
+   * For external/materialized nodes, deletes in the provider
+   * and removes the local materialized copy.
+   */
+  providerDelete(
+    idOrUri: string,
+    options?: DeleteOptions & { context?: ProviderOperationContext },
+  ): Promise<void>;
+
+  /** The configured default provider name */
+  readonly defaultProvider: string;
+
+  // ===========================================================================
+  // Task Lifecycle (TaskManageable Trait — Federated)
+  // ===========================================================================
+
+  /**
+   * Transition a task's status using a semantic action.
+   * Resolves the owning provider, checks that it supports TaskManageable,
+   * and delegates the transition.
+   */
+  taskTransition(
+    idOrUri: string,
+    action: TaskAction,
+    options?: TaskTransitionOptions,
+  ): Promise<TaskTransitionResult>;
+
+  /**
+   * Get tasks that are ready to work on, aggregated across all
+   * task-capable providers (Option B: federated aggregation).
+   */
+  taskReady(options?: FederatedReadyTaskOptions): Promise<Node[]>;
+
+  /**
+   * Assign a task to an owner.
+   * Resolves the owning provider, checks TaskManageable + supportsAssignment.
+   */
+  taskAssign(idOrUri: string, assignee: string, options?: TaskTransitionOptions): Promise<Node>;
+
+  /**
+   * Get valid next actions for a task in its current state.
+   * Falls back to the provider's full `taskCapabilities.actions` if the
+   * provider doesn't implement `validActions`.
+   */
+  taskValidActions(idOrUri: string): Promise<TaskAction[]>;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Pattern for local node IDs (s-, i-, f-, e-, x-)
+ */
+const LOCAL_ID_PATTERN = /^[ctfex]-[a-z0-9]+$/;
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Check if a string is a local node ID
+ */
+function isLocalId(idOrUri: string): boolean {
+  return LOCAL_ID_PATTERN.test(idOrUri);
+}
+
+/**
+ * Convert CreateNodeInput to ProviderCreateInput.
+ * Passes through tags and parent_id via metadata so providers can use them.
+ */
+function toProviderCreateInput(input: CreateNodeInput): ProviderCreateInput {
+  // Merge tags and parent_id into metadata for providers that support them
+  const metadata: Record<string, unknown> = { ...input.metadata };
+  if (input.tags && input.tags.length > 0) {
+    metadata.tags = input.tags;
+  }
+  if (input.parent_id) {
+    metadata.parent_id = input.parent_id;
+  }
+
+  return {
+    type: input.type === 'task' ? 'issue' : input.type === 'context' ? 'spec' : 'issue',
+    title: input.title,
+    content: input.content,
+    status: input.status,
+    priority: input.priority,
+    metadata: Object.keys(metadata).length > 0 ? metadata : input.metadata,
+  };
+}
+
+/**
+ * Convert UpdateNodeInput to ProviderUpdateInput
+ */
+function toProviderUpdateInput(updates: UpdateNodeInput): ProviderUpdateInput {
+  return {
+    title: updates.title,
+    content: updates.content,
+    status: updates.status,
+    priority: updates.priority,
+    metadata: updates.metadata,
+  };
+}
+
+/**
+ * Find external node by URI in the store
+ */
+async function findExternalNodeByUri(uri: string, store: GraphStore): Promise<ExternalNode | null> {
+  const nodes = await store.query.nodes({
+    type: 'external',
+  });
+
+  for (const node of nodes) {
+    if (node.type === 'external' && (node as ExternalNode).uri === uri) {
+      return node as ExternalNode;
+    }
+  }
+
+  return null;
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Create a provider-aware store by wrapping an existing GraphStore
+ */
+export function createProviderAwareStore(
+  baseStore: GraphStore,
+  config: ProviderStoreConfig = {},
+): ProviderAwareStore {
+  // Set up provider registry
+  const registry = config.registry ?? createProviderRegistry();
+
+  // Set up materialization manager
+  const materialization = createMaterializationManager(config.materialization);
+
+  // Default provider configuration
+  const defaultProviderName = config.defaultProvider ?? 'native';
+
+  // Auto-register native provider if not disabled
+  if (config.autoRegisterNative !== false) {
+    const nativeProvider = createNativeProvider(baseStore);
+    registry.register(nativeProvider);
+  }
+
+  // =========================================================================
+  // Provider Watch State
+  // =========================================================================
+
+  /** External handlers for provider change events */
+  const changeHandlers: ProviderChangeHandler[] = [];
+
+  /** Track which providers are currently being watched */
+  const watchedProviders = new Set<string>();
+
+  /**
+   * Handle an inbound provider change event.
+   * Auto-refreshes materialized nodes, then notifies external handlers.
+   */
+  async function handleProviderChange(
+    providerName: string,
+    event: ProviderChangeEvent,
+  ): Promise<void> {
+    if (event.kind === 'node') {
+      await handleNodeChange(providerName, event.event);
+    }
+    // Edge events: no auto-action needed for now — consumers can
+    // react via onProviderChange handlers. In the future, the
+    // federated graph could invalidate cached edge data here.
+
+    // Notify external handlers
+    for (const handler of changeHandlers) {
+      try {
+        handler(providerName, event);
+      } catch {
+        // Don't let handler errors break the watch loop
+      }
+    }
+  }
+
+  /**
+   * Handle a node change from a provider.
+   * If the node is already materialized locally, refresh it.
+   */
+  async function handleNodeChange(
+    _providerName: string,
+    event: ProviderNodeChangeEvent,
+  ): Promise<void> {
+    // Check if we have a materialized copy of this node
+    const existing = await findExternalNodeByUri(event.uri, baseStore);
+
+    if (!existing) {
+      // Node not materialized locally — nothing to refresh.
+      // The event is still forwarded to external handlers above.
+      return;
+    }
+
+    if (event.type === 'deleted') {
+      // Mark the local materialized node as stale
+      await baseStore.updateNode(existing.id, {
+        metadata: {
+          ...existing.metadata,
+          stale: true,
+          last_refresh_at: new Date().toISOString(),
+          last_refresh_error: 'Node deleted in provider',
+        },
+      });
+      return;
+    }
+
+    // For 'created' (re-appeared) or 'updated': refresh materialized copy
+    if (event.node) {
+      // Provider included the full node data — materialize directly
+      await materialization.materialize(event.uri, event.node, baseStore);
+    } else {
+      // No node data in event — fetch fresh from provider
+      const provider = registry.resolveProvider(event.uri);
+      if (provider) {
+        await materialization.refresh(existing, provider, baseStore);
+      }
+    }
+  }
+
+  // Create the provider-aware store by extending the base store
+  const providerStore: ProviderAwareStore = {
+    // Spread all base store properties and methods
+    ...baseStore,
+
+    // Add provider-specific properties
+    providers: registry,
+    materialization,
+
+    /**
+     * Resolve a node by ID or URI
+     */
+    async resolveNode(
+      idOrUri: string,
+      options?: ResolveOptions,
+    ): Promise<Node | ProviderNode | null> {
+      return resolveNodeInternal(idOrUri, options);
+    },
+
+    /**
+     * Explicitly materialize an external node
+     */
+    async materializeNode(uri: string): Promise<ExternalNode> {
+      // Find provider for this URI
+      const provider = registry.resolveProvider(uri);
+      if (!provider) {
+        throw new Error(`No provider found for URI: ${uri}`);
+      }
+
+      // Parse and fetch
+      const parsed = provider.parseUri(uri);
+      if (!parsed) {
+        throw new Error(`Invalid URI for provider: ${uri}`);
+      }
+
+      const providerNode = await provider.get(parsed.id);
+      if (!providerNode) {
+        throw new Error(`Node not found: ${uri}`);
+      }
+
+      // Materialize
+      return materialization.materialize(uri, providerNode, baseStore);
+    },
+
+    /**
+     * Refresh a materialized external node
+     */
+    async refreshNode(id: string): Promise<ExternalNode | null> {
+      // Get the existing node
+      const node = await baseStore.getNode(id);
+      if (!node || node.type !== 'external') {
+        throw new Error(`Node not found or not external: ${id}`);
+      }
+
+      const externalNode = node as ExternalNode;
+
+      // Find provider
+      const provider = registry.resolveProvider(externalNode.uri);
+      if (!provider) {
+        throw new Error(`No provider found for URI: ${externalNode.uri}`);
+      }
+
+      // Refresh using materialization manager
+      return materialization.refresh(externalNode, provider, baseStore);
+    },
+
+    /**
+     * Start background sync
+     */
+    startBackgroundSync(): void {
+      materialization.startBackgroundSync(baseStore, registry);
+    },
+
+    /**
+     * Stop background sync
+     */
+    stopBackgroundSync(): void {
+      materialization.stopBackgroundSync();
+    },
+
+    /**
+     * Check if background sync is running
+     */
+    isBackgroundSyncRunning(): boolean {
+      return materialization.isBackgroundSyncRunning();
+    },
+
+    /**
+     * Start watching all watchable providers for changes.
+     */
+    startProviderWatching(): void {
+      for (const provider of registry.list()) {
+        if (isWatchable(provider) && !watchedProviders.has(provider.name)) {
+          provider.startWatching((event) => {
+            void handleProviderChange(provider.name, event);
+          });
+          watchedProviders.add(provider.name);
+        }
+      }
+    },
+
+    /**
+     * Stop watching all providers for changes.
+     */
+    stopProviderWatching(): void {
+      for (const provider of registry.list()) {
+        if (isWatchable(provider) && watchedProviders.has(provider.name)) {
+          provider.stopWatching();
+          watchedProviders.delete(provider.name);
+        }
+      }
+    },
+
+    /**
+     * Register an external handler for provider change events.
+     */
+    onProviderChange(handler: ProviderChangeHandler): () => void {
+      changeHandlers.push(handler);
+      return () => {
+        const idx = changeHandlers.indexOf(handler);
+        if (idx >= 0) changeHandlers.splice(idx, 1);
+      };
+    },
+
+    // =========================================================================
+    // Provider-Routed CRUD (Unified Interface)
+    // =========================================================================
+
+    defaultProvider: defaultProviderName,
+
+    async providerCreate(
+      input: CreateNodeInput,
+      options?: ProviderCreateOptions,
+    ): Promise<ProviderCreateResult> {
+      const targetScheme = options?.scheme ?? defaultProviderName;
+
+      // Native/local path — no provider routing needed
+      if (targetScheme === 'native' || targetScheme === 'opentasks') {
+        const node = await baseStore.createNode(input);
+        return { node, provider: 'native' };
+      }
+
+      // Find the target provider by name or scheme
+      const provider = registry.get(targetScheme) ?? registry.resolveProvider(`${targetScheme}://`);
+      if (!provider) {
+        throw new ProviderError('NOT_FOUND', `Unknown provider: ${targetScheme}`, targetScheme);
+      }
+
+      if (!provider.capabilities.write) {
+        throw new ProviderError(
+          'NOT_SUPPORTED',
+          `Provider ${provider.name} is read-only`,
+          provider.name,
+        );
+      }
+
+      if (!provider.capabilities.mount) {
+        throw new ProviderError(
+          'NOT_SUPPORTED',
+          `Provider ${provider.name} does not support mounting`,
+          provider.name,
+        );
+      }
+
+      // Create via provider, forwarding operational context
+      const providerNode = await provider.create(toProviderCreateInput(input), options?.context);
+
+      // Build canonical URI and always materialize on create
+      const uri = provider.buildUri(providerNode.id);
+      const materializedNode = await materialization.materialize(uri, providerNode, baseStore);
+
+      return {
+        node: materializedNode,
+        uri,
+        provider: provider.name,
+      };
+    },
+
+    async providerGet(idOrUri: string, options?: ProviderGetOptions): Promise<Node | null> {
+      // 1. Local ID — direct store access
+      if (isLocalId(idOrUri)) {
+        const node = await baseStore.getNode(idOrUri);
+
+        // If it's a materialized external node, check staleness
+        if (node?.type === 'external') {
+          const extNode = node as ExternalNode;
+          if (materialization.isStale(extNode)) {
+            const provider = registry.resolveProvider(extNode.uri);
+            if (provider) {
+              const refreshed = await materialization.refresh(
+                extNode,
+                provider,
+                baseStore,
+                options?.context,
+              );
+              return refreshed ?? node;
+            }
+          }
+        }
+
+        return node;
+      }
+
+      // 2. Provider URI — resolve through provider, always materialize
+      const result = await resolveNodeInternal(idOrUri, { materialize: true }, options?.context);
+      return result as Node | null;
+    },
+
+    async providerUpdate(
+      idOrUri: string,
+      updates: UpdateNodeInput,
+      options?: ProviderUpdateOptions,
+    ): Promise<Node> {
+      // Resolve the target node and provider
+      const { node, provider: owningProvider, isExternal } = await resolveForWrite(idOrUri);
+
+      if (!isExternal || owningProvider?.name === 'native') {
+        // Local node — update directly
+        return baseStore.updateNode(node.id, updates);
+      }
+
+      // External node but provider not registered — error rather than silent local-only update
+      if (!owningProvider) {
+        const extNode = node as ExternalNode;
+        throw new ProviderError(
+          'NOT_FOUND',
+          `Provider not registered for external node URI: ${extNode.uri}. Cannot route update.`,
+        );
+      }
+
+      if (!owningProvider.capabilities.write) {
+        throw new ProviderError(
+          'NOT_SUPPORTED',
+          `Provider ${owningProvider.name} is read-only`,
+          owningProvider.name,
+        );
+      }
+
+      // Route update to external provider
+      const extNode = node as ExternalNode;
+      const parsed = owningProvider.parseUri(extNode.uri);
+      if (!parsed) {
+        throw new ProviderError(
+          'INVALID_URI',
+          `Cannot parse URI: ${extNode.uri}`,
+          owningProvider.name,
+        );
+      }
+
+      const updatedProviderNode = await owningProvider.update(
+        parsed.id,
+        toProviderUpdateInput(updates),
+        options?.context,
+      );
+
+      // Refresh local materialized copy with provider's response
+      return materialization.materialize(
+        extNode.uri,
+        updatedProviderNode,
+        baseStore,
+      ) as Promise<Node>;
+    },
+
+    async providerDelete(
+      idOrUri: string,
+      options?: DeleteOptions & { context?: ProviderOperationContext },
+    ): Promise<void> {
+      // Resolve the target node and provider
+      const { node, provider: owningProvider, isExternal } = await resolveForWrite(idOrUri);
+
+      if (!isExternal || owningProvider?.name === 'native') {
+        // Local node — delete directly
+        await baseStore.deleteNode(node.id, options);
+        return;
+      }
+
+      // External node but provider not registered — error rather than silent local-only delete
+      if (!owningProvider) {
+        const extNode = node as ExternalNode;
+        throw new ProviderError(
+          'NOT_FOUND',
+          `Provider not registered for external node URI: ${extNode.uri}. Cannot route delete.`,
+        );
+      }
+
+      if (!owningProvider.capabilities.write) {
+        throw new ProviderError(
+          'NOT_SUPPORTED',
+          `Provider ${owningProvider.name} is read-only`,
+          owningProvider.name,
+        );
+      }
+
+      // Delete in external provider
+      const extNode = node as ExternalNode;
+      const parsed = owningProvider.parseUri(extNode.uri);
+      if (!parsed) {
+        throw new ProviderError(
+          'INVALID_URI',
+          `Cannot parse URI: ${extNode.uri}`,
+          owningProvider.name,
+        );
+      }
+
+      await owningProvider.delete(parsed.id, options?.context);
+
+      // Remove local materialized copy
+      await baseStore.deleteNode(node.id, { hard: true });
+    },
+
+    // =========================================================================
+    // Task Lifecycle (TaskManageable Trait — Federated)
+    // =========================================================================
+
+    async taskTransition(
+      idOrUri: string,
+      action: TaskAction,
+      options?: TaskTransitionOptions,
+    ): Promise<TaskTransitionResult> {
+      const { provider, providerId } = await resolveTaskProvider(idOrUri);
+
+      const updatedNode = await provider.transitionTask(providerId, action, options?.context);
+
+      // Native provider nodes already exist in the graph store — no materialization needed
+      if (provider.name === 'native') {
+        const node = await baseStore.getNode(updatedNode.id);
+        if (!node) {
+          throw new ProviderError('NOT_FOUND', `Node not found after transition: ${updatedNode.id}`);
+        }
+        return { node, provider: provider.name, action };
+      }
+
+      // Materialize the result for external providers
+      const uri = provider.buildUri(updatedNode.id);
+      const materialized = await materialization.materialize(uri, updatedNode, baseStore);
+
+      return {
+        node: materialized,
+        provider: provider.name,
+        action,
+      };
+    },
+
+    async taskReady(options?: FederatedReadyTaskOptions): Promise<Node[]> {
+      const results: Node[] = [];
+
+      for (const provider of registry.list()) {
+        if (!isTaskManageable(provider)) continue;
+        if (options?.providers && !options.providers.includes(provider.name)) continue;
+
+        const readyNodes = await provider.readyTasks(
+          {
+            limit: options?.limit,
+            tags: options?.tags,
+            priority: options?.priority,
+            assignee: options?.assignee,
+          },
+          options?.context,
+        );
+
+        // Native provider nodes already exist in the graph store — retrieve directly
+        if (provider.name === 'native') {
+          for (const pNode of readyNodes) {
+            const node = await baseStore.getNode(pNode.id);
+            if (node) {
+              results.push(node);
+            }
+          }
+          continue;
+        }
+
+        // Materialize each ready task from external providers so callers get Node objects
+        for (const pNode of readyNodes) {
+          const uri = provider.buildUri(pNode.id);
+          const existing = await findExternalNodeByUri(uri, baseStore);
+          if (existing) {
+            results.push(existing);
+          } else {
+            const materialized = await materialization.materialize(uri, pNode, baseStore);
+            results.push(materialized);
+          }
+        }
+      }
+
+      // Apply global limit after aggregating across providers
+      if (options?.limit && results.length > options.limit) {
+        return results.slice(0, options.limit);
+      }
+
+      return results;
+    },
+
+    async taskAssign(
+      idOrUri: string,
+      assignee: string,
+      options?: TaskTransitionOptions,
+    ): Promise<Node> {
+      const { provider, providerId } = await resolveTaskProvider(idOrUri);
+
+      if (!provider.taskCapabilities.supportsAssignment || !provider.assignTask) {
+        throw new ProviderError(
+          'NOT_SUPPORTED',
+          `Provider ${provider.name} does not support task assignment`,
+          provider.name,
+        );
+      }
+
+      const updatedNode = await provider.assignTask(providerId, assignee, options?.context);
+
+      // Native provider nodes already exist in the graph store — no materialization needed
+      if (provider.name === 'native') {
+        const node = await baseStore.getNode(updatedNode.id);
+        if (!node) {
+          throw new ProviderError('NOT_FOUND', `Node not found after assign: ${updatedNode.id}`);
+        }
+        return node;
+      }
+
+      const uri = provider.buildUri(updatedNode.id);
+      return materialization.materialize(uri, updatedNode, baseStore) as Promise<Node>;
+    },
+
+    async taskValidActions(idOrUri: string): Promise<TaskAction[]> {
+      const { provider, providerId } = await resolveTaskProvider(idOrUri);
+
+      if (provider.validActions) {
+        return provider.validActions(providerId);
+      }
+
+      // Fall back to the provider's declared capabilities
+      return provider.taskCapabilities.actions;
+    },
+  };
+
+  // ===========================================================================
+  // Internal Helper: Resolve a task-capable provider for a given ID or URI
+  // ===========================================================================
+
+  async function resolveTaskProvider(idOrUri: string): Promise<{
+    provider: Provider & import('../providers/traits/TaskManageable.js').TaskManageable;
+    providerId: string;
+  }> {
+    // If it's a local ID, check if it's an external node with a provider URI
+    if (isLocalId(idOrUri)) {
+      const node = await baseStore.getNode(idOrUri);
+      if (!node) {
+        throw new ProviderError('NOT_FOUND', `Node not found: ${idOrUri}`);
+      }
+      if (node.type === 'external') {
+        const extNode = node as ExternalNode;
+        const provider = registry.resolveProvider(extNode.uri);
+        if (!provider) {
+          throw new ProviderError('NOT_FOUND', `No provider found for URI: ${extNode.uri}`);
+        }
+        if (!isTaskManageable(provider)) {
+          throw new ProviderError(
+            'NOT_SUPPORTED',
+            `Provider ${provider.name} does not support task operations`,
+            provider.name,
+          );
+        }
+        const parsed = provider.parseUri(extNode.uri);
+        if (!parsed) {
+          throw new ProviderError('INVALID_URI', `Cannot parse URI: ${extNode.uri}`, provider.name);
+        }
+        return { provider, providerId: parsed.id };
+      }
+      // Local non-external node — check native provider
+      const nativeProvider = registry.get('native');
+      if (!nativeProvider || !isTaskManageable(nativeProvider)) {
+        throw new ProviderError(
+          'NOT_SUPPORTED',
+          'Native provider does not support task operations',
+        );
+      }
+      return {
+        provider: nativeProvider as Provider &
+          import('../providers/traits/TaskManageable.js').TaskManageable,
+        providerId: idOrUri,
+      };
+    }
+
+    // Provider URI
+    const provider = registry.resolveProvider(idOrUri);
+    if (!provider) {
+      throw new ProviderError('NOT_FOUND', `No provider found for: ${idOrUri}`);
+    }
+    if (!isTaskManageable(provider)) {
+      throw new ProviderError(
+        'NOT_SUPPORTED',
+        `Provider ${provider.name} does not support task operations`,
+        provider.name,
+      );
+    }
+    const parsed = provider.parseUri(idOrUri);
+    if (!parsed) {
+      throw new ProviderError('INVALID_URI', `Cannot parse URI: ${idOrUri}`, provider.name);
+    }
+    return { provider, providerId: parsed.id };
+  }
+
+  // ===========================================================================
+  // Internal Helper: Resolve any node by ID or URI (used by resolveNode and providerGet)
+  // ===========================================================================
+
+  async function resolveNodeInternal(
+    idOrUri: string,
+    options?: ResolveOptions,
+    context?: ProviderOperationContext,
+  ): Promise<Node | ProviderNode | null> {
+    // 1. Check if local ID - use existing getNode
+    if (isLocalId(idOrUri)) {
+      return baseStore.getNode(idOrUri);
+    }
+
+    // 2. Check for cached materialized node (unless refresh requested)
+    if (!options?.refresh) {
+      const existing = await findExternalNodeByUri(idOrUri, baseStore);
+      if (existing && !materialization.isStale(existing)) {
+        return existing;
+      }
+    }
+
+    // 3. Find provider for this URI
+    const provider = registry.resolveProvider(idOrUri);
+    if (!provider) {
+      return null;
+    }
+
+    // 4. Parse URI and fetch from provider
+    const parsed = provider.parseUri(idOrUri);
+    if (!parsed) {
+      return null;
+    }
+
+    const providerNode = await provider.get(parsed.id, context);
+    if (!providerNode) {
+      return null;
+    }
+
+    // 5. Materialize if requested or per strategy
+    const shouldMaterialize = materialization.shouldMaterialize(idOrUri, {
+      accessType: 'resolve',
+      explicit: options?.materialize,
+    });
+
+    if (shouldMaterialize) {
+      return materialization.materialize(idOrUri, providerNode, baseStore);
+    }
+
+    // Return provider node directly
+    return providerNode as unknown as Node;
+  }
+
+  // ===========================================================================
+  // Internal Helper: Resolve a node + its owning provider for write operations
+  // ===========================================================================
+
+  async function resolveForWrite(idOrUri: string): Promise<{
+    node: Node;
+    provider: Provider | null;
+    isExternal: boolean;
+  }> {
+    // Case 1: Provider URI (e.g., sudocode://proj/i-456)
+    if (!isLocalId(idOrUri)) {
+      const provider = registry.resolveProvider(idOrUri);
+      if (!provider) {
+        throw new ProviderError('NOT_FOUND', `No provider found for: ${idOrUri}`);
+      }
+
+      // Check if we have a materialized copy
+      const existing = await findExternalNodeByUri(idOrUri, baseStore);
+      if (existing) {
+        return { node: existing, provider, isExternal: true };
+      }
+
+      // No local copy — materialize first so we have a node to return
+      const parsed = provider.parseUri(idOrUri);
+      if (!parsed) {
+        throw new ProviderError('INVALID_URI', `Cannot parse URI: ${idOrUri}`, provider.name);
+      }
+
+      const providerNode = await provider.get(parsed.id);
+      if (!providerNode) {
+        throw new ProviderError('NOT_FOUND', `Node not found: ${idOrUri}`, provider.name);
+      }
+
+      const materialized = await materialization.materialize(idOrUri, providerNode, baseStore);
+      return { node: materialized, provider, isExternal: true };
+    }
+
+    // Case 2: Local ID (s-abc1, i-def2, x-ghi3)
+    const node = await baseStore.getNode(idOrUri);
+    if (!node) {
+      throw new ProviderError('NOT_FOUND', `Node not found: ${idOrUri}`);
+    }
+
+    // Check if it's a materialized external node
+    if (node.type === 'external') {
+      const extNode = node as ExternalNode;
+      const provider = registry.resolveProvider(extNode.uri);
+      return { node, provider, isExternal: true };
+    }
+
+    // Pure local node
+    return { node, provider: null, isExternal: false };
+  }
+
+  return providerStore;
+}