opentasks 0.0.6 → 0.0.7

package/dist/graph/provider-store.js

@@ -11,6 +11,7 @@ import { createNativeProvider } from '../providers/native.js';
 import { createMaterializationManager } from '../providers/materialization.js';
 import { isWatchable, } from '../providers/traits/Watchable.js';
 import { isTaskManageable, } from '../providers/traits/TaskManageable.js';
+import { isReconcilable } from '../providers/traits/Reconcilable.js';
 // ============================================================================
 // Constants
 // ============================================================================
@@ -27,6 +28,23 @@ const LOCAL_ID_PATTERN = /^[ctfex]-[a-z0-9]+$/;
 function isLocalId(idOrUri) {
     return LOCAL_ID_PATTERN.test(idOrUri);
 }
+/**
+ * Check if a node is backed by an external provider (either type:'external'
+ * or a local-provider node with metadata.provider_uri).
+ */
+function isProviderBacked(node) {
+    return node.type === 'external' || typeof node.metadata?.provider_uri === 'string';
+}
+/**
+ * Get the provider URI for a node. For type:'external' nodes, returns the
+ * top-level uri field. For local-provider nodes, returns metadata.provider_uri.
+ * Returns null if the node has no provider binding.
+ */
+function getProviderUri(node) {
+    if (node.type === 'external')
+        return node.uri;
+    return node.metadata?.provider_uri ?? null;
+}
 /**
  * Convert CreateNodeInput to ProviderCreateInput.
  * Passes through tags and parent_id via metadata so providers can use them.
@@ -62,19 +80,94 @@ function toProviderUpdateInput(updates) {
     };
 }
 /**
- * Find external node by URI in the store
+ * Find a materialized node by provider URI.
+ * Searches both type:'external' nodes (by uri field) and local-provider nodes
+ * (by metadata.provider_uri).
  */
 async function findExternalNodeByUri(uri, store) {
-    const nodes = await store.query.nodes({
-        type: 'external',
-    });
-    for (const node of nodes) {
+    // First check type:'external' nodes
+    const externalNodes = await store.query.nodes({ type: 'external' });
+    for (const node of externalNodes) {
         if (node.type === 'external' && node.uri === uri) {
             return node;
         }
     }
+    // Then check local-provider nodes via metadata.provider_uri
+    // Note: search only checks title/content, not metadata. Scan all task/context
+    // nodes and check metadata.provider_uri. Acceptable for local graph sizes.
+    const taskNodes = await store.query.nodes({ type: 'task' });
+    for (const node of taskNodes) {
+        if (node.metadata?.provider_uri === uri) {
+            return node;
+        }
+    }
+    const contextNodes = await store.query.nodes({ type: 'context' });
+    for (const node of contextNodes) {
+        if (node.metadata?.provider_uri === uri) {
+            return node;
+        }
+    }
     return null;
 }
+/**
+ * Extract edge information from a ProviderNode's rawData.
+ * Provider-specific: beads uses blocks/blockedBy/dependencies,
+ * sudocode uses relationships, claude-tasks uses blocks/blockedBy.
+ * Returns normalized edge descriptors with URIs.
+ */
+function extractEdgesFromRawData(providerNode, nodeUri, provider) {
+    const raw = providerNode.rawData;
+    if (!raw)
+        return [];
+    const edges = [];
+    // blocks: this node blocks the listed IDs
+    if (Array.isArray(raw.blocks)) {
+        for (const id of raw.blocks) {
+            if (typeof id === 'string') {
+                edges.push({ fromUri: nodeUri, toUri: provider.buildUri(id), type: 'blocks' });
+            }
+        }
+    }
+    // blockedBy: listed IDs block this node
+    if (Array.isArray(raw.blockedBy)) {
+        for (const id of raw.blockedBy) {
+            if (typeof id === 'string') {
+                edges.push({ fromUri: provider.buildUri(id), toUri: nodeUri, type: 'blocks' });
+            }
+        }
+    }
+    // dependencies: structured format (beads v0.49+)
+    if (Array.isArray(raw.dependencies)) {
+        for (const dep of raw.dependencies) {
+            const d = dep;
+            if (typeof d.depends_on_id === 'string' && typeof d.issue_id === 'string') {
+                edges.push({
+                    fromUri: provider.buildUri(d.depends_on_id),
+                    toUri: provider.buildUri(d.issue_id),
+                    type: 'blocks',
+                });
+            }
+        }
+    }
+    // relationships: sudocode format
+    if (Array.isArray(raw.relationships)) {
+        for (const rel of raw.relationships) {
+            const r = rel;
+            if (typeof r.target_id === 'string' && typeof r.type === 'string') {
+                edges.push({
+                    fromUri: nodeUri,
+                    toUri: provider.buildUri(r.target_id),
+                    type: r.type,
+                });
+            }
+        }
+    }
+    // parent_id: sudocode parent relationship
+    if (typeof raw.parent_id === 'string') {
+        edges.push({ fromUri: provider.buildUri(raw.parent_id), toUri: nodeUri, type: 'parent' });
+    }
+    return edges;
+}
 // ============================================================================
 // Factory Function
 // ============================================================================
@@ -100,6 +193,26 @@ export function createProviderAwareStore(baseStore, config = {}) {
     const changeHandlers = [];
     /** Track which providers are currently being watched */
     const watchedProviders = new Set();
+    // =========================================================================
+    // Pointer-Only Node Cache (session-scoped, in-memory)
+    // =========================================================================
+    /** TTL for pointer cache entries (30 seconds) */
+    const POINTER_CACHE_TTL_MS = 30_000;
+    /** In-memory cache for pointer-only node data resolved from providers */
+    const pointerCache = new Map();
+    function getFromPointerCache(nodeId) {
+        const entry = pointerCache.get(nodeId);
+        if (!entry)
+            return null;
+        if (Date.now() >= entry.expiresAt) {
+            pointerCache.delete(nodeId);
+            return null;
+        }
+        return entry.node;
+    }
+    function setInPointerCache(nodeId, node) {
+        pointerCache.set(nodeId, { node, expiresAt: Date.now() + POINTER_CACHE_TTL_MS });
+    }
     /**
      * Handle an inbound provider change event.
      * Auto-refreshes materialized nodes, then notifies external handlers.
@@ -108,9 +221,9 @@ export function createProviderAwareStore(baseStore, config = {}) {
         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.
+        else if (event.kind === 'edge') {
+            await handleEdgeChange(providerName, event.event);
+        }
         // Notify external handlers
         for (const handler of changeHandlers) {
             try {
@@ -146,15 +259,72 @@ export function createProviderAwareStore(baseStore, config = {}) {
             return;
         }
         // For 'created' (re-appeared) or 'updated': refresh materialized copy
+        const changeProvider = registry.get(_providerName) ?? registry.resolveProvider(event.uri);
         if (event.node) {
             // Provider included the full node data — materialize directly
-            await materialization.materialize(event.uri, event.node, baseStore);
+            await materialization.materialize(event.uri, event.node, baseStore, {
+                local: changeProvider?.local, materializeMode: changeProvider?.materializeMode,
+            });
         }
         else {
             // No node data in event — fetch fresh from provider
-            const provider = registry.resolveProvider(event.uri);
-            if (provider) {
-                await materialization.refresh(existing, provider, baseStore);
+            if (changeProvider) {
+                if (existing.type === 'external') {
+                    await materialization.refresh(existing, changeProvider, baseStore);
+                }
+                else {
+                    // Local-provider node — fetch and re-materialize
+                    const parsed = changeProvider.parseUri(event.uri);
+                    if (parsed) {
+                        const fresh = await changeProvider.get(parsed.id);
+                        if (fresh) {
+                            await materialization.materialize(event.uri, fresh, baseStore, {
+                                local: changeProvider.local, materializeMode: changeProvider.materializeMode,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Handle an edge change from a provider watch event.
+     * Creates or deletes edges in the graph, stamped with edge_source.
+     */
+    async function handleEdgeChange(providerName, event) {
+        // Resolve source and target URIs to local node IDs
+        const fromNode = await findExternalNodeByUri(event.sourceUri, baseStore);
+        const toNode = await findExternalNodeByUri(event.targetUri, baseStore);
+        if (!fromNode || !toNode) {
+            // One or both nodes not materialized — skip edge
+            return;
+        }
+        if (event.type === 'created') {
+            // Check if edge already exists
+            const existingEdges = await baseStore.query.edgesFrom(fromNode.id, event.edge.type);
+            const alreadyExists = existingEdges.some((e) => e.to_id === toNode.id && e.source === providerName);
+            if (!alreadyExists) {
+                await baseStore.createEdge({
+                    from_id: fromNode.id,
+                    to_id: toNode.id,
+                    type: event.edge.type,
+                    metadata: {
+                        edge_source: providerName,
+                        from_uri: event.sourceUri,
+                        to_uri: event.targetUri,
+                        ...event.edge.metadata,
+                    },
+                });
+            }
+        }
+        else if (event.type === 'deleted') {
+            // Find and delete the provider-owned edge
+            const existingEdges = await baseStore.query.edgesFrom(fromNode.id, event.edge.type);
+            for (const edge of existingEdges) {
+                if (edge.to_id === toNode.id &&
+                    (edge.source === providerName || edge.metadata?.edge_source === providerName)) {
+                    await baseStore.deleteEdge(edge.id);
+                }
             }
         }
     }
@@ -190,7 +360,9 @@ export function createProviderAwareStore(baseStore, config = {}) {
                 throw new Error(`Node not found: ${uri}`);
             }
             // Materialize
-            return materialization.materialize(uri, providerNode, baseStore);
+            return materialization.materialize(uri, providerNode, baseStore, {
+                local: provider.local, materializeMode: provider.materializeMode,
+            });
         },
         /**
          * Refresh a materialized external node
@@ -289,7 +461,9 @@ export function createProviderAwareStore(baseStore, config = {}) {
             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);
+            const materializedNode = await materialization.materialize(uri, providerNode, baseStore, {
+                local: provider.local, materializeMode: provider.materializeMode,
+            });
             return {
                 node: materializedNode,
                 uri,
@@ -324,23 +498,24 @@ export function createProviderAwareStore(baseStore, config = {}) {
                 // Local node — update directly
                 return baseStore.updateNode(node.id, updates);
             }
-            // External node but provider not registered — error rather than silent local-only update
+            // Provider-backed node but provider not registered — error rather than silent local-only update
+            const nodeProviderUri = getProviderUri(node);
             if (!owningProvider) {
-                const extNode = node;
-                throw new ProviderError('NOT_FOUND', `Provider not registered for external node URI: ${extNode.uri}. Cannot route update.`);
+                throw new ProviderError('NOT_FOUND', `Provider not registered for node URI: ${nodeProviderUri}. 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;
-            const parsed = owningProvider.parseUri(extNode.uri);
+            // Route update to owning provider
+            const parsed = owningProvider.parseUri(nodeProviderUri);
             if (!parsed) {
-                throw new ProviderError('INVALID_URI', `Cannot parse URI: ${extNode.uri}`, owningProvider.name);
+                throw new ProviderError('INVALID_URI', `Cannot parse URI: ${nodeProviderUri}`, 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);
+            return materialization.materialize(nodeProviderUri, updatedProviderNode, baseStore, {
+                local: owningProvider.local, materializeMode: owningProvider.materializeMode,
+            });
         },
         async providerDelete(idOrUri, options) {
             // Resolve the target node and provider
@@ -350,19 +525,18 @@ export function createProviderAwareStore(baseStore, config = {}) {
                 await baseStore.deleteNode(node.id, options);
                 return;
             }
-            // External node but provider not registered — error rather than silent local-only delete
+            // Provider-backed node but provider not registered — error rather than silent local-only delete
+            const deleteProviderUri = getProviderUri(node);
             if (!owningProvider) {
-                const extNode = node;
-                throw new ProviderError('NOT_FOUND', `Provider not registered for external node URI: ${extNode.uri}. Cannot route delete.`);
+                throw new ProviderError('NOT_FOUND', `Provider not registered for node URI: ${deleteProviderUri}. 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;
-            const parsed = owningProvider.parseUri(extNode.uri);
+            // Delete in owning provider
+            const parsed = owningProvider.parseUri(deleteProviderUri);
             if (!parsed) {
-                throw new ProviderError('INVALID_URI', `Cannot parse URI: ${extNode.uri}`, owningProvider.name);
+                throw new ProviderError('INVALID_URI', `Cannot parse URI: ${deleteProviderUri}`, owningProvider.name);
             }
             await owningProvider.delete(parsed.id, options?.context);
             // Remove local materialized copy
@@ -382,17 +556,97 @@ export function createProviderAwareStore(baseStore, config = {}) {
                 }
                 return { node, provider: provider.name, action };
             }
-            // Materialize the result for external providers
+            // Materialize the result for non-native providers
             const uri = provider.buildUri(updatedNode.id);
-            const materialized = await materialization.materialize(uri, updatedNode, baseStore);
+            const materialized = await materialization.materialize(uri, updatedNode, baseStore, {
+                local: provider.local, materializeMode: provider.materializeMode,
+            });
             return {
                 node: materialized,
                 provider: provider.name,
                 action,
             };
         },
+        async providerListTasks(options) {
+            const results = [];
+            const seenUris = new Set();
+            // 1. Query native graph store for type:'task' nodes
+            const nativeFilter = { type: 'task' };
+            if (options?.status)
+                nativeFilter.status = options.status;
+            if (options?.tags)
+                nativeFilter.tags = options.tags;
+            if (options?.assignee)
+                nativeFilter.assignee = options.assignee;
+            if (options?.search)
+                nativeFilter.search = options.search;
+            const nativeNodes = await baseStore.query.nodes(nativeFilter);
+            const seenIds = new Set();
+            for (const node of nativeNodes) {
+                results.push(node);
+                seenIds.add(node.id);
+                // Track provider URIs from local-provider nodes to prevent duplicates
+                // when the provider federation loop re-discovers the same tasks
+                const pUri = getProviderUri(node);
+                if (pUri) {
+                    seenUris.add(pUri);
+                }
+            }
+            // 2. Query each registered provider's list()
+            for (const provider of registry.list()) {
+                if (provider.name === 'native')
+                    continue; // already covered above
+                if (options?.providers && !options.providers.includes(provider.name))
+                    continue;
+                try {
+                    const providerFilter = {};
+                    if (options?.status) {
+                        providerFilter.status = Array.isArray(options.status) ? options.status[0] : options.status;
+                    }
+                    if (options?.search)
+                        providerFilter.search = options.search;
+                    const providerNodes = await provider.list(providerFilter, options?.context);
+                    for (const pNode of providerNodes) {
+                        const uri = provider.buildUri(pNode.id);
+                        if (seenUris.has(uri))
+                            continue;
+                        seenUris.add(uri);
+                        // Check if already materialized in graph
+                        const existing = await findExternalNodeByUri(uri, baseStore);
+                        if (existing) {
+                            // Avoid pushing the same graph node twice (already in results from native query)
+                            if (!seenIds.has(existing.id)) {
+                                results.push(existing);
+                                seenIds.add(existing.id);
+                            }
+                        }
+                        else {
+                            // Materialize so callers get Node objects with local IDs
+                            const materialized = await materialization.materialize(uri, pNode, baseStore, {
+                                local: provider.local, materializeMode: provider.materializeMode,
+                            });
+                            results.push(materialized);
+                            seenIds.add(materialized.id);
+                        }
+                    }
+                }
+                catch {
+                    // Provider unavailable — skip gracefully
+                }
+            }
+            // 3. Apply limit after aggregation
+            if (options?.limit && results.length > options.limit) {
+                const offset = options?.offset ?? 0;
+                return results.slice(offset, offset + options.limit);
+            }
+            if (options?.offset) {
+                return results.slice(options.offset);
+            }
+            return results;
+        },
         async taskReady(options) {
             const results = [];
+            const seenIds = new Set();
             for (const provider of registry.list()) {
                 if (!isTaskManageable(provider))
                     continue;
@@ -408,22 +662,31 @@ export function createProviderAwareStore(baseStore, config = {}) {
                 if (provider.name === 'native') {
                     for (const pNode of readyNodes) {
                         const node = await baseStore.getNode(pNode.id);
-                        if (node) {
+                        if (node && !seenIds.has(node.id)) {
                             results.push(node);
+                            seenIds.add(node.id);
                         }
                     }
                     continue;
                 }
-                // Materialize each ready task from external providers so callers get Node objects
+                // Materialize each ready task from non-native 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);
+                        if (!seenIds.has(existing.id)) {
+                            results.push(existing);
+                            seenIds.add(existing.id);
+                        }
                     }
                     else {
-                        const materialized = await materialization.materialize(uri, pNode, baseStore);
-                        results.push(materialized);
+                        const materialized = await materialization.materialize(uri, pNode, baseStore, {
+                            local: provider.local, materializeMode: provider.materializeMode,
+                        });
+                        if (!seenIds.has(materialized.id)) {
+                            results.push(materialized);
+                            seenIds.add(materialized.id);
+                        }
                     }
                 }
             }
@@ -448,7 +711,9 @@ export function createProviderAwareStore(baseStore, config = {}) {
                 return node;
             }
             const uri = provider.buildUri(updatedNode.id);
-            return materialization.materialize(uri, updatedNode, baseStore);
+            return materialization.materialize(uri, updatedNode, baseStore, {
+                local: provider.local, materializeMode: provider.materializeMode,
+            });
         },
         async taskValidActions(idOrUri) {
             const { provider, providerId } = await resolveTaskProvider(idOrUri);
@@ -458,33 +723,251 @@ export function createProviderAwareStore(baseStore, config = {}) {
             // Fall back to the provider's declared capabilities
             return provider.taskCapabilities.actions;
         },
+        // ===========================================================================
+        // Reconciliation
+        // ===========================================================================
+        async reconcileProviders(options) {
+            // 1. Scan graph for all provider-authoritative nodes
+            const allNodes = await baseStore.query.nodes({});
+            const authoritativeNodes = allNodes.filter((n) => n.metadata?.provider_authoritative === true);
+            // 2. Filter by options
+            let targetNodes = authoritativeNodes;
+            if (options?.nodeIds) {
+                const idSet = new Set(options.nodeIds);
+                targetNodes = targetNodes.filter((n) => idSet.has(n.id));
+            }
+            if (options?.providers) {
+                const providerSet = new Set(options.providers);
+                targetNodes = targetNodes.filter((n) => typeof n.metadata?.provider_source === 'string' && providerSet.has(n.metadata.provider_source));
+            }
+            // 3. Group by provider_source
+            const grouped = new Map();
+            for (const node of targetNodes) {
+                const source = node.metadata?.provider_source;
+                const uri = getProviderUri(node);
+                if (!source || !uri)
+                    continue;
+                if (!grouped.has(source))
+                    grouped.set(source, []);
+                grouped.get(source).push({ node, providerUri: uri });
+            }
+            const results = [];
+            const skippedProviders = [];
+            // 4. For each provider group
+            for (const [source, nodes] of grouped) {
+                const provider = registry.get(source);
+                // 4a. Check availability
+                if (!provider) {
+                    skippedProviders.push(source);
+                    for (const { node, providerUri } of nodes) {
+                        results.push({ nodeId: node.id, providerUri, status: 'unavailable' });
+                    }
+                    continue;
+                }
+                if (provider.isAvailable) {
+                    const available = await provider.isAvailable();
+                    if (!available) {
+                        skippedProviders.push(source);
+                        for (const { node, providerUri } of nodes) {
+                            results.push({ nodeId: node.id, providerUri, status: 'unavailable' });
+                        }
+                        continue;
+                    }
+                }
+                // 4b. Determine which nodes actually need a full fetch
+                // If the provider is Reconcilable, use batch hashes to skip unchanged nodes
+                let nodesToFetch = nodes;
+                if (isReconcilable(provider)) {
+                    try {
+                        const ids = nodes.map(({ providerUri }) => {
+                            const parsed = provider.parseUri(providerUri);
+                            return parsed?.id;
+                        }).filter((id) => !!id);
+                        const summaries = await provider.listForReconciliation({ ids });
+                        const hashByUri = new Map(summaries.map((s) => [s.uri, s.contentHash]));
+                        // Compare hashes — only fetch nodes whose hash changed or is missing
+                        nodesToFetch = [];
+                        for (const entry of nodes) {
+                            const remoteHash = hashByUri.get(entry.providerUri);
+                            const localHash = entry.node.metadata?.provider_content_hash;
+                            if (remoteHash && localHash && remoteHash === localHash) {
+                                // Hash matches — unchanged, just refresh timestamp
+                                const now = new Date().toISOString();
+                                await baseStore.updateNode(entry.node.id, {
+                                    metadata: {
+                                        ...entry.node.metadata,
+                                        provider_cached_at: now,
+                                        provider_needs_reconcile: undefined,
+                                    },
+                                });
+                                results.push({ nodeId: entry.node.id, providerUri: entry.providerUri, status: 'unchanged' });
+                            }
+                            else {
+                                nodesToFetch.push(entry);
+                            }
+                        }
+                    }
+                    catch {
+                        // Batch path failed — fall back to individual gets
+                        nodesToFetch = nodes;
+                    }
+                }
+                // 4c. Reconcile nodes that need a full fetch via individual get() calls
+                for (const { node, providerUri } of nodesToFetch) {
+                    try {
+                        const parsed = provider.parseUri(providerUri);
+                        if (!parsed) {
+                            results.push({
+                                nodeId: node.id,
+                                providerUri,
+                                status: 'error',
+                                error: `Failed to parse URI: ${providerUri}`,
+                            });
+                            continue;
+                        }
+                        const providerNode = await provider.get(parsed.id);
+                        if (!providerNode) {
+                            // Provider returns null (deleted in provider) — no action (positive-writes-only)
+                            results.push({ nodeId: node.id, providerUri, status: 'unchanged' });
+                            continue;
+                        }
+                        // Compare: did anything change?
+                        const now = new Date().toISOString();
+                        const titleChanged = providerNode.title !== node.title;
+                        const contentChanged = providerNode.content !== (node.content ?? undefined);
+                        const nodeStatus = 'status' in node ? node.status : undefined;
+                        const nodePriority = 'priority' in node ? node.priority : undefined;
+                        const statusChanged = providerNode.status !== nodeStatus;
+                        const priorityChanged = providerNode.priority !== nodePriority;
+                        if (titleChanged || contentChanged || statusChanged || priorityChanged) {
+                            // Update graph node with provider data
+                            const isPointer = node.metadata?.provider_pointer_only === true;
+                            await baseStore.updateNode(node.id, {
+                                ...(isPointer
+                                    ? {}
+                                    : {
+                                        title: providerNode.title,
+                                        content: providerNode.content,
+                                        status: providerNode.status,
+                                        priority: providerNode.priority,
+                                    }),
+                                metadata: {
+                                    ...node.metadata,
+                                    provider_cached_at: isPointer ? undefined : now,
+                                    provider_content_hash: providerNode.contentHash ?? undefined,
+                                    provider_needs_reconcile: undefined, // clear flag
+                                },
+                            });
+                            results.push({ nodeId: node.id, providerUri, status: 'updated' });
+                        }
+                        else {
+                            // Same data — just stamp provider_cached_at and hash
+                            await baseStore.updateNode(node.id, {
+                                metadata: {
+                                    ...node.metadata,
+                                    provider_cached_at: now,
+                                    provider_content_hash: providerNode.contentHash ?? node.metadata?.provider_content_hash,
+                                    provider_needs_reconcile: undefined, // clear flag
+                                },
+                            });
+                            results.push({ nodeId: node.id, providerUri, status: 'unchanged' });
+                        }
+                        // 4d. Edge reconciliation — extract edges from ProviderNode.rawData
+                        //     (zero extra provider calls — piggyback on node data already fetched)
+                        if (providerNode.rawData) {
+                            try {
+                                const rawEdges = extractEdgesFromRawData(providerNode, providerUri, provider);
+                                if (rawEdges.length > 0) {
+                                    // Get existing edges owned by this provider for this node
+                                    const existingEdgesFrom = await baseStore.query.edgesFrom(node.id);
+                                    const existingEdgesTo = await baseStore.query.edgesTo(node.id);
+                                    const allExisting = [...existingEdgesFrom, ...existingEdgesTo];
+                                    const providerOwnedEdges = allExisting.filter((e) => e.source === source || e.metadata?.edge_source === source);
+                                    // Build sets for diffing
+                                    const providerEdgeKeys = new Set(rawEdges.map((pe) => `${pe.fromUri}|${pe.toUri}|${pe.type}`));
+                                    const existingEdgeKeys = new Map();
+                                    for (const e of providerOwnedEdges) {
+                                        const fromUri = e.metadata?.from_uri ?? e.from_id;
+                                        const toUri = e.metadata?.to_uri ?? e.to_id;
+                                        existingEdgeKeys.set(`${fromUri}|${toUri}|${e.type}`, { id: e.id });
+                                    }
+                                    // Add edges that exist in provider but not in graph
+                                    for (const pe of rawEdges) {
+                                        const key = `${pe.fromUri}|${pe.toUri}|${pe.type}`;
+                                        if (!existingEdgeKeys.has(key)) {
+                                            const fromNode = await findExternalNodeByUri(pe.fromUri, baseStore);
+                                            const toNode = await findExternalNodeByUri(pe.toUri, baseStore);
+                                            if (fromNode && toNode) {
+                                                await baseStore.createEdge({
+                                                    from_id: fromNode.id,
+                                                    to_id: toNode.id,
+                                                    type: pe.type,
+                                                    metadata: {
+                                                        edge_source: source,
+                                                        from_uri: pe.fromUri,
+                                                        to_uri: pe.toUri,
+                                                    },
+                                                });
+                                            }
+                                        }
+                                    }
+                                    // Remove edges that exist in graph but not in provider
+                                    for (const [key, edge] of existingEdgeKeys) {
+                                        if (!providerEdgeKeys.has(key)) {
+                                            await baseStore.deleteEdge(edge.id);
+                                        }
+                                    }
+                                }
+                            }
+                            catch {
+                                // Edge reconciliation failure is non-fatal
+                            }
+                        }
+                    }
+                    catch (error) {
+                        // Error fetching — leave node as-is, preserve cached data
+                        results.push({
+                            nodeId: node.id,
+                            providerUri,
+                            status: 'error',
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+            }
+            return {
+                totalNodes: targetNodes.length,
+                results,
+                skippedProviders,
+            };
+        },
     };
     // ===========================================================================
     // Internal Helper: Resolve a task-capable provider for a given ID or URI
     // ===========================================================================
     async function resolveTaskProvider(idOrUri) {
-        // If it's a local ID, check if it's an external node with a provider URI
+        // If it's a local ID, check if it's a provider-backed node
         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;
-                const provider = registry.resolveProvider(extNode.uri);
+            const taskProviderUri = getProviderUri(node);
+            if (taskProviderUri) {
+                const provider = registry.resolveProvider(taskProviderUri);
                 if (!provider) {
-                    throw new ProviderError('NOT_FOUND', `No provider found for URI: ${extNode.uri}`);
+                    throw new ProviderError('NOT_FOUND', `No provider found for URI: ${taskProviderUri}`);
                 }
                 if (!isTaskManageable(provider)) {
                     throw new ProviderError('NOT_SUPPORTED', `Provider ${provider.name} does not support task operations`, provider.name);
                 }
-                const parsed = provider.parseUri(extNode.uri);
+                const parsed = provider.parseUri(taskProviderUri);
                 if (!parsed) {
-                    throw new ProviderError('INVALID_URI', `Cannot parse URI: ${extNode.uri}`, provider.name);
+                    throw new ProviderError('INVALID_URI', `Cannot parse URI: ${taskProviderUri}`, provider.name);
                 }
                 return { provider, providerId: parsed.id };
             }
-            // Local non-external node — check native provider
+            // Local non-provider 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');
@@ -514,13 +997,50 @@ export function createProviderAwareStore(baseStore, config = {}) {
     async function resolveNodeInternal(idOrUri, options, context) {
         // 1. Check if local ID - use existing getNode
         if (isLocalId(idOrUri)) {
-            return baseStore.getNode(idOrUri);
+            const localNode = await baseStore.getNode(idOrUri);
+            if (!localNode)
+                return null;
+            // Transparent pointer-only resolution: fetch real data from provider
+            if (localNode.metadata?.provider_pointer_only === true) {
+                const providerUri = getProviderUri(localNode);
+                if (providerUri) {
+                    // Check session cache first
+                    if (!options?.refresh) {
+                        const cached = getFromPointerCache(localNode.id);
+                        if (cached) {
+                            // Overlay provider data onto the local node shape
+                            return { ...localNode, title: cached.title, content: cached.content ?? localNode.content };
+                        }
+                    }
+                    // Fetch from provider
+                    const provider = registry.resolveProvider(providerUri);
+                    if (provider) {
+                        const parsed = provider.parseUri(providerUri);
+                        if (parsed) {
+                            try {
+                                const fresh = await provider.get(parsed.id, context);
+                                if (fresh) {
+                                    setInPointerCache(localNode.id, fresh);
+                                    return { ...localNode, title: fresh.title, content: fresh.content ?? localNode.content };
+                                }
+                            }
+                            catch {
+                                // Fall through to return stub node
+                            }
+                        }
+                    }
+                }
+            }
+            return localNode;
         }
         // 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;
+            if (existing) {
+                // Local-provider nodes (type !== 'external') are never stale
+                if (existing.type !== 'external' || !materialization.isStale(existing)) {
+                    return existing;
+                }
             }
         }
         // 3. Find provider for this URI
@@ -543,7 +1063,9 @@ export function createProviderAwareStore(baseStore, config = {}) {
             explicit: options?.materialize,
         });
         if (shouldMaterialize) {
-            return materialization.materialize(idOrUri, providerNode, baseStore);
+            return materialization.materialize(idOrUri, providerNode, baseStore, {
+                local: provider.local, materializeMode: provider.materializeMode,
+            });
         }
         // Return provider node directly
         return providerNode;
@@ -572,7 +1094,9 @@ export function createProviderAwareStore(baseStore, config = {}) {
             if (!providerNode) {
                 throw new ProviderError('NOT_FOUND', `Node not found: ${idOrUri}`, provider.name);
             }
-            const materialized = await materialization.materialize(idOrUri, providerNode, baseStore);
+            const materialized = await materialization.materialize(idOrUri, providerNode, baseStore, {
+                local: provider.local, materializeMode: provider.materializeMode,
+            });
             return { node: materialized, provider, isExternal: true };
         }
         // Case 2: Local ID (s-abc1, i-def2, x-ghi3)
@@ -580,13 +1104,13 @@ export function createProviderAwareStore(baseStore, config = {}) {
         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;
-            const provider = registry.resolveProvider(extNode.uri);
+        // Check if it's a provider-backed node (external OR local-provider with metadata.provider_uri)
+        const providerUri = getProviderUri(node);
+        if (providerUri) {
+            const provider = registry.resolveProvider(providerUri);
             return { node, provider, isExternal: true };
         }
-        // Pure local node
+        // Pure local node (no provider binding)
         return { node, provider: null, isExternal: false };
     }
     return providerStore;