opentasks 0.0.1 → 0.0.2

package/dist/daemon/registry.js

@@ -0,0 +1,189 @@
+/**
+ * Global Daemon Registry
+ *
+ * Manages the global registry of all running OpenTasks daemons.
+ * Located at ~/.opentasks/registry.json
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import lockfile from 'proper-lockfile';
+import { DaemonError } from './types.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const REGISTRY_VERSION = '1.0.0';
+/**
+ * Get the default global registry path
+ */
+export function getGlobalRegistryPath() {
+    return path.join(os.homedir(), '.opentasks', 'registry.json');
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Check if a process is alive
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create empty registry
+ */
+function createEmptyRegistry() {
+    return {
+        version: REGISTRY_VERSION,
+        daemons: [],
+    };
+}
+// ============================================================================
+// Implementation
+// ============================================================================
+/**
+ * Create a registry manager
+ *
+ * @param registryPath - Path to registry.json file (defaults to ~/.opentasks/registry.json)
+ */
+export function createRegistryManager(registryPath = getGlobalRegistryPath()) {
+    const registryDir = path.dirname(registryPath);
+    /**
+     * Ensure registry directory and file exist
+     */
+    async function ensureRegistry() {
+        // Create directory if missing
+        await fs.mkdir(registryDir, { recursive: true });
+        // Create registry file if missing
+        try {
+            await fs.access(registryPath);
+        }
+        catch {
+            await writeRegistry(createEmptyRegistry());
+        }
+    }
+    /**
+     * Read the registry file
+     */
+    async function readRegistry() {
+        try {
+            const contents = await fs.readFile(registryPath, 'utf8');
+            return JSON.parse(contents);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return createEmptyRegistry();
+            }
+            throw new DaemonError('REGISTRY_ERROR', 'Failed to read registry', error);
+        }
+    }
+    /**
+     * Write the registry file atomically
+     */
+    async function writeRegistry(registry) {
+        const tempPath = `${registryPath}.tmp.${process.pid}`;
+        try {
+            await fs.writeFile(tempPath, JSON.stringify(registry, null, 2), 'utf8');
+            await fs.rename(tempPath, registryPath);
+        }
+        catch (error) {
+            // Clean up temp file on error
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            throw new DaemonError('REGISTRY_ERROR', 'Failed to write registry', error);
+        }
+    }
+    /**
+     * Execute an operation with file locking
+     */
+    async function withLock(operation) {
+        await ensureRegistry();
+        let release = null;
+        try {
+            release = await lockfile.lock(registryPath, {
+                stale: 10000,
+                retries: {
+                    retries: 5,
+                    minTimeout: 100,
+                    maxTimeout: 1000,
+                },
+            });
+            return await operation();
+        }
+        catch (error) {
+            if (error.message?.includes('ELOCKED')) {
+                throw new DaemonError('REGISTRY_ERROR', 'Registry is locked by another process', error);
+            }
+            throw error;
+        }
+        finally {
+            if (release) {
+                try {
+                    await release();
+                }
+                catch {
+                    // Ignore release errors
+                }
+            }
+        }
+    }
+    return {
+        registryPath,
+        async register(entry) {
+            await withLock(async () => {
+                const registry = await readRegistry();
+                // Remove any existing entry for this location
+                registry.daemons = registry.daemons.filter((d) => d.locationPath !== entry.locationPath);
+                // Add new entry
+                registry.daemons.push(entry);
+                await writeRegistry(registry);
+            });
+        },
+        async unregister(locationPath) {
+            await withLock(async () => {
+                const registry = await readRegistry();
+                registry.daemons = registry.daemons.filter((d) => d.locationPath !== locationPath);
+                await writeRegistry(registry);
+            });
+        },
+        async find(locationPath) {
+            const registry = await readRegistry();
+            const entry = registry.daemons.find((d) => d.locationPath === locationPath);
+            if (!entry) {
+                return null;
+            }
+            // Verify daemon is still alive
+            if (!isProcessAlive(entry.pid)) {
+                return null;
+            }
+            return entry;
+        },
+        async list() {
+            const registry = await readRegistry();
+            return registry.daemons;
+        },
+        async cleanup() {
+            return await withLock(async () => {
+                const registry = await readRegistry();
+                const originalCount = registry.daemons.length;
+                // Filter out dead processes
+                registry.daemons = registry.daemons.filter((d) => isProcessAlive(d.pid));
+                const removedCount = originalCount - registry.daemons.length;
+                if (removedCount > 0) {
+                    await writeRegistry(registry);
+                }
+                return removedCount;
+            });
+        },
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/daemon/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/daemon/registry.ts"],"names":[],"mappings":"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"}

package/dist/daemon/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Daemon Module Types
+ *
+ * Shared types for daemon lifecycle, IPC, and coordination.
+ */
+/**
+ * Contents of .opentasks/daemon.lock
+ */
+export interface DaemonLock {
+    /** Process ID of daemon */
+    pid: number;
+    /** Parent process ID (for orphan detection) */
+    parentPid: number;
+    /** OpenTasks version */
+    version: string;
+    /** ISO timestamp when daemon started */
+    startedAt: string;
+    /** Path to Unix socket for IPC */
+    socketPath: string;
+    /** Path to SQLite database */
+    databasePath: string;
+}
+/**
+ * Metadata provided when acquiring lock (PID and timestamp added automatically)
+ */
+export type LockMetadata = Omit<DaemonLock, 'pid' | 'parentPid' | 'startedAt'>;
+/**
+ * Global registry file format (~/.opentasks/registry.json)
+ */
+export interface DaemonRegistry {
+    /** Registry format version */
+    version: string;
+    /** All registered daemons */
+    daemons: DaemonEntry[];
+}
+/**
+ * Entry for a registered daemon
+ */
+export interface DaemonEntry {
+    /** Absolute path to .opentasks/ directory */
+    locationPath: string;
+    /** Socket path for IPC */
+    socketPath: string;
+    /** Process ID */
+    pid: number;
+    /** OpenTasks version */
+    version: string;
+    /** When daemon started (ISO timestamp) */
+    startedAt: string;
+    /** Last activity timestamp (ISO) */
+    lastActivity: string;
+}
+/**
+ * Daemon runtime state
+ */
+export type DaemonState = 'starting' | 'running' | 'stopping' | 'stopped';
+/**
+ * Daemon status information
+ */
+export interface DaemonStatus {
+    /** Current state */
+    state: DaemonState;
+    /** When daemon started (ISO timestamp), null if not started */
+    startedAt: string | null;
+    /** Process ID */
+    pid: number;
+    /** Socket path for IPC */
+    socketPath: string;
+    /** Whether there are pending changes to flush */
+    pendingFlush: boolean;
+    /** Number of active IPC connections */
+    connectionCount: number;
+    /** Number of managed locations (multi-location mode) */
+    locationCount?: number;
+}
+/**
+ * Information about a managed location
+ */
+export interface LocationInfo {
+    /** Location hash */
+    hash: string;
+    /** Absolute path to .opentasks/ directory */
+    opentasksPath: string;
+    /** Whether this is the primary (default) location */
+    primary: boolean;
+    /** Whether the location is healthy */
+    healthy: boolean;
+}
+/**
+ * Error codes for daemon operations
+ */
+export type DaemonErrorCode = 'LOCK_HELD' | 'LOCK_NOT_HELD' | 'DAEMON_NOT_RUNNING' | 'DAEMON_ALREADY_RUNNING' | 'REGISTRY_ERROR' | 'IPC_ERROR' | 'SHUTDOWN_TIMEOUT' | 'LOCATION_NOT_FOUND' | 'LOCATION_INIT_FAILED';
+/**
+ * Daemon-specific error
+ */
+export declare class DaemonError extends Error {
+    readonly code: DaemonErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(code: DaemonErrorCode, message: string, cause?: unknown | undefined);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/daemon/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/daemon/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAC;IAEZ,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAElB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAEhB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAElB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IAEnB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,WAAW,GAAG,WAAW,CAAC,CAAC;AAM/E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAEhB,6BAA6B;IAC7B,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IAErB,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IAEnB,iBAAiB;IACjB,GAAG,EAAE,MAAM,CAAC;IAEZ,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAEhB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAElB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;CACtB;AAMD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,KAAK,EAAE,WAAW,CAAC;IAEnB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB,iBAAiB;IACjB,GAAG,EAAE,MAAM,CAAC;IAEZ,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IAEnB,iDAAiD;IACjD,YAAY,EAAE,OAAO,CAAC;IAEtB,uCAAuC;IACvC,eAAe,EAAE,MAAM,CAAC;IAExB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IAEb,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IAEtB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IAEjB,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,WAAW,GACX,eAAe,GACf,oBAAoB,GACpB,wBAAwB,GACxB,gBAAgB,GAChB,WAAW,GACX,kBAAkB,GAClB,oBAAoB,GACpB,sBAAsB,CAAC;AAE3B;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAElB,IAAI,EAAE,eAAe;aAErB,KAAK,CAAC,EAAE,OAAO;gBAFf,IAAI,EAAE,eAAe,EACrC,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,OAAO,YAAA;CAKlC"}

package/dist/daemon/types.js

@@ -0,0 +1,19 @@
+/**
+ * Daemon Module Types
+ *
+ * Shared types for daemon lifecycle, IPC, and coordination.
+ */
+/**
+ * Daemon-specific error
+ */
+export class DaemonError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'DaemonError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/daemon/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/daemon/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkJH;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAElB;IAEA;IAHlB,YACkB,IAAqB,EACrC,OAAe,EACC,KAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAiB;QAErB,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/daemon/watcher.d.ts

@@ -0,0 +1,62 @@
+/**
+ * File Watcher
+ *
+ * Watches for external changes to OpenTasks files.
+ * Notifies handlers when files are modified externally.
+ */
+/**
+ * Type of file change detected
+ */
+export type ChangeType = 'add' | 'change' | 'unlink';
+/**
+ * File category for change handling
+ */
+export type FileCategory = 'graph' | 'context' | 'task' | 'config' | 'unknown';
+/**
+ * Change event emitted by watcher
+ */
+export interface FileChangeEvent {
+    /** Type of change */
+    type: ChangeType;
+    /** Absolute path to file */
+    path: string;
+    /** Category of file */
+    category: FileCategory;
+}
+/**
+ * Handler called when file changes are detected
+ */
+export type ChangeHandler = (event: FileChangeEvent) => void;
+/**
+ * File watcher configuration
+ */
+export interface WatcherConfig {
+    /** Path to .opentasks/ directory */
+    locationPath: string;
+    /** Debounce delay in milliseconds (default: 100) */
+    debounceMs?: number;
+    /** Whether to watch markdown files (default: true) */
+    watchMarkdown?: boolean;
+}
+/**
+ * File watcher interface
+ */
+export interface FileWatcher {
+    /** Start watching for changes */
+    start(): Promise<void>;
+    /** Stop watching */
+    stop(): Promise<void>;
+    /** Pause change detection (during internal writes) */
+    pause(): void;
+    /** Resume change detection */
+    resume(): void;
+    /** Register change handler */
+    onchange(handler: ChangeHandler): void;
+    /** Check if currently paused */
+    readonly paused: boolean;
+}
+/**
+ * Create a file watcher for a .opentasks/ location
+ */
+export declare function createFileWatcher(config: WatcherConfig): FileWatcher;
+//# sourceMappingURL=watcher.d.ts.map

package/dist/daemon/watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../src/daemon/watcher.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,IAAI,EAAE,UAAU,CAAC;IAEjB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IAEb,uBAAuB;IACvB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IAErB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,sDAAsD;IACtD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,oBAAoB;IACpB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB,sDAAsD;IACtD,KAAK,IAAI,IAAI,CAAC;IAEd,8BAA8B;IAC9B,MAAM,IAAI,IAAI,CAAC;IAEf,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAEvC,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAqCD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,WAAW,CAiIpE"}

package/dist/daemon/watcher.js

@@ -0,0 +1,142 @@
+/**
+ * File Watcher
+ *
+ * Watches for external changes to OpenTasks files.
+ * Notifies handlers when files are modified externally.
+ */
+import * as path from 'node:path';
+import chokidar from 'chokidar';
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_DEBOUNCE_MS = 100;
+// ============================================================================
+// Implementation
+// ============================================================================
+/**
+ * Determine file category from path
+ */
+function categorizeFile(filePath, locationPath) {
+    const relative = path.relative(locationPath, filePath);
+    if (relative === 'graph.jsonl') {
+        return 'graph';
+    }
+    if (relative === 'config.json') {
+        return 'config';
+    }
+    if (relative.startsWith('context/') && relative.endsWith('.md')) {
+        return 'context';
+    }
+    if (relative.startsWith('tasks/') && relative.endsWith('.md')) {
+        return 'task';
+    }
+    return 'unknown';
+}
+/**
+ * Create a file watcher for a .opentasks/ location
+ */
+export function createFileWatcher(config) {
+    const { locationPath, debounceMs = DEFAULT_DEBOUNCE_MS, watchMarkdown = true } = config;
+    let watcher = null;
+    let isPaused = false;
+    const handlers = [];
+    // Debounce map: path -> timeout
+    const pendingChanges = new Map();
+    /**
+     * Emit a change event to all handlers
+     */
+    function emitChange(event) {
+        if (isPaused)
+            return;
+        for (const handler of handlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Ignore handler errors
+            }
+        }
+    }
+    /**
+     * Handle a file change (with debouncing)
+     */
+    function handleChange(type, filePath) {
+        const category = categorizeFile(filePath, locationPath);
+        // Ignore unknown files
+        if (category === 'unknown')
+            return;
+        // Skip markdown if not watching
+        if (!watchMarkdown && (category === 'context' || category === 'task')) {
+            return;
+        }
+        // Cancel existing pending change for this path
+        const existing = pendingChanges.get(filePath);
+        if (existing) {
+            clearTimeout(existing.timeout);
+        }
+        // Schedule debounced emit
+        const timeout = setTimeout(() => {
+            pendingChanges.delete(filePath);
+            emitChange({ type, path: filePath, category });
+        }, debounceMs);
+        pendingChanges.set(filePath, { timeout, type });
+    }
+    return {
+        get paused() {
+            return isPaused;
+        },
+        async start() {
+            if (watcher) {
+                return;
+            }
+            // Build watch paths
+            const watchPaths = [
+                path.join(locationPath, 'graph.jsonl'),
+                path.join(locationPath, 'config.json'),
+            ];
+            if (watchMarkdown) {
+                watchPaths.push(path.join(locationPath, 'context'), path.join(locationPath, 'tasks'));
+            }
+            return new Promise((resolve, reject) => {
+                watcher = chokidar.watch(watchPaths, {
+                    ignoreInitial: true,
+                    persistent: true,
+                    awaitWriteFinish: {
+                        stabilityThreshold: 50,
+                        pollInterval: 10,
+                    },
+                });
+                watcher.on('add', (filePath) => handleChange('add', filePath));
+                watcher.on('change', (filePath) => handleChange('change', filePath));
+                watcher.on('unlink', (filePath) => handleChange('unlink', filePath));
+                watcher.on('ready', () => {
+                    resolve();
+                });
+                watcher.on('error', (error) => {
+                    reject(error);
+                });
+            });
+        },
+        async stop() {
+            // Clear all pending changes
+            for (const { timeout } of pendingChanges.values()) {
+                clearTimeout(timeout);
+            }
+            pendingChanges.clear();
+            if (watcher) {
+                await watcher.close();
+                watcher = null;
+            }
+        },
+        pause() {
+            isPaused = true;
+        },
+        resume() {
+            isPaused = false;
+        },
+        onchange(handler) {
+            handlers.push(handler);
+        },
+    };
+}
+//# sourceMappingURL=watcher.js.map

package/dist/daemon/watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../src/daemon/watcher.ts"],"names":[],"mappings":"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"}

package/dist/graph/EdgeTypeRegistry.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Edge Type Registry for OpenTasks
+ *
+ * Makes relationship types extensible without code changes.
+ * Providers can contribute new edge types at runtime.
+ */
+/**
+ * Definition for an edge type
+ */
+export interface EdgeTypeDefinition {
+    /** Edge type name (e.g., 'blocks', 'implements') */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Inverse relationship name (e.g., 'blocks' ↔ 'blocked-by') */
+    inverseOf?: string;
+    /** Does this edge type affect ready status? */
+    affectsReady: boolean;
+    /** Edge direction semantics */
+    direction: 'directed' | 'undirected';
+    /** Which providers support this edge type */
+    providers: string[];
+}
+/**
+ * Provider's support level for an edge type
+ */
+export interface EdgeTypeSupport {
+    /** Edge type name */
+    type: string;
+    /** Can query existing edges of this type */
+    canQuery: boolean;
+    /** Can create new edges of this type */
+    canCreate: boolean;
+    /** Can delete edges of this type */
+    canDelete: boolean;
+}
+/**
+ * Built-in edge types
+ */
+export declare const BUILTIN_EDGE_TYPES: EdgeTypeDefinition[];
+/**
+ * Result of looking up an edge type
+ */
+export interface EdgeTypeLookupResult {
+    /** The edge type definition */
+    definition: EdgeTypeDefinition;
+    /** Whether this is the canonical form (not inverse) */
+    isCanonical: boolean;
+    /** The canonical edge type name */
+    canonicalType: string;
+}
+/**
+ * Edge Type Registry
+ *
+ * Manages registered edge types and provides lookup functionality.
+ * Supports inverse relationships (e.g., blocks ↔ blocked-by).
+ */
+export declare class EdgeTypeRegistry {
+    private types;
+    private inverses;
+    private registrationOrder;
+    constructor();
+    /**
+     * Register a new edge type
+     *
+     * @param definition - The edge type definition
+     * @throws Error if type already registered with different definition
+     */
+    register(definition: EdgeTypeDefinition): void;
+    /**
+     * Look up an edge type by name
+     *
+     * @param name - The edge type name
+     * @returns The lookup result or null if not found
+     */
+    lookup(name: string): EdgeTypeLookupResult | null;
+    /**
+     * Get the inverse of an edge type
+     *
+     * @param name - The edge type name
+     * @returns The inverse type name or null if none
+     */
+    getInverse(name: string): string | null;
+    /**
+     * Check if an edge type affects ready status
+     *
+     * @param name - The edge type name
+     * @returns True if this edge type affects ready status
+     */
+    affectsReady(name: string): boolean;
+    /**
+     * Get all registered edge types
+     *
+     * @returns Array of all edge type definitions
+     */
+    getAll(): EdgeTypeDefinition[];
+    /**
+     * Get edge types that affect ready status
+     *
+     * @returns Array of edge type names that affect ready
+     */
+    getReadyAffectingTypes(): string[];
+    /**
+     * Get edge types supported by a provider
+     *
+     * @param provider - The provider name
+     * @returns Array of edge type definitions
+     */
+    getTypesForProvider(provider: string): EdgeTypeDefinition[];
+    /**
+     * Check if a type is registered
+     *
+     * @param name - The edge type name
+     * @returns True if the type is registered
+     */
+    has(name: string): boolean;
+}
+/**
+ * Get the global edge type registry instance
+ *
+ * @returns The singleton EdgeTypeRegistry
+ */
+export declare function getEdgeTypeRegistry(): EdgeTypeRegistry;
+/**
+ * Create a new edge type registry (for testing)
+ *
+ * @returns A fresh EdgeTypeRegistry instance
+ */
+export declare function createEdgeTypeRegistry(): EdgeTypeRegistry;
+/**
+ * Reset the global registry (for testing)
+ */
+export declare function resetEdgeTypeRegistry(): void;
+//# sourceMappingURL=EdgeTypeRegistry.d.ts.map