obsidian-accomplishments-mcp 0.1.10 → 0.1.11

package/dist/services/v2/v2-runtime.js

@@ -0,0 +1,1908 @@
+/**
+ * V2 Runtime
+ *
+ * Wires all V2 services together and provides dependency implementations
+ * for the V2 MCP tools.
+ */
+import * as fs from 'fs/promises';
+import { watch } from 'fs';
+import * as path from 'path';
+import { getEntityTypeFromId, } from '../../models/v2-types.js';
+import { ProjectIndex } from './index-service.js';
+import { AtomicFileManager } from './file-manager.js';
+import { LifecycleManager } from './lifecycle-manager.js';
+import { PathResolver } from './path-resolver.js';
+import { EntityParser } from './entity-parser.js';
+import { EntitySerializer } from './entity-serializer.js';
+import { SearchIndex } from './search-service.js';
+import { CanvasManager } from './canvas-manager.js';
+/**
+ * Configuration for the Obsidian plugin endpoint.
+ */
+const OBSIDIAN_PLUGIN_ENDPOINT = 'http://127.0.0.1:12312';
+const OBSIDIAN_PLUGIN_TIMEOUT_MS = 5000; // 5 second timeout
+/**
+ * Notify the Obsidian plugin to perform an operation.
+ * This sends a POST request to the plugin's local HTTP endpoint.
+ * The request is fire-and-forget - it does not block the calling operation.
+ *
+ * @param operation - The operation to perform ('populate' or 'reposition')
+ */
+export function notifyObsidianPlugin(operation) {
+    console.error(`[V2Runtime] Notifying Obsidian plugin: action=${operation}`);
+    // Fire-and-forget: don't await the fetch, just let it run in the background
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), OBSIDIAN_PLUGIN_TIMEOUT_MS);
+    fetch(OBSIDIAN_PLUGIN_ENDPOINT, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ action: operation }),
+        signal: controller.signal,
+    })
+        .then((response) => {
+        clearTimeout(timeoutId);
+        if (response.ok) {
+            console.error(`[V2Runtime] Obsidian plugin notification successful: action=${operation}`);
+        }
+        else {
+            console.error(`[V2Runtime] Obsidian plugin notification failed: ${response.status} ${response.statusText}`);
+        }
+    })
+        .catch((error) => {
+        clearTimeout(timeoutId);
+        if (error instanceof Error && error.name === 'AbortError') {
+            console.error(`[V2Runtime] Obsidian plugin notification timed out after ${OBSIDIAN_PLUGIN_TIMEOUT_MS}ms`);
+        }
+        else {
+            // Silently log errors - plugin might not be running
+            // This is expected when Obsidian is not open
+            console.error(`[V2Runtime] Could not notify Obsidian plugin (may not be running):`, error instanceof Error ? error.message : error);
+        }
+    });
+}
+// =============================================================================
+// V2 Runtime Class
+// =============================================================================
+/**
+ * V2 Runtime - orchestrates all V2 services and provides dependency implementations.
+ */
+export class V2Runtime {
+    config;
+    index;
+    fileManager;
+    lifecycleManager;
+    pathResolver;
+    parser;
+    serializer;
+    searchIndex;
+    canvasManager;
+    // File watchers
+    watchers = [];
+    // Debounce timers for file changes
+    debounceTimers = new Map();
+    DEBOUNCE_MS = 100;
+    // ID prefix mapping for each entity type
+    idPrefixes = new Map([
+        ['milestone', 'M'],
+        ['story', 'S'],
+        ['task', 'T'],
+        ['decision', 'DEC'],
+        ['document', 'DOC'],
+        ['feature', 'F'],
+    ]);
+    // Track duplicate IDs (id -> array of file paths)
+    duplicateIds = new Map();
+    constructor(config) {
+        this.config = config;
+        this.index = new ProjectIndex();
+        this.fileManager = new AtomicFileManager(config.vaultPath);
+        this.lifecycleManager = new LifecycleManager();
+        this.pathResolver = new PathResolver(config);
+        this.parser = new EntityParser();
+        this.serializer = new EntitySerializer();
+        this.searchIndex = new SearchIndex();
+        this.canvasManager = new CanvasManager(config.vaultPath, config.defaultCanvas, async (entityId) => {
+            const entity = await this.getEntity(entityId);
+            return entity?.vault_path || null;
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Initialization
+    // ---------------------------------------------------------------------------
+    /** Initialize the runtime by scanning the vault and starting file watchers */
+    async initialize() {
+        await this.scanVault();
+        this.startFileWatchers();
+    }
+    /** Shutdown the runtime and cleanup resources */
+    async shutdown() {
+        this.stopFileWatchers();
+    }
+    /** Get the canvas manager for direct canvas operations */
+    getCanvasManager() {
+        return this.canvasManager;
+    }
+    /** Scan vault and build indexes */
+    async scanVault() {
+        const folders = this.pathResolver.getAllAbsoluteEntityFolders();
+        console.error(`[V2Runtime] Scanning ${folders.length} entity folders:`, folders);
+        let totalEntities = 0;
+        for (const folder of folders) {
+            const count = await this.scanFolder(folder);
+            totalEntities += count;
+        }
+        console.error(`[V2Runtime] Scan complete. Found ${totalEntities} entities. Index size: ${this.index.getAll().length}`);
+    }
+    /** Recursively scan a folder for entity files */
+    async scanFolder(folder) {
+        let count = 0;
+        try {
+            const entries = await fs.readdir(folder, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(folder, entry.name);
+                if (entry.isDirectory()) {
+                    // Recursively scan subdirectories
+                    count += await this.scanFolder(fullPath);
+                }
+                else if (entry.isFile() && entry.name.endsWith('.md')) {
+                    const entity = await this.loadEntity(fullPath);
+                    if (entity)
+                        count++;
+                }
+            }
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                console.error(`[V2Runtime] Folder does not exist (skipping): ${folder}`);
+            }
+            else {
+                console.error(`[V2Runtime] Error scanning folder ${folder}:`, err);
+            }
+        }
+        return count;
+    }
+    /** Load a single entity from file and update ProjectIndex */
+    async loadEntity(absolutePath) {
+        try {
+            const content = await fs.readFile(absolutePath, 'utf-8');
+            const vaultPath = this.pathResolver.toVaultPath(absolutePath);
+            const result = this.parser.parse(content, vaultPath);
+            const entity = result.entity;
+            // Check for duplicate ID
+            const existingPaths = this.duplicateIds.get(entity.id);
+            if (existingPaths) {
+                // Already have this ID - add to duplicates list
+                if (!existingPaths.includes(absolutePath)) {
+                    existingPaths.push(absolutePath);
+                    console.warn(`[V2Runtime] Duplicate entity ID detected: ${entity.id}\n` +
+                        `  Files with this ID:\n` +
+                        existingPaths.map(p => `    - ${p}`).join('\n'));
+                }
+            }
+            else {
+                // Check if entity already exists in ProjectIndex (first duplicate detection)
+                const existingMetadata = this.index.get(entity.id);
+                if (existingMetadata) {
+                    const originalPath = this.pathResolver.toAbsolutePath(existingMetadata.vault_path);
+                    if (originalPath !== absolutePath) {
+                        const paths = [originalPath, absolutePath];
+                        this.duplicateIds.set(entity.id, paths);
+                        console.warn(`[V2Runtime] Duplicate entity ID detected: ${entity.id}\n` +
+                            `  Files with this ID:\n` +
+                            paths.map(p => `    - ${p}`).join('\n'));
+                    }
+                }
+            }
+            // Index for search
+            this.searchIndex.index(entity.id, entity.title, this.getEntityContent(entity), entity.type, entity.archived || false);
+            // Get file mtime for metadata
+            const stats = await fs.stat(absolutePath);
+            const fileMtime = stats.mtimeMs;
+            // Remove old relationships if entity was already indexed (re-load case)
+            this.removeRelationships(entity.id);
+            // Index metadata in ProjectIndex (this is the single source of truth)
+            const metadata = this.createEntityMetadata(entity, fileMtime);
+            this.index.set(metadata);
+            // Index relationships in ProjectIndex
+            this.indexRelationships(entity);
+            return entity;
+        }
+        catch (err) {
+            console.error(`Error loading entity from ${absolutePath}:`, err);
+            return null;
+        }
+    }
+    /** Remove entity from index by file path (safe delete) */
+    removeEntityByPath(absolutePath) {
+        const vaultPath = this.pathResolver.toVaultPath(absolutePath);
+        // Find entity by vault_path in ProjectIndex
+        const entityId = this.index.getIdByPath(vaultPath);
+        if (entityId) {
+            // Safe delete: only remove entity if this path is the canonical path for this ID
+            // This handles the case where duplicate files with the same ID existed
+            const canonicalPath = this.index.getPathById(entityId);
+            if (canonicalPath === vaultPath) {
+                // This is the canonical file - remove the entity entirely
+                this.searchIndex.remove(entityId);
+                this.removeRelationships(entityId);
+                this.index.delete(entityId);
+            }
+            else {
+                // This was a duplicate file - just remove the stale path mapping
+                console.warn(`[V2Runtime] Removing stale path mapping for ${entityId}: ${vaultPath} (canonical: ${canonicalPath})`);
+                this.index.removePathMapping(vaultPath);
+            }
+        }
+    }
+    /** Get content from entity for search indexing */
+    getEntityContent(entity) {
+        switch (entity.type) {
+            case 'milestone': return entity.objective || '';
+            case 'story': {
+                const s = entity;
+                const parts = [s.outcome, s.notes].filter(Boolean);
+                return parts.join(' ');
+            }
+            case 'task': {
+                const t = entity;
+                const parts = [t.goal, t.description, t.technical_notes, t.notes].filter(Boolean);
+                return parts.join(' ');
+            }
+            case 'decision': {
+                const d = entity;
+                const parts = [d.context, d.decision, d.rationale].filter(Boolean);
+                return parts.join(' ');
+            }
+            case 'document': return entity.content || '';
+            case 'feature': {
+                const f = entity;
+                // Return actual markdown content if available, otherwise user_story
+                return f.content || f.user_story || '';
+            }
+            default: return '';
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Index Relationship Management
+    // ---------------------------------------------------------------------------
+    /**
+     * Index all relationships for an entity into ProjectIndex.
+     * This enables O(1) lookups for dependencies, children, etc.
+     */
+    indexRelationships(entity) {
+        // Parent-child relationships (Story -> Milestone, Task -> Story)
+        if (entity.type === 'story' && entity.parent) {
+            this.index.addRelationship(entity.parent, 'parent_of', entity.id);
+        }
+        if (entity.type === 'task' && entity.parent) {
+            this.index.addRelationship(entity.parent, 'parent_of', entity.id);
+        }
+        // Dependency relationships: depends_on means "I am blocked by these"
+        // So if A depends_on B, then B blocks A
+        const dependsOn = entity.depends_on;
+        if (dependsOn && Array.isArray(dependsOn)) {
+            for (const depId of dependsOn) {
+                this.index.addRelationship(depId, 'blocks', entity.id);
+            }
+        }
+        // Implementation relationships (Story implements Document)
+        if (entity.type === 'story' && entity.implements) {
+            for (const docId of entity.implements) {
+                this.index.addRelationship(entity.id, 'implements', docId);
+            }
+        }
+        if (entity.type === 'milestone' && entity.implements) {
+            for (const docId of entity.implements) {
+                this.index.addRelationship(entity.id, 'implements', docId);
+            }
+        }
+        // Supersedes relationships (Decision supersedes Decision)
+        if (entity.type === 'decision' && entity.supersedes) {
+            this.index.addRelationship(entity.id, 'supersedes', entity.supersedes);
+        }
+        // Versioning relationships (Document previous_version -> next_version)
+        if (entity.type === 'document' && entity.previous_version) {
+            this.index.addRelationship(entity.id, 'previous_version', entity.previous_version);
+        }
+    }
+    /**
+     * Remove forward relationships for an entity from ProjectIndex.
+     * Called before re-indexing an entity's relationships.
+     *
+     * Excludes `parent_of` and `blocks` relationships because those are "owned" by
+     * other entities (children and dependents respectively), not by this entity.
+     * - `parent_of` is indexed when a child sets its `parent` field
+     * - `blocks` is indexed when a dependent sets its `depends_on` field
+     */
+    removeRelationships(entityId) {
+        // Exclude parent_of and blocks - these are indexed by children/dependents
+        this.index.removeForwardRelationships(entityId, ['parent_of', 'blocks']);
+    }
+    /**
+     * Create EntityMetadata from an Entity for the primary index.
+     */
+    createEntityMetadata(entity, fileMtime = 0) {
+        const metadata = {
+            id: entity.id,
+            type: entity.type,
+            title: entity.title,
+            workstream: entity.workstream,
+            status: entity.status,
+            archived: entity.archived,
+            in_progress: this.isEntityInProgress(entity),
+            canvas_source: entity.canvas_source,
+            vault_path: entity.vault_path,
+            updated_at: entity.updated_at,
+            file_mtime: fileMtime,
+            children_count: 0, // Will be updated when children are indexed
+        };
+        // Add type-specific fields
+        if (entity.type === 'milestone') {
+            metadata.priority = entity.priority;
+        }
+        if (entity.type === 'story') {
+            metadata.priority = entity.priority;
+            metadata.parent_id = entity.parent;
+        }
+        if (entity.type === 'task') {
+            metadata.parent_id = entity.parent;
+        }
+        return metadata;
+    }
+    /**
+     * Check if an entity is in progress.
+     */
+    isEntityInProgress(entity) {
+        if (entity.type === 'milestone' || entity.type === 'story' || entity.type === 'task' || entity.type === 'feature') {
+            return entity.status === 'In Progress';
+        }
+        return false;
+    }
+    // ---------------------------------------------------------------------------
+    // File Watching
+    // ---------------------------------------------------------------------------
+    /** Start file watchers for all entity folders */
+    startFileWatchers() {
+        const folders = this.pathResolver.getAllAbsoluteEntityFolders();
+        for (const folder of folders) {
+            try {
+                const watcher = watch(folder, { persistent: true }, (eventType, filename) => {
+                    if (!filename || !filename.endsWith('.md'))
+                        return;
+                    const absolutePath = path.join(folder, filename);
+                    this.handleFileChange(eventType, absolutePath);
+                });
+                this.watchers.push(watcher);
+            }
+            catch (err) {
+                // Folder might not exist yet - that's okay
+                if (err.code !== 'ENOENT') {
+                    console.error(`Error watching folder ${folder}:`, err);
+                }
+            }
+        }
+    }
+    /** Stop all file watchers */
+    stopFileWatchers() {
+        for (const watcher of this.watchers) {
+            watcher.close();
+        }
+        this.watchers = [];
+        // Clear any pending debounce timers
+        for (const timer of this.debounceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+    }
+    /** Handle file change event with debouncing */
+    handleFileChange(eventType, absolutePath) {
+        // Clear existing timer for this path
+        const existingTimer = this.debounceTimers.get(absolutePath);
+        if (existingTimer) {
+            clearTimeout(existingTimer);
+        }
+        // Set new debounced handler
+        const timer = setTimeout(async () => {
+            this.debounceTimers.delete(absolutePath);
+            await this.processFileChange(absolutePath);
+        }, this.DEBOUNCE_MS);
+        this.debounceTimers.set(absolutePath, timer);
+    }
+    /** Process a file change after debouncing */
+    async processFileChange(absolutePath) {
+        try {
+            // Check if file exists
+            await fs.access(absolutePath);
+            // File exists - reload it (handles both create and modify)
+            await this.loadEntity(absolutePath);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                // File was deleted - remove from cache
+                this.removeEntityByPath(absolutePath);
+            }
+            else {
+                console.error(`Error processing file change for ${absolutePath}:`, err);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Core Entity Operations
+    // ---------------------------------------------------------------------------
+    /** Get entity by ID - loads from disk using ProjectIndex */
+    async getEntity(id) {
+        const metadata = this.index.get(id);
+        if (!metadata) {
+            // Entity not in index
+            return null;
+        }
+        if (!metadata.vault_path) {
+            console.error(`[V2Runtime] Entity ${id} has no vault_path in index`);
+            return null;
+        }
+        const absolutePath = this.pathResolver.toAbsolutePath(metadata.vault_path);
+        try {
+            const content = await fs.readFile(absolutePath, 'utf-8');
+            const result = this.parser.parse(content, metadata.vault_path);
+            return result.entity;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                // File doesn't exist - remove stale entry from index
+                console.warn(`[V2Runtime] Removing stale index entry for ${id} - file not found: ${absolutePath}`);
+                this.index.delete(id);
+                this.searchIndex.remove(id);
+            }
+            else {
+                console.error(`[V2Runtime] Error reading entity ${id} from ${absolutePath}:`, err);
+            }
+            return null;
+        }
+    }
+    /** Get all entities - loads from disk using ProjectIndex */
+    async getAllEntities(options) {
+        // First filter metadata from ProjectIndex (fast)
+        let metadataList = this.index.getAll();
+        if (!options?.includeArchived) {
+            metadataList = metadataList.filter((m) => !m.archived);
+        }
+        if (!options?.includeCompleted) {
+            metadataList = metadataList.filter((m) => m.status !== 'Completed');
+        }
+        if (options?.workstream) {
+            metadataList = metadataList.filter((m) => m.workstream === options.workstream);
+        }
+        if (options?.types) {
+            metadataList = metadataList.filter((m) => options.types.includes(m.type));
+        }
+        // Then load full entities from disk (only for filtered results)
+        const entities = [];
+        for (const metadata of metadataList) {
+            const entity = await this.getEntity(metadata.id);
+            if (entity) {
+                entities.push(entity);
+            }
+        }
+        return entities;
+    }
+    /** Get entity status */
+    getEntityStatus(entity) {
+        switch (entity.type) {
+            case 'milestone': return entity.status;
+            case 'story': return entity.status;
+            case 'task': return entity.status;
+            case 'decision': return entity.status;
+            case 'document': return entity.status;
+            case 'feature': return entity.status;
+            default: return 'Unknown';
+        }
+    }
+    /** Get entity workstream */
+    getEntityWorkstream(entity) {
+        switch (entity.type) {
+            case 'milestone': return entity.workstream;
+            case 'story': return entity.workstream;
+            case 'task': return entity.workstream || '';
+            case 'decision': return entity.workstream;
+            case 'document': return entity.workstream;
+            case 'feature': return entity.workstream || '';
+            default: return '';
+        }
+    }
+    /**
+     * Get the highest ID number for a given entity type by scanning vault files.
+     * This ensures we never generate duplicate IDs even if entities were created
+     * by the Obsidian plugin while the MCP server was running.
+     *
+     * NOTE: This scans the vault on every call to guarantee accuracy.
+     * The index may be stale if the plugin creates entities.
+     */
+    async getHighestIdForType(type) {
+        const prefix = this.idPrefixes.get(type);
+        if (!prefix)
+            return 0;
+        let highest = 0;
+        const folders = this.pathResolver.getAllAbsoluteEntityFolders();
+        for (const folder of folders) {
+            try {
+                const files = await this.getAllMarkdownFilesInFolder(folder);
+                for (const filePath of files) {
+                    try {
+                        const content = await fs.readFile(filePath, 'utf-8');
+                        const vaultPath = this.pathResolver.toVaultPath(filePath);
+                        const result = this.parser.parse(content, vaultPath);
+                        // Only consider entities of the target type
+                        if (result.entity.type === type) {
+                            // Extract numeric part from ID (e.g., "S-042" -> 42)
+                            const match = result.entity.id.match(new RegExp(`^${prefix}-(\\d+)$`));
+                            if (match) {
+                                const num = parseInt(match[1], 10);
+                                if (num > highest) {
+                                    highest = num;
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // Skip files that can't be parsed (not entities)
+                        continue;
+                    }
+                }
+            }
+            catch (err) {
+                const error = err;
+                if (error.code !== 'ENOENT') {
+                    console.error(`[V2Runtime] Error scanning folder ${folder}:`, err);
+                }
+            }
+        }
+        return highest;
+    }
+    /**
+     * Get all markdown files in a folder (recursively)
+     */
+    async getAllMarkdownFilesInFolder(folder) {
+        const files = [];
+        try {
+            const entries = await fs.readdir(folder, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(folder, entry.name);
+                if (entry.isDirectory()) {
+                    // Recursively scan subdirectories
+                    const subFiles = await this.getAllMarkdownFilesInFolder(fullPath);
+                    files.push(...subFiles);
+                }
+                else if (entry.isFile() && entry.name.endsWith('.md')) {
+                    files.push(fullPath);
+                }
+            }
+        }
+        catch (err) {
+            const error = err;
+            if (error.code !== 'ENOENT') {
+                console.error(`[V2Runtime] Error reading folder ${folder}:`, err);
+            }
+        }
+        return files;
+    }
+    /** Get next ID for entity type (zero-padded to 3 digits) */
+    async getNextId(type) {
+        // Scan the vault to find the highest existing ID for this type
+        // This prevents ID collisions with entities created by the Obsidian plugin
+        const highest = await this.getHighestIdForType(type);
+        const next = highest + 1;
+        const prefix = this.idPrefixes.get(type);
+        if (!prefix) {
+            throw new Error(`Unknown entity type: ${type}`);
+        }
+        // Zero-pad to 3 digits (e.g., S-001, M-012, T-123)
+        const padded = String(next).padStart(3, '0');
+        return `${prefix}-${padded}`;
+    }
+    /** Get all duplicate entity IDs and their file paths */
+    getDuplicateIds() {
+        return new Map(this.duplicateIds);
+    }
+    /** Check if there are any duplicate IDs */
+    hasDuplicateIds() {
+        return this.duplicateIds.size > 0;
+    }
+    /** Check if an entity exists in the index */
+    entityExists(id) {
+        return this.index.has(id);
+    }
+    /** Get entity type from ID (from index) */
+    getEntityTypeFromCache(id) {
+        const metadata = this.index.get(id);
+        return metadata?.type ?? null;
+    }
+    /** Write entity to file */
+    async writeEntity(entity) {
+        const filePath = this.pathResolver.getEntityPath(entity.id, entity.title);
+        const absolutePath = this.pathResolver.toAbsolutePath(filePath);
+        // Check if entity exists at a different path (title change scenario)
+        // If so, delete the old file to prevent duplicates
+        const existingPath = this.index.getPathById(entity.id);
+        if (existingPath && existingPath !== filePath) {
+            const oldAbsolutePath = this.pathResolver.toAbsolutePath(existingPath);
+            try {
+                await fs.unlink(oldAbsolutePath);
+                // Remove old path mapping
+                this.index.removePathMapping(existingPath);
+                console.error(`[V2Runtime] Deleted old file after title change: ${existingPath} -> ${filePath}`);
+            }
+            catch (err) {
+                if (err.code !== 'ENOENT') {
+                    console.error(`[V2Runtime] Error deleting old file ${oldAbsolutePath}:`, err);
+                }
+            }
+        }
+        // Set vault_path on entity before serializing
+        entity.vault_path = filePath;
+        const content = this.serializer.serialize(entity);
+        // Ensure directory exists
+        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+        await fs.writeFile(absolutePath, content, 'utf-8');
+        // Update search index
+        this.searchIndex.index(entity.id, entity.title, this.getEntityContent(entity), entity.type, entity.archived || false);
+        // Get file mtime for metadata
+        const stats = await fs.stat(absolutePath);
+        const fileMtime = stats.mtimeMs;
+        // Remove old relationships (in case entity was updated)
+        this.removeRelationships(entity.id);
+        // Update ProjectIndex metadata
+        const metadata = this.createEntityMetadata(entity, fileMtime);
+        this.index.set(metadata);
+        // Re-index relationships
+        this.indexRelationships(entity);
+        // Sync bidirectional implements/implemented_by relationships
+        await this.syncBidirectionalRelationships(entity);
+        // Notify Obsidian plugin to refresh canvas (fire-and-forget)
+        notifyObsidianPlugin('populate');
+    }
+    /**
+     * Sync all bidirectional relationships.
+     * Ensures consistency across all symmetric relationship pairs:
+     * - parent ↔ children
+     * - depends_on ↔ blocks
+     * - implements ↔ implemented_by
+     * - supersedes ↔ superseded_by
+     * - previous_version ↔ next_version
+     */
+    async syncBidirectionalRelationships(entity) {
+        // 1. Hierarchy: parent ↔ children
+        await this.syncParentChildRelationship(entity);
+        // 2. Dependencies: depends_on ↔ blocks
+        await this.syncDependencyRelationship(entity);
+        // 3. Implementation: implements ↔ implemented_by
+        await this.syncImplementsRelationship(entity);
+        // 4. Supersession: supersedes ↔ superseded_by (Decision only)
+        await this.syncSupersedesRelationship(entity);
+        // 5. Versioning: previous_version ↔ next_version (Document only)
+        await this.syncVersioningRelationship(entity);
+    }
+    /**
+     * Sync parent ↔ children relationship.
+     */
+    async syncParentChildRelationship(entity) {
+        if (entity.type === 'story') {
+            const story = entity;
+            if (story.parent) {
+                await this.ensureChildInParent(story.parent, story.id);
+            }
+        }
+        else if (entity.type === 'task') {
+            const task = entity;
+            if (task.parent) {
+                await this.ensureChildInParent(task.parent, task.id);
+            }
+        }
+        else if (entity.type === 'milestone') {
+            const milestone = entity;
+            if (milestone.children && milestone.children.length > 0) {
+                for (const childId of milestone.children) {
+                    await this.ensureParentInChild(childId, milestone.id);
+                }
+            }
+        }
+    }
+    /**
+     * Sync depends_on ↔ blocks relationship.
+     */
+    async syncDependencyRelationship(entity) {
+        const dependsOn = entity.depends_on;
+        if (dependsOn && dependsOn.length > 0) {
+            for (const depId of dependsOn) {
+                await this.ensureAffects(depId, entity.id);
+            }
+        }
+        const affects = entity.affects;
+        if (affects && affects.length > 0) {
+            for (const affectedId of affects) {
+                await this.ensureDependsOn(affectedId, entity.id);
+            }
+        }
+    }
+    /**
+     * Sync implements ↔ implemented_by relationship.
+     */
+    async syncImplementsRelationship(entity) {
+        if (entity.type === 'story' || entity.type === 'milestone') {
+            const implements_ = entity.implements;
+            if (implements_ && implements_.length > 0) {
+                for (const targetId of implements_) {
+                    // Check if it's a document or feature ID
+                    const targetType = getEntityTypeFromId(targetId);
+                    if (targetType === 'document') {
+                        await this.ensureImplementedBy(targetId, entity.id);
+                    }
+                    else if (targetType === 'feature') {
+                        await this.ensureFeatureImplementedBy(targetId, entity.id);
+                    }
+                }
+            }
+        }
+        else if (entity.type === 'document') {
+            const implementedBy = entity.implemented_by;
+            if (implementedBy && implementedBy.length > 0) {
+                for (const storyId of implementedBy) {
+                    await this.ensureImplements(storyId, entity.id);
+                }
+            }
+        }
+        else if (entity.type === 'feature') {
+            const implementedBy = entity.implemented_by;
+            if (implementedBy && implementedBy.length > 0) {
+                for (const implementerId of implementedBy) {
+                    await this.ensureImplementsFeature(implementerId, entity.id);
+                }
+            }
+        }
+    }
+    /**
+     * Sync supersedes ↔ superseded_by relationship (Decision only).
+     */
+    async syncSupersedesRelationship(entity) {
+        if (entity.type !== 'decision')
+            return;
+        const decision = entity;
+        if (decision.supersedes) {
+            await this.ensureSupersededBy(decision.supersedes, decision.id);
+        }
+        if (decision.superseded_by) {
+            await this.ensureSupersedes(decision.superseded_by, decision.id);
+        }
+    }
+    /**
+     * Sync previous_version ↔ next_version relationship (Document only).
+     */
+    async syncVersioningRelationship(entity) {
+        if (entity.type !== 'document')
+            return;
+        const document = entity;
+        if (document.previous_version) {
+            await this.ensureNextVersion(document.previous_version, document.id);
+        }
+        if (document.next_version) {
+            await this.ensurePreviousVersion(document.next_version, document.id);
+        }
+    }
+    /**
+     * Ensure a parent entity's children array includes the given child ID.
+     */
+    async ensureChildInParent(parentId, childId) {
+        const parent = await this.getEntity(parentId);
+        if (!parent)
+            return;
+        if (parent.type === 'milestone') {
+            const milestone = parent;
+            const currentChildren = milestone.children || [];
+            if (currentChildren.includes(childId))
+                return;
+            milestone.children = [...currentChildren, childId];
+            milestone.updated_at = new Date().toISOString();
+            await this.writeEntityDirect(milestone);
+            console.error(`[V2Runtime] Synced children: added ${childId} to ${parentId}`);
+        }
+        else if (parent.type === 'story') {
+            const story = parent;
+            const currentChildren = story.children || [];
+            if (currentChildren.includes(childId))
+                return;
+            story.children = [...currentChildren, childId];
+            story.updated_at = new Date().toISOString();
+            await this.writeEntityDirect(story);
+            console.error(`[V2Runtime] Synced children: added ${childId} to ${parentId}`);
+        }
+    }
+    /**
+     * Ensure a child entity's parent field is set to the given parent ID.
+     */
+    async ensureParentInChild(childId, parentId) {
+        const child = await this.getEntity(childId);
+        if (!child)
+            return;
+        if (child.type === 'story') {
+            const story = child;
+            if (story.parent === parentId)
+                return;
+            story.parent = parentId;
+            story.updated_at = new Date().toISOString();
+            await this.writeEntityDirect(story);
+            console.error(`[V2Runtime] Synced parent: set ${parentId} on ${childId}`);
+        }
+        else if (child.type === 'task') {
+            const task = child;
+            if (task.parent === parentId)
+                return;
+            task.parent = parentId;
+            task.updated_at = new Date().toISOString();
+            await this.writeEntityDirect(task);
+            console.error(`[V2Runtime] Synced parent: set ${parentId} on ${childId}`);
+        }
+    }
+    /**
+     * Ensure an entity's affects array includes the given affected ID.
+     */
+    async ensureAffects(affecterId, affectedId) {
+        const affecter = await this.getEntity(affecterId);
+        if (!affecter)
+            return;
+        const currentAffects = affecter.affects || [];
+        if (currentAffects.includes(affectedId))
+            return;
+        affecter.affects = [...currentAffects, affectedId];
+        affecter.updated_at = new Date().toISOString();
+        await this.writeEntityDirect(affecter);
+        console.error(`[V2Runtime] Synced affects: added ${affectedId} to ${affecterId}`);
+    }
+    /**
+     * Ensure an entity's depends_on array includes the given dependency ID.
+     */
+    async ensureDependsOn(entityId, dependencyId) {
+        const entity = await this.getEntity(entityId);
+        if (!entity)
+            return;
+        const currentDependsOn = entity.depends_on || [];
+        if (currentDependsOn.includes(dependencyId))
+            return;
+        entity.depends_on = [...currentDependsOn, dependencyId];
+        entity.updated_at = new Date().toISOString();
+        await this.writeEntityDirect(entity);
+        console.error(`[V2Runtime] Synced depends_on: added ${dependencyId} to ${entityId}`);
+    }
+    /**
+     * Ensure a decision's superseded_by field is set.
+     */
+    async ensureSupersededBy(oldDecisionId, newDecisionId) {
+        const oldDecision = await this.getEntity(oldDecisionId);
+        if (!oldDecision || oldDecision.type !== 'decision')
+            return;
+        const decision = oldDecision;
+        if (decision.superseded_by === newDecisionId)
+            return;
+        decision.superseded_by = newDecisionId;
+        decision.updated_at = new Date().toISOString();
+        await this.writeEntityDirect(decision);
+        console.error(`[V2Runtime] Synced superseded_by: set ${newDecisionId} on ${oldDecisionId}`);
+    }
+    /**
+     * Ensure a decision's supersedes field is set.
+     */
+    async ensureSupersedes(newDecisionId, oldDecisionId) {
+        const newDecision = await this.getEntity(newDecisionId);
+        if (!newDecision || newDecision.type !== 'decision')
+            return;
+        const decision = newDecision;
+        if (decision.supersedes === oldDecisionId)
+            return;
+        decision.supersedes = oldDecisionId;
+        decision.updated_at = new Date().toISOString();
+        await this.writeEntityDirect(decision);
+        console.error(`[V2Runtime] Synced supersedes: set ${oldDecisionId} on ${newDecisionId}`);
+    }
+    /**
+     * Ensure a document's next_version field is set.
+     */
+    async ensureNextVersion(oldDocId, newDocId) {
+        const oldDoc = await this.getEntity(oldDocId);
+        if (!oldDoc || oldDoc.type !== 'document')
+            return;
+        const document = oldDoc;
+        if (document.next_version === newDocId)
+            return;
+        document.next_version = newDocId;
+        document.updated_at = new Date().toISOString();
+        await this.writeEntityDirect(document);
+        console.error(`[V2Runtime] Synced next_version: set ${newDocId} on ${oldDocId}`);
+    }
+    /**
+     * Ensure a document's previous_version field is set.
+     */
+    async ensurePreviousVersion(newDocId, oldDocId) {
+        const newDoc = await this.getEntity(newDocId);
+        if (!newDoc || newDoc.type !== 'document')
+            return;
+        const document = newDoc;
+        if (document.previous_version === oldDocId)
+            return;
+        document.previous_version = oldDocId;
+        document.updated_at = new Date().toISOString();
+        await this.writeEntityDirect(document);
+        console.error(`[V2Runtime] Synced previous_version: set ${oldDocId} on ${newDocId}`);
+    }
+    async ensureImplementedBy(docId, implementerId) {
+        const doc = await this.getEntity(docId);
+        if (!doc || doc.type !== 'document')
+            return;
+        const document = doc;
+        const currentImplementedBy = document.implemented_by || [];
+        // Check if already present
+        if (currentImplementedBy.includes(implementerId))
+            return;
+        // Add the implementer and save
+        document.implemented_by = [...currentImplementedBy, implementerId];
+        document.updated_at = new Date().toISOString();
+        // Write directly to avoid infinite recursion (don't call writeEntity)
+        await this.writeEntityDirect(document);
+        console.error(`[V2Runtime] Synced implemented_by: added ${implementerId} to ${docId}`);
+    }
+    /**
+     * Ensure a Story/Milestone's implements includes the given document ID.
+     * Only updates if the relationship is missing.
+     */
+    async ensureImplements(entityId, docId) {
+        const entity = await this.getEntity(entityId);
+        if (!entity)
+            return;
+        if (entity.type === 'story') {
+            const story = entity;
+            const currentImplements = story.implements || [];
+            if (currentImplements.includes(docId))
+                return;
+            story.implements = [...currentImplements, docId];
+            story.updated_at = new Date().toISOString();
+            await this.writeEntityDirect(story);
+            console.error(`[V2Runtime] Synced implements: added ${docId} to ${entityId}`);
+        }
+        else if (entity.type === 'milestone') {
+            const milestone = entity;
+            const currentImplements = milestone.implements || [];
+            if (currentImplements.includes(docId))
+                return;
+            milestone.implements = [...currentImplements, docId];
+            milestone.updated_at = new Date().toISOString();
+            await this.writeEntityDirect(milestone);
+            console.error(`[V2Runtime] Synced implements: added ${docId} to ${entityId}`);
+        }
+    }
+    /**
+     * Ensure a Feature's implemented_by includes the given story/milestone ID.
+     */
+    async ensureFeatureImplementedBy(featureId, implementerId) {
+        const feat = await this.getEntity(featureId);
+        if (!feat || feat.type !== 'feature')
+            return;
+        const feature = feat;
+        const currentImplementedBy = feature.implemented_by || [];
+        // Check if already present
+        if (currentImplementedBy.includes(implementerId))
+            return;
+        // Add the implementer and save
+        feature.implemented_by = [...currentImplementedBy, implementerId];
+        feature.updated_at = new Date().toISOString();
+        await this.writeEntityDirect(feature);
+        console.error(`[V2Runtime] Synced implemented_by: added ${implementerId} to ${featureId}`);
+    }
+    /**
+     * Ensure a Story/Milestone's implements includes the given feature ID.
+     */
+    async ensureImplementsFeature(entityId, featureId) {
+        const entity = await this.getEntity(entityId);
+        if (!entity)
+            return;
+        if (entity.type === 'story') {
+            const story = entity;
+            const currentImplements = story.implements || [];
+            if (currentImplements.includes(featureId))
+                return;
+            story.implements = [...currentImplements, featureId];
+            story.updated_at = new Date().toISOString();
+            await this.writeEntityDirect(story);
+            console.error(`[V2Runtime] Synced implements: added ${featureId} to ${entityId}`);
+        }
+        else if (entity.type === 'milestone') {
+            const milestone = entity;
+            const currentImplements = milestone.implements || [];
+            if (currentImplements.includes(featureId))
+                return;
+            milestone.implements = [...currentImplements, featureId];
+            milestone.updated_at = new Date().toISOString();
+            await this.writeEntityDirect(milestone);
+            console.error(`[V2Runtime] Synced implements: added ${featureId} to ${entityId}`);
+        }
+    }
+    /**
+     * Write entity directly without triggering relationship sync (to avoid recursion).
+     */
+    async writeEntityDirect(entity) {
+        const filePath = this.pathResolver.getEntityPath(entity.id, entity.title);
+        const absolutePath = this.pathResolver.toAbsolutePath(filePath);
+        entity.vault_path = filePath;
+        const content = this.serializer.serialize(entity);
+        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+        await fs.writeFile(absolutePath, content, 'utf-8');
+        // Update indexes
+        this.searchIndex.index(entity.id, entity.title, this.getEntityContent(entity), entity.type, entity.archived || false);
+        const stats = await fs.stat(absolutePath);
+        this.removeRelationships(entity.id);
+        const metadata = this.createEntityMetadata(entity, stats.mtimeMs);
+        this.index.set(metadata);
+        this.indexRelationships(entity);
+    }
+    /** Get children of an entity - uses ProjectIndex for O(1) lookup */
+    async getChildren(parentId) {
+        // Use ProjectIndex relationship graph for O(1) lookup
+        // parent_of relationship: parent -> child
+        const childIds = this.index.getRelated(parentId, 'parent_of');
+        const children = [];
+        for (const childId of childIds) {
+            const entity = await this.getEntity(childId);
+            if (entity) {
+                children.push(entity);
+            }
+        }
+        return children;
+    }
+    /** Get parent of an entity */
+    async getParent(id) {
+        const entity = await this.getEntity(id);
+        if (!entity)
+            return null;
+        let parentId;
+        if (entity.type === 'story') {
+            parentId = entity.parent;
+        }
+        else if (entity.type === 'task') {
+            parentId = entity.parent;
+        }
+        return parentId ? this.getEntity(parentId) : null;
+    }
+    /** Get siblings of an entity */
+    async getSiblings(id) {
+        const entity = await this.getEntity(id);
+        if (!entity)
+            return [];
+        const parent = await this.getParent(id);
+        if (!parent) {
+            // Top-level entity - siblings are same type (use ProjectIndex)
+            const allMetadata = this.index.getAll();
+            const siblings = [];
+            for (const m of allMetadata) {
+                if (m.type === entity.type && m.id !== id) {
+                    const sibling = await this.getEntity(m.id);
+                    if (sibling) {
+                        siblings.push(sibling);
+                    }
+                }
+            }
+            return siblings;
+        }
+        const children = await this.getChildren(parent.id);
+        return children.filter(c => c.id !== id);
+    }
+    /** Get entity path */
+    async getEntityPath(id) {
+        const entity = await this.getEntity(id);
+        if (!entity)
+            return '';
+        return this.pathResolver.getEntityPath(id, entity.title);
+    }
+    // ---------------------------------------------------------------------------
+    // Dependency Operations
+    // ---------------------------------------------------------------------------
+    /**
+     * Get entities that this entity depends on (what blocks this entity).
+     * Uses ProjectIndex relationship graph for O(1) lookup.
+     *
+     * If entity A has depends_on: [B], then A is blocked by B.
+     * This returns [B] when called with A's id.
+     */
+    async getDependencies(id) {
+        // In the index: B blocks A is stored as forward(B, 'blocks', A)
+        // So to find what blocks A, we look at reverse relationships
+        const blockerIds = this.index.getRelatedReverse(id, 'blocks');
+        const deps = [];
+        for (const depId of blockerIds) {
+            const dep = await this.getEntity(depId);
+            if (dep)
+                deps.push(dep);
+        }
+        return deps;
+    }
+    /**
+     * Get entities that depend on this entity (what this entity blocks).
+     * Uses ProjectIndex relationship graph for O(1) lookup.
+     *
+     * If entity A has depends_on: [B], then B blocks A.
+     * This returns [A] when called with B's id.
+     */
+    async getDependents(id) {
+        // In the index: B blocks A is stored as forward(B, 'blocks', A)
+        // So to find what B blocks, we look at forward relationships
+        const dependentIds = this.index.getRelated(id, 'blocks');
+        const dependents = [];
+        for (const depId of dependentIds) {
+            const dep = await this.getEntity(depId);
+            if (dep)
+                dependents.push(dep);
+        }
+        return dependents;
+    }
+    // ---------------------------------------------------------------------------
+    // Status Operations
+    // ---------------------------------------------------------------------------
+    /** Validate status transition */
+    validateStatusTransition(entity, newStatus) {
+        // Use lifecycle manager's canTransition method
+        const result = this.lifecycleManager.canTransition(entity, newStatus);
+        return { valid: result.allowed, reason: result.reason };
+    }
+    /** Compute cascade effects of status change */
+    async computeCascadeEffects(entity, newStatus) {
+        // For now, return empty - cascade logic can be added later
+        return [];
+    }
+    // ---------------------------------------------------------------------------
+    // Archive Operations
+    // ---------------------------------------------------------------------------
+    /** Move entity to archive */
+    async moveToArchive(id, archivePath) {
+        const entity = await this.getEntity(id);
+        if (!entity)
+            throw new Error(`Entity not found: ${id}`);
+        const currentPath = this.pathResolver.getEntityPath(id, entity.title);
+        // If archivePath is provided, it's a folder path - append the filename
+        // Otherwise use the full archive path from path resolver
+        let targetPath;
+        if (archivePath) {
+            const filename = path.basename(currentPath);
+            targetPath = path.join(archivePath, filename);
+        }
+        else {
+            targetPath = this.pathResolver.getArchivePath(id, entity.title);
+        }
+        const absoluteCurrent = this.pathResolver.toAbsolutePath(currentPath);
+        const absoluteTarget = this.pathResolver.toAbsolutePath(targetPath);
+        // Ensure archive directory exists
+        await fs.mkdir(path.dirname(absoluteTarget), { recursive: true });
+        // Move file
+        await fs.rename(absoluteCurrent, absoluteTarget);
+        // Update entity on disk with archived flag
+        entity.archived = true;
+        entity.vault_path = targetPath;
+        const content = this.serializer.serialize(entity);
+        await fs.writeFile(absoluteTarget, content, 'utf-8');
+        // Update ProjectIndex with new path and archived status
+        const stats = await fs.stat(absoluteTarget);
+        const metadata = this.createEntityMetadata(entity, stats.mtimeMs);
+        this.index.set(metadata);
+        // Notify Obsidian plugin to refresh canvas (fire-and-forget)
+        notifyObsidianPlugin('populate');
+        return targetPath;
+    }
+    /** Restore entity from archive */
+    async restoreFromArchive(id) {
+        const entity = await this.getEntity(id);
+        if (!entity)
+            throw new Error(`Entity not found: ${id}`);
+        const archivePath = this.pathResolver.getArchivePath(id, entity.title);
+        const targetPath = this.pathResolver.getEntityPath(id, entity.title);
+        const absoluteArchive = this.pathResolver.toAbsolutePath(archivePath);
+        const absoluteTarget = this.pathResolver.toAbsolutePath(targetPath);
+        // Ensure target directory exists
+        await fs.mkdir(path.dirname(absoluteTarget), { recursive: true });
+        // Move file
+        await fs.rename(absoluteArchive, absoluteTarget);
+        // Update entity on disk with archived flag
+        entity.archived = false;
+        entity.vault_path = targetPath;
+        const content = this.serializer.serialize(entity);
+        await fs.writeFile(absoluteTarget, content, 'utf-8');
+        // Update ProjectIndex with new path and archived status
+        const stats = await fs.stat(absoluteTarget);
+        const metadata = this.createEntityMetadata(entity, stats.mtimeMs);
+        this.index.set(metadata);
+        // Notify Obsidian plugin to refresh canvas (fire-and-forget)
+        notifyObsidianPlugin('populate');
+        return targetPath;
+    }
+    // ---------------------------------------------------------------------------
+    // Conversion Helpers
+    // ---------------------------------------------------------------------------
+    /** Convert entity to summary */
+    toEntitySummary(entity) {
+        const summary = {
+            id: entity.id,
+            type: entity.type,
+            title: entity.title,
+            status: this.getEntityStatus(entity),
+            workstream: this.getEntityWorkstream(entity),
+            last_updated: entity.updated_at || new Date().toISOString(),
+        };
+        // Add parent for stories and tasks
+        if ('parent' in entity && entity.parent) {
+            const parentEntity = this.index.get(entity.parent);
+            summary.parent = {
+                id: entity.parent,
+                title: parentEntity?.title || 'Unknown',
+            };
+        }
+        return summary;
+    }
+    /** Convert entity to full representation */
+    async toEntityFull(entity) {
+        const summary = this.toEntitySummary(entity);
+        const children = await this.getChildren(entity.id);
+        // Get dependencies using the indexed relationships
+        const dependencies = await this.getDependencies(entity.id);
+        const dependents = await this.getDependents(entity.id);
+        // Build the full entity representation
+        const full = {
+            ...summary,
+            content: this.getEntityContent(entity),
+            children_count: children.length,
+            children: children.map(c => this.toEntitySummary(c)),
+            dependencies: {
+                blocks: dependents.map(e => e.id), // Entities that this entity blocks
+                blocked_by: dependencies.map(e => e.id), // Entities that block this entity
+            },
+            dependency_details: {
+                blocks: dependents.map(e => this.toEntitySummary(e)),
+                blocked_by: dependencies.map(e => this.toEntitySummary(e)),
+            },
+        };
+        // Add type-specific fields
+        if (entity.type === 'milestone' || entity.type === 'story') {
+            full.priority = entity.priority;
+        }
+        // Add document-specific fields
+        if (entity.type === 'document') {
+            const doc = entity;
+            if (doc.documents && doc.documents.length > 0) {
+                full.documents = doc.documents;
+            }
+        }
+        // Add feature-specific fields
+        if (entity.type === 'feature') {
+            const feature = entity;
+            full.user_story = feature.user_story;
+            full.tier = feature.tier;
+            full.phase = feature.phase;
+            if (feature.documented_by && feature.documented_by.length > 0) {
+                full.documented_by = feature.documented_by;
+            }
+            if (feature.implemented_by && feature.implemented_by.length > 0) {
+                full.implemented_by = feature.implemented_by;
+            }
+            if (feature.decided_by && feature.decided_by.length > 0) {
+                full.decided_by = feature.decided_by;
+            }
+            if (feature.test_refs && feature.test_refs.length > 0) {
+                full.test_refs = feature.test_refs;
+            }
+        }
+        return full;
+    }
+    /** Get current timestamp */
+    getCurrentTimestamp() {
+        return new Date().toISOString();
+    }
+    // ---------------------------------------------------------------------------
+    // Search Operations
+    // ---------------------------------------------------------------------------
+    /** Search entities */
+    async searchEntities(query, options) {
+        const results = this.searchIndex.search(query, {
+            types: options?.types,
+            includeArchived: options?.archived,
+            limit: options?.limit,
+        });
+        const output = [];
+        for (const result of results) {
+            const entity = await this.getEntity(result.id);
+            if (!entity)
+                continue;
+            // Apply additional filters
+            if (options?.statuses && !options.statuses.includes(this.getEntityStatus(entity))) {
+                continue;
+            }
+            if (options?.workstreams && !options.workstreams.includes(this.getEntityWorkstream(entity))) {
+                continue;
+            }
+            output.push({
+                entity,
+                score: result.score,
+                snippet: this.getEntityContent(entity).substring(0, 200),
+            });
+        }
+        return output;
+    }
+    /** Get task progress for a story */
+    async getTaskProgress(storyId) {
+        const children = await this.getChildren(storyId);
+        const tasks = children.filter(c => c.type === 'task');
+        const completed = tasks.filter(t => t.status === 'Completed').length;
+        return { total: tasks.length, completed };
+    }
+    // ---------------------------------------------------------------------------
+    // Decision & Document Operations
+    // ---------------------------------------------------------------------------
+    /** Get all decisions */
+    async getAllDecisions(options) {
+        const entities = await this.getAllEntities({
+            includeArchived: options?.includeArchived,
+            includeCompleted: true,
+            types: ['decision'],
+            workstream: options?.workstream,
+        });
+        let decisions = entities;
+        if (!options?.includeSuperseded) {
+            decisions = decisions.filter(d => d.status !== 'Superseded');
+        }
+        return decisions;
+    }
+    /** Get all documents */
+    async getAllDocuments(options) {
+        const entities = await this.getAllEntities({
+            includeArchived: false,
+            includeCompleted: true,
+            types: ['document'],
+            workstream: options?.workstream,
+        });
+        return entities;
+    }
+    /** Get all stories */
+    async getAllStories(options) {
+        const entities = await this.getAllEntities({
+            includeArchived: false,
+            includeCompleted: true,
+            types: ['story'],
+            workstream: options?.workstream,
+        });
+        let stories = entities;
+        if (options?.priorities) {
+            stories = stories.filter(s => options.priorities.includes(s.priority || 'Medium'));
+        }
+        return stories;
+    }
+    /** Get all features */
+    async getAllFeatures(options) {
+        const entities = await this.getAllEntities({
+            includeArchived: false,
+            includeCompleted: true,
+            types: ['feature'],
+            workstream: options?.workstream,
+        });
+        let features = entities;
+        if (options?.tier) {
+            features = features.filter(f => f.tier === options.tier);
+        }
+        if (options?.phase) {
+            // Use String() to ensure consistent comparison (phase might be passed as number)
+            const phaseStr = String(options.phase);
+            features = features.filter(f => f.phase === phaseStr);
+        }
+        if (!options?.includeDeferred) {
+            features = features.filter(f => f.status !== 'Deferred');
+        }
+        return features;
+    }
+    /** Create a decision */
+    async createDecision(data) {
+        const id = await this.getNextId('decision');
+        const now = this.getCurrentTimestamp();
+        const decision = {
+            id,
+            type: 'decision',
+            title: data.title,
+            context: data.context,
+            decision: data.decision,
+            rationale: data.rationale,
+            workstream: data.workstream,
+            decided_by: data.decided_by,
+            decided_on: now,
+            status: 'Decided',
+            affects: data.affects || [],
+            supersedes: data.supersedes,
+            archived: false,
+            created_at: now,
+            updated_at: now,
+            canvas_source: '',
+            cssclasses: [],
+            vault_path: '',
+        };
+        await this.writeEntity(decision);
+        return decision;
+    }
+    /** Update a document */
+    async updateDocument(id, data) {
+        const entity = await this.getEntity(id);
+        if (!entity || entity.type !== 'document') {
+            throw new Error(`Document not found: ${id}`);
+        }
+        const updated = {
+            ...entity,
+            ...data,
+            updated_at: this.getCurrentTimestamp(),
+        };
+        await this.writeEntity(updated);
+        return updated;
+    }
+    /** Get decisions affecting a document */
+    async getDecisionsAffectingDocument(docId) {
+        const decisions = await this.getAllDecisions({ includeSuperseded: true });
+        // For now, return decisions that reference this document
+        // This would need more sophisticated tracking in a real implementation
+        return decisions.filter(d => d.affects?.includes(docId));
+    }
+    /** Generate entity ID - uses vault scanning for consistency */
+    async generateId(type) {
+        // Scan the vault to find the highest existing ID for this type
+        // This prevents ID collisions with entities created by the Obsidian plugin
+        const highest = await this.getHighestIdForType(type);
+        const next = highest + 1;
+        const prefix = this.idPrefixes.get(type);
+        if (!prefix) {
+            throw new Error(`Unknown entity type: ${type}`);
+        }
+        const padded = String(next).padStart(3, '0');
+        return `${prefix}-${padded}`;
+    }
+    // ---------------------------------------------------------------------------
+    // Implementation Handoff Operations
+    // ---------------------------------------------------------------------------
+    /** Get related decisions for an entity */
+    async getRelatedDecisions(entityId) {
+        const decisions = await this.getAllDecisions();
+        return decisions.filter(d => d.affects?.includes(entityId));
+    }
+    /** Get blocking entities */
+    async getBlockingEntities(entityId) {
+        return this.getDependencies(entityId);
+    }
+    /** Check if entity has open TODOs */
+    async hasOpenTodos(entityId) {
+        const entity = await this.getEntity(entityId);
+        if (!entity)
+            return false;
+        const content = this.getEntityContent(entity);
+        return content.includes('- [ ]') || content.includes('TODO');
+    }
+    /** Get acceptance criteria */
+    async getAcceptanceCriteria(entityId) {
+        const entity = await this.getEntity(entityId);
+        if (!entity || entity.type !== 'story')
+            return [];
+        return entity.acceptance_criteria || [];
+    }
+    /** Get implementation context */
+    async getImplementationContext(entityId) {
+        const entity = await this.getEntity(entityId);
+        if (!entity)
+            return undefined;
+        // Implementation context would be stored in entity metadata
+        return entity.implementation_context;
+    }
+    /** Get related documents */
+    async getRelatedDocuments(entityId) {
+        const entity = await this.getEntity(entityId);
+        if (!entity)
+            return [];
+        const implements_ = entity.implements;
+        if (!implements_)
+            return [];
+        const docs = [];
+        for (const docId of implements_) {
+            const doc = await this.getEntity(docId);
+            if (doc && doc.type === 'document') {
+                docs.push(doc);
+            }
+        }
+        return docs;
+    }
+    /** Search content for pattern */
+    async searchContent(entityId, pattern) {
+        const entity = await this.getEntity(entityId);
+        if (!entity)
+            return false;
+        const content = this.getEntityContent(entity);
+        return content.toLowerCase().includes(pattern.toLowerCase());
+    }
+    // ---------------------------------------------------------------------------
+    // Relationship Reconciliation
+    // ---------------------------------------------------------------------------
+    /**
+     * Reconcile all implements/implemented_by relationships across the vault.
+     * This scans all entities and ensures bidirectional consistency:
+     * - If Story/Milestone has `implements: [DOC-001]`, ensure DOC-001 has `implemented_by: [S-001]`
+     * - If Document has `implemented_by: [S-001]`, ensure S-001 has `implements: [DOC-001]`
+     *
+     * @param options.dry_run If true, only report what would be changed without making changes
+     * @returns Summary of reconciliation actions taken
+     */
+    async reconcileImplementsRelationships(options) {
+        const dryRun = options?.dry_run ?? false;
+        const details = [];
+        const changes = [];
+        const warnings = [];
+        let updated = 0;
+        // Get all entities
+        const allIds = this.index.getAllIds();
+        // First pass: collect all implements relationships from stories/milestones
+        // Separate maps for documents and features since they have different ID types
+        const docImplementsMap = new Map();
+        const featureImplementsMap = new Map();
+        for (const id of allIds) {
+            const entity = await this.getEntity(id);
+            if (!entity)
+                continue;
+            if (entity.type === 'story' || entity.type === 'milestone') {
+                const implements_ = entity.implements;
+                if (implements_ && implements_.length > 0) {
+                    for (const targetId of implements_) {
+                        const targetType = getEntityTypeFromId(targetId);
+                        if (targetType === 'document') {
+                            const docId = targetId;
+                            if (!docImplementsMap.has(docId)) {
+                                docImplementsMap.set(docId, new Set());
+                            }
+                            docImplementsMap.get(docId).add(id);
+                        }
+                        else if (targetType === 'feature') {
+                            const featureId = targetId;
+                            if (!featureImplementsMap.has(featureId)) {
+                                featureImplementsMap.set(featureId, new Set());
+                            }
+                            featureImplementsMap.get(featureId).add(id);
+                        }
+                    }
+                }
+            }
+        }
+        // Second pass: update documents with missing implemented_by
+        for (const id of allIds) {
+            const entity = await this.getEntity(id);
+            if (!entity || entity.type !== 'document')
+                continue;
+            const doc = entity;
+            const expectedImplementers = docImplementsMap.get(doc.id) || new Set();
+            const currentImplementedBy = new Set(doc.implemented_by || []);
+            // Check for references to non-existent entities
+            for (const implementerId of currentImplementedBy) {
+                if (!this.entityExists(implementerId)) {
+                    warnings.push({
+                        entity_id: doc.id,
+                        issue: `References non-existent entity ${implementerId} in implemented_by`,
+                    });
+                }
+            }
+            // Find missing implementers
+            const missingImplementers = [];
+            for (const implementerId of expectedImplementers) {
+                if (!currentImplementedBy.has(implementerId)) {
+                    missingImplementers.push(implementerId);
+                }
+            }
+            if (missingImplementers.length > 0) {
+                // Add to changes array (new format)
+                changes.push({
+                    entity_id: doc.id,
+                    field: 'implemented_by',
+                    action: 'added',
+                    values: missingImplementers,
+                    reason: `Synced from ${missingImplementers.map(id => `${id}.implements`).join(', ')}`,
+                });
+                if (!dryRun) {
+                    doc.implemented_by = [...(doc.implemented_by || []), ...missingImplementers];
+                    doc.updated_at = new Date().toISOString();
+                    await this.writeEntityDirect(doc);
+                    updated++;
+                }
+                // Legacy details format
+                for (const implementerId of missingImplementers) {
+                    details.push({
+                        entity_id: doc.id,
+                        action: 'added_implemented_by',
+                        related_id: implementerId,
+                    });
+                }
+            }
+        }
+        // Second pass (features): update features with missing implemented_by
+        for (const id of allIds) {
+            const entity = await this.getEntity(id);
+            if (!entity || entity.type !== 'feature')
+                continue;
+            const feature = entity;
+            const expectedImplementers = featureImplementsMap.get(feature.id) || new Set();
+            const currentImplementedBy = new Set(feature.implemented_by || []);
+            // Check for references to non-existent entities
+            for (const implementerId of currentImplementedBy) {
+                if (!this.entityExists(implementerId)) {
+                    warnings.push({
+                        entity_id: feature.id,
+                        issue: `References non-existent entity ${implementerId} in implemented_by`,
+                    });
+                }
+            }
+            // Find missing implementers
+            const missingImplementers = [];
+            for (const implementerId of expectedImplementers) {
+                if (!currentImplementedBy.has(implementerId)) {
+                    missingImplementers.push(implementerId);
+                }
+            }
+            if (missingImplementers.length > 0) {
+                // Add to changes array (new format)
+                changes.push({
+                    entity_id: feature.id,
+                    field: 'implemented_by',
+                    action: 'added',
+                    values: missingImplementers,
+                    reason: `Synced from ${missingImplementers.map(id => `${id}.implements`).join(', ')}`,
+                });
+                if (!dryRun) {
+                    feature.implemented_by = [...(feature.implemented_by || []), ...missingImplementers];
+                    feature.updated_at = new Date().toISOString();
+                    await this.writeEntityDirect(feature);
+                    updated++;
+                }
+                for (const implementerId of missingImplementers) {
+                    details.push({
+                        entity_id: feature.id,
+                        action: 'added_implemented_by',
+                        related_id: implementerId,
+                    });
+                }
+            }
+        }
+        // Third pass: collect all implemented_by from documents and update stories/milestones
+        const implementedByMap = new Map();
+        for (const id of allIds) {
+            const entity = await this.getEntity(id);
+            if (!entity || entity.type !== 'document')
+                continue;
+            const doc = entity;
+            if (doc.implemented_by && doc.implemented_by.length > 0) {
+                for (const storyId of doc.implemented_by) {
+                    if (!implementedByMap.has(storyId)) {
+                        implementedByMap.set(storyId, new Set());
+                    }
+                    implementedByMap.get(storyId).add(doc.id);
+                }
+            }
+        }
+        // Fourth pass: update stories/milestones with missing implements
+        for (const id of allIds) {
+            const entity = await this.getEntity(id);
+            if (!entity)
+                continue;
+            if (entity.type !== 'story' && entity.type !== 'milestone')
+                continue;
+            const storyOrMilestone = entity;
+            const expectedDocs = implementedByMap.get(id) || new Set();
+            const currentImplements = new Set(storyOrMilestone.implements || []);
+            // Check for references to non-existent entities
+            for (const targetId of currentImplements) {
+                if (!this.entityExists(targetId)) {
+                    warnings.push({
+                        entity_id: entity.id,
+                        issue: `References non-existent entity ${targetId} in implements`,
+                    });
+                }
+            }
+            // Find missing docs
+            const missingDocs = [];
+            for (const docId of expectedDocs) {
+                if (!currentImplements.has(docId)) {
+                    missingDocs.push(docId);
+                }
+            }
+            if (missingDocs.length > 0) {
+                // Add to changes array (new format)
+                changes.push({
+                    entity_id: entity.id,
+                    field: 'implements',
+                    action: 'added',
+                    values: missingDocs,
+                    reason: `Synced from ${missingDocs.map(id => `${id}.implemented_by`).join(', ')}`,
+                });
+                if (!dryRun) {
+                    if (entity.type === 'story') {
+                        entity.implements = [...(entity.implements || []), ...missingDocs];
+                    }
+                    else {
+                        entity.implements = [...(entity.implements || []), ...missingDocs];
+                    }
+                    entity.updated_at = new Date().toISOString();
+                    await this.writeEntityDirect(entity);
+                    updated++;
+                }
+                // Legacy details format
+                for (const docId of missingDocs) {
+                    details.push({
+                        entity_id: entity.id,
+                        action: 'added_implements',
+                        related_id: docId,
+                    });
+                }
+            }
+        }
+        return {
+            scanned: allIds.length,
+            updated: dryRun ? 0 : updated,
+            dry_run: dryRun,
+            changes,
+            warnings,
+            details,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Dependency Provider Methods
+    // ---------------------------------------------------------------------------
+    /** Get entity management dependencies */
+    getEntityManagementDeps() {
+        return {
+            getEntity: (id) => this.getEntity(id),
+            getNextId: (type) => this.getNextId(type),
+            getChildren: (id) => this.getChildren(id),
+            entityExists: (id) => this.entityExists(id),
+            getEntityType: (id) => this.getEntityTypeFromCache(id),
+            writeEntity: (entity) => this.writeEntity(entity),
+            moveToArchive: (id, path) => this.moveToArchive(id, path),
+            restoreFromArchive: (id) => this.restoreFromArchive(id),
+            validateStatusTransition: (entity, status) => this.validateStatusTransition(entity, status),
+            computeCascadeEffects: (entity, status) => this.computeCascadeEffects(entity, status),
+            toEntityFull: (entity) => this.toEntityFull(entity),
+            getCurrentTimestamp: () => this.getCurrentTimestamp(),
+            // Canvas operations
+            addToCanvas: async (entity, canvasPath) => {
+                const nodeId = await this.canvasManager.addNode(entity.vault_path, canvasPath, undefined, this.canvasManager.getDimensionsForType(entity.type));
+                return nodeId !== null;
+            },
+            removeFromCanvas: async (id, canvasPath) => {
+                const entity = await this.getEntity(id);
+                if (!entity)
+                    return false;
+                return this.canvasManager.removeNode(entity.vault_path, canvasPath);
+            },
+        };
+    }
+    /** Get batch operations dependencies */
+    getBatchOperationsDeps() {
+        return {
+            createEntity: async (type, data) => {
+                const id = await this.getNextId(type);
+                const now = this.getCurrentTimestamp();
+                // Build entity with all required base fields plus type-specific data
+                const baseFields = {
+                    id,
+                    type,
+                    created_at: now,
+                    updated_at: now,
+                    archived: false,
+                    canvas_source: '',
+                    cssclasses: [],
+                    vault_path: '',
+                };
+                // Merge with provided data (which should include title, workstream, status, etc.)
+                const entity = { ...baseFields, ...data };
+                await this.writeEntity(entity);
+                return entity;
+            },
+            getEntity: (id) => this.getEntity(id),
+            entityExists: (id) => this.entityExists(id),
+            getEntityType: (id) => this.getEntityTypeFromCache(id),
+            updateEntityStatus: async (id, status) => {
+                const entity = await this.getEntity(id);
+                if (!entity)
+                    throw new Error(`Entity not found: ${id}`);
+                entity.status = status;
+                entity.updated_at = this.getCurrentTimestamp();
+                await this.writeEntity(entity);
+            },
+            writeEntity: (entity) => this.writeEntity(entity),
+            archiveEntity: (id, path) => this.moveToArchive(id, path).then(() => { }),
+            getChildren: (id) => this.getChildren(id),
+            validateStatusTransition: (entity, status) => this.validateStatusTransition(entity, status),
+            computeCascadeEffects: (entity, status) => this.computeCascadeEffects(entity, status),
+            getCurrentTimestamp: () => this.getCurrentTimestamp(),
+            // Canvas operations
+            addToCanvas: async (entity, canvasPath) => {
+                const nodeId = await this.canvasManager.addNode(entity.vault_path, canvasPath, undefined, this.canvasManager.getDimensionsForType(entity.type));
+                return nodeId !== null;
+            },
+            removeFromCanvas: async (id, canvasPath) => {
+                const entity = await this.getEntity(id);
+                if (!entity)
+                    return false;
+                return this.canvasManager.removeNode(entity.vault_path, canvasPath);
+            },
+            toEntityFull: (entity) => this.toEntityFull(entity),
+        };
+    }
+    /** Get project understanding dependencies */
+    getProjectUnderstandingDeps() {
+        return {
+            getAllEntities: (options) => this.getAllEntities(options),
+            toEntitySummary: (entity) => this.toEntitySummary(entity),
+            getBlockers: (id) => this.getDependencies(id),
+            getBlockedBy: (id) => this.getDependents(id),
+            getLastUpdated: (entity) => new Date(entity.updated_at || entity.created_at || Date.now()),
+        };
+    }
+    /** Get search navigation dependencies */
+    getSearchNavigationDeps() {
+        return {
+            searchEntities: (query, options) => this.searchEntities(query, options),
+            getAllEntities: (options) => this.getAllEntities(options),
+            getEntity: (id) => this.getEntity(id),
+            getEntityPath: (id) => this.getEntityPath(id),
+            toEntitySummary: (entity) => this.toEntitySummary(entity),
+            toEntityFull: (entity) => this.toEntityFull(entity),
+            getParent: (id) => this.getParent(id),
+            getChildren: (id) => this.getChildren(id),
+            getSiblings: (id) => this.getSiblings(id),
+            getDependencies: (id) => this.getDependencies(id),
+            getDependents: (id) => this.getDependents(id),
+            getTaskProgress: (id) => this.getTaskProgress(id),
+        };
+    }
+    /** Get decision document dependencies */
+    getDecisionDocumentDeps() {
+        return {
+            createDecision: (data) => this.createDecision(data),
+            getEntity: (id) => this.getEntity(id),
+            getAllDecisions: (options) => this.getAllDecisions(options),
+            getAllDocuments: () => this.getAllDocuments(),
+            updateDocument: (id, data) => this.updateDocument(id, data),
+            toEntityFull: (entity) => this.toEntityFull(entity),
+            getCurrentTimestamp: () => this.getCurrentTimestamp(),
+            generateId: async (type) => await this.generateId(type),
+            getDecisionsAffectingDocument: (id) => this.getDecisionsAffectingDocument(id),
+            searchContent: (id, pattern) => this.searchContent(id, pattern),
+            addToCanvas: async (entity, canvasPath) => {
+                const nodeId = await this.canvasManager.addNode(entity.vault_path, canvasPath, undefined, this.canvasManager.getDimensionsForType(entity.type));
+                return nodeId !== null;
+            },
+        };
+    }
+    /** Get feature coverage dependencies */
+    getFeatureCoverageDeps() {
+        return {
+            getAllFeatures: (options) => this.getAllFeatures(options),
+            getEntity: (id) => this.getEntity(id),
+            getAllDocuments: (options) => this.getAllDocuments(options),
+        };
+    }
+}
+// =============================================================================
+// Singleton Runtime Instance
+// =============================================================================
+let runtimeInstance = null;
+/** Get or create the V2 runtime instance */
+export async function getV2Runtime(config) {
+    if (!runtimeInstance) {
+        runtimeInstance = new V2Runtime(config);
+        await runtimeInstance.initialize();
+    }
+    return runtimeInstance;
+}
+/** Reset the runtime (for testing) */
+export function resetV2Runtime() {
+    runtimeInstance = null;
+}
+//# sourceMappingURL=v2-runtime.js.map