@feltdb/core 0.2.0

package/dist/db.js

@@ -0,0 +1,700 @@
+/**
+ * FeltDB State-First Database API
+ *
+ * High-level, application-facing API that treats FeltDB as application state.
+ * Persistence, indexing, and reactivity are completely transparent.
+ */
+import { Collection, Relationship } from './collection.js';
+import { createAgentRef } from './agent.js';
+import { AgentRegistry } from './agent-registry.js';
+import { AgentRuntime } from './agent-runtime.js';
+import { MemoryJsDb } from './memory-db.js';
+import { HttpJsDb } from './http-db.js';
+import { IndexedDbJsDb } from './indexeddb-db.js';
+import { emptyFlowSpec, planFlowSpecMigration, validateFlowSpec } from './flowspec.js';
+export function createFeltDB(options) {
+    if (!options?.namespace?.trim()) {
+        throw new Error('createFeltDB requires a non-empty namespace');
+    }
+    const runtime = options.server ? new HttpJsDb(options.server)
+        : 'browser' in options && options.browser ? new IndexedDbJsDb(options.namespace)
+            : new MemoryJsDb(options.namespace);
+    return new StateFirstDB(runtime);
+}
+/**
+ * State-first database interface.
+ * Applications use this to treat FeltDB collections as live application state.
+ */
+export class StateFirstDB {
+    constructor(jsDb) {
+        this.collections = new Map();
+        this.capabilityWorkers = new Map();
+        this.jsDb = jsDb;
+        this.runtimeInfo = this.detectRuntime();
+        this.agentRegistry = new AgentRegistry();
+        const agentConfig = {
+            persistent: this.runtimeInfo.persistent,
+            executionTimeoutMs: 30000,
+            supportsReactiveTriggers: true,
+            defaultRetryPolicy: {
+                maxAttempts: 3,
+                backoffMs: 1000,
+            },
+        };
+        this.agentRuntime = new AgentRuntime(this.agentRegistry, agentConfig);
+    }
+    /**
+     * Detect runtime environment and storage characteristics
+     */
+    detectRuntime() {
+        const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';
+        const isNode = typeof globalThis !== 'undefined' && 'versions' in globalThis && 'node' in globalThis.versions;
+        const isMemory = this.jsDb instanceof MemoryJsDb;
+        const isRemote = this.jsDb instanceof HttpJsDb;
+        const isIndexedDb = this.jsDb instanceof IndexedDbJsDb;
+        // Detect storage backend
+        let storage = 'memory';
+        let persistent = false;
+        if (isRemote) {
+            storage = 'remote';
+            persistent = true;
+        }
+        else if (isMemory) {
+            storage = 'memory';
+        }
+        else if (isIndexedDb) {
+            storage = 'indexeddb';
+            persistent = true;
+        }
+        else if (isNode) {
+            storage = 'file';
+            persistent = true;
+        }
+        return {
+            runtime: isRemote ? 'remote' : isIndexedDb || isBrowser ? 'browser' : isNode ? 'node' : 'wasm',
+            storage,
+            persistent,
+            reactive: true, // FeltDB is always reactive
+            durable: persistent,
+            version: '0.1.0',
+            supportsCheckpointing: persistent,
+            supportsLifecycle: isBrowser || isIndexedDb,
+        };
+    }
+    /**
+     * Get runtime information about this FeltDB instance.
+     *
+     * Useful for testing and debugging without contaminating the normal API.
+     *
+     * @example
+     * const runtime = db.runtime();
+     * console.log(`Using ${runtime.storage} storage in ${runtime.runtime}`);
+     */
+    runtime() {
+        return { ...this.runtimeInfo };
+    }
+    /**
+     * Get or create a collection.
+     *
+     * Collections are live application state - they automatically update
+     * whenever underlying data changes. No manual refresh() or invalidate() needed.
+     *
+     * @example
+     * const tasks = db.collection("tasks");
+     * const task = await tasks.get(123);
+     * const allActive = await tasks.where(t => t.status === "active").all();
+     */
+    collection(name) {
+        if (!this.collections.has(name)) {
+            this.collections.set(name, new Collection(this.jsDb, name));
+        }
+        return this.collections.get(name);
+    }
+    /** Resolve local state, causally acquiring it from configured peers when absent. */
+    async acquire(collection, id) {
+        if (this.jsDb instanceof HttpJsDb)
+            return this.jsDb.acquire(collection, id);
+        return this.collection(collection).get(id);
+    }
+    /** Search canonical collection state locally or through the remote capability surface. */
+    async search(collection, query, limit = 50) {
+        if (this.jsDb instanceof HttpJsDb)
+            return this.jsDb.search(collection, query, limit);
+        const needle = query.toLowerCase();
+        return (await this.collection(collection).all())
+            .filter(value => JSON.stringify(value).toLowerCase().includes(needle)).slice(0, limit);
+    }
+    /** Install a resource-bounded declarative capability program. */
+    async defineCapability(name, steps) {
+        if (!(this.jsDb instanceof HttpJsDb))
+            throw new Error('Distributed capabilities require a server runtime');
+        return this.jsDb.command(`/capabilities/${encodeURIComponent(name)}`, { steps });
+    }
+    /** Attach executable behavior to a capability in an embedded runtime. */
+    registerCapabilityWorker(name, handler) {
+        if (this.jsDb instanceof HttpJsDb)
+            throw new Error('Remote capability workers are installed on the server');
+        this.capabilityWorkers.set(name, handler);
+        return () => this.capabilityWorkers.delete(name);
+    }
+    async executeCapability(name, input) {
+        if (this.jsDb instanceof HttpJsDb)
+            return this.jsDb.command(`/capabilities/${encodeURIComponent(name)}/execute`, input);
+        const worker = this.capabilityWorkers.get(name);
+        if (!worker)
+            throw new Error(`No embedded capability worker registered for ${name}`);
+        const id = `cap-${name}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        const executions = this.collection('_flow_executions');
+        await executions.insert({ id, capability: name, input, status: 'running', owner: this.instanceId(), started_at: Date.now() }, id);
+        try {
+            const output = await worker(input);
+            await executions.update(id, { status: 'completed', output, completed_at: Date.now() });
+            return output;
+        }
+        catch (error) {
+            await executions.update(id, { status: 'failed', error: error instanceof Error ? error.message : String(error), completed_at: Date.now() });
+            throw error;
+        }
+    }
+    /** Joint-consensus membership change. `members` contains every voting node, including this node. */
+    async changeClusterMembership(expectedEpoch, members) {
+        if (!(this.jsDb instanceof HttpJsDb))
+            throw new Error('Cluster membership requires a server runtime');
+        return this.jsDb.command('/cluster/members', { expected_epoch: expectedEpoch, peers: members });
+    }
+    /** Version and deploy one canonical application model into FeltDB primitives. */
+    async deployFlowSpec(spec, expectedVersion, allowDestructive = false) {
+        const diagnostics = validateFlowSpec(spec).filter(value => value.severity === 'error');
+        if (diagnostics.length)
+            throw new Error(diagnostics.map(value => value.message).join('; '));
+        const applications = this.collection('_flow_apps');
+        const current = await applications.get(spec.app);
+        const version = (current?.version ?? 0) + 1;
+        if (expectedVersion !== undefined && (current?.version ?? 0) !== expectedVersion)
+            throw new Error(`FlowSpec version conflict: expected ${expectedVersion}, found ${current?.version ?? 0}`);
+        const migration = planFlowSpecMigration(current?.spec ?? emptyFlowSpec(spec.app), spec);
+        const destructive = migration.filter(operation => operation.safety === 'destructive');
+        if (destructive.length && !allowDestructive)
+            throw new Error(`Destructive migration requires explicit approval: ${destructive.map(operation => operation.target).join(', ')}`);
+        const deployment = { id: spec.app, app: spec.app, version, status: 'deploying', spec, migration, deployed_at: Date.now() };
+        if (current)
+            await applications.update(spec.app, deployment);
+        else
+            await applications.insert(deployment, spec.app);
+        const modelId = (kind, name) => `${spec.app}-${kind}-${name}`.replace(/[^A-Za-z0-9_-]/g, '_');
+        const reconcile = async (collectionName, kind, currentValues, nextValues) => {
+            const collection = this.collection(collectionName);
+            const nextNames = new Set(nextValues.map(value => value.name ?? value.event ?? 'unnamed'));
+            for (const value of currentValues) {
+                const name = value.name ?? value.event ?? 'unnamed';
+                if (!nextNames.has(name))
+                    await collection.delete(modelId(kind, name));
+            }
+            for (const value of nextValues) {
+                const name = value.name ?? value.event ?? 'unnamed';
+                const id = modelId(kind, name);
+                const record = { id, app: spec.app, version, ...value };
+                if (await collection.get(id))
+                    await collection.update(id, record);
+                else
+                    await collection.insert(record, id);
+            }
+        };
+        const previous = current?.spec ?? emptyFlowSpec(spec.app);
+        await reconcile('_flow_collection_models', 'collection', previous.collections, spec.collections);
+        await reconcile('_flow_capability_models', 'capability', previous.capabilities, spec.capabilities);
+        await reconcile('_flow_trigger_models', 'trigger', previous.triggers, spec.triggers);
+        await reconcile('_flow_policy_models', 'policy', previous.policies, spec.policies);
+        await reconcile('_flow_schedule_models', 'schedule', previous.schedules, spec.schedules);
+        if (this.jsDb instanceof HttpJsDb) {
+            for (const workflow of previous.workflows)
+                if (!spec.workflows.some(value => value.name === workflow.name))
+                    await this.collection('_flow_workflows').delete(modelId('workflow', workflow.name));
+            for (const agent of previous.agents)
+                if (!spec.agents.some(value => value.name === agent.name))
+                    await this.collection('_flow_agents').delete(modelId('agent', agent.name));
+            for (const workflow of spec.workflows)
+                await this.defineWorkflow(modelId('workflow', workflow.name), workflow.steps.map(step => step.name));
+            for (const agent of spec.agents) {
+                const capabilities = agent.statements.filter(line => line.startsWith('capability ')).map(line => line.slice('capability '.length).trim());
+                await this.defineStateAgent(modelId('agent', agent.name), capabilities, { flowspec_app: spec.app, flowspec_version: version });
+            }
+        }
+        else {
+            // Embedded runtimes materialize the same application model as ordinary
+            // durable state. Network workers can activate it later without a second
+            // schema or a Studio-only representation.
+            await reconcile('_flow_workflows', 'workflow', previous.workflows, spec.workflows);
+            await reconcile('_flow_agents', 'agent', previous.agents, spec.agents);
+        }
+        const active = { ...deployment, status: 'active' };
+        await applications.update(spec.app, active);
+        await this.collection('_flow_app_versions').insert({ id: `${spec.app}-${version}`, app: spec.app, version, spec, migration, deployed_at: active.deployed_at }, `${spec.app}-${version}`);
+        return { app: spec.app, version, status: 'active' };
+    }
+    /** Read the runtime's durable local mutation log for inspection and audit. */
+    async auditEvents() {
+        if (!this.jsDb.audit_events)
+            return [];
+        return await this.jsDb.audit_events();
+    }
+    /** Export durable embedded operations for transport over any application channel. */
+    async exportOperations(sinceSequence = 0) {
+        if (!this.jsDb.export_operations)
+            throw new Error('This runtime uses server-managed replication');
+        return await this.jsDb.export_operations(sinceSequence);
+    }
+    /** Merge operations from another embedded replica and notify live collections. */
+    async applyOperations(operations) {
+        if (!this.jsDb.apply_remote_operations)
+            throw new Error('This runtime uses server-managed replication');
+        return await this.jsDb.apply_remote_operations(operations);
+    }
+    /** Exchange durable operations with another embedded replica in both directions. */
+    async synchronizeWith(peer) {
+        const localOperations = await this.exportOperations();
+        const peerOperations = await peer.exportOperations();
+        await this.addSyncPeer(peer.instanceId());
+        await peer.addSyncPeer(this.instanceId());
+        const remoteResult = await peer.applyOperations(localOperations);
+        const localResult = await this.applyOperations(peerOperations);
+        return { sent: localOperations.length, received: peerOperations.length, applied: localResult.applied + remoteResult.applied, ignored: localResult.ignored + remoteResult.ignored };
+    }
+    /** Route a capability to the first available embedded provider and audit failover attempts. */
+    async executeCapabilityWithFailover(name, input, providers = []) {
+        const routes = this.collection('_flow_capability_routes');
+        const routeId = `route-${name}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        const candidates = [this, ...providers];
+        const failures = [];
+        await routes.insert({ id: routeId, capability: name, status: 'routing', input, candidates: candidates.map(value => value.instanceId()), started_at: Date.now() }, routeId);
+        for (const provider of candidates) {
+            try {
+                const output = await provider.executeCapability(name, input);
+                await routes.update(routeId, { status: 'completed', provider: provider.instanceId(), attempts: failures.length + 1, failures, completed_at: Date.now() });
+                return { output, provider: provider.instanceId(), attempts: failures.length + 1 };
+            }
+            catch (error) {
+                failures.push({ provider: provider.instanceId(), error: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        await routes.update(routeId, { status: 'failed', attempts: failures.length, failures, completed_at: Date.now() });
+        throw new Error(`No provider could execute capability ${name}: ${failures.map(value => value.error).join('; ')}`);
+    }
+    /** Inspect the causal operation that currently materializes a remote record. */
+    async recordProvenance(collection, id) {
+        if (!(this.jsDb instanceof HttpJsDb))
+            throw new Error('Causal provenance requires a server runtime');
+        return this.jsDb.provenance(collection, id);
+    }
+    /** Persist immutable content by hash; repeated bytes deduplicate automatically. */
+    async storeContent(content) {
+        if (!(this.jsDb instanceof HttpJsDb))
+            throw new Error('Durable content storage requires a server runtime');
+        return this.jsDb.storeContent(content);
+    }
+    /** Resolve verified immutable content locally or from configured peers. */
+    async acquireContent(hash) {
+        if (!(this.jsDb instanceof HttpJsDb))
+            throw new Error('Network content acquisition requires a server runtime');
+        return this.jsDb.acquireContent(hash);
+    }
+    /** Define a durable workflow whose lifecycle is ordinary replicated state. */
+    async defineWorkflow(name, steps) {
+        if (!(this.jsDb instanceof HttpJsDb))
+            throw new Error('Durable workflow coordination requires a server runtime');
+        return this.jsDb.command(`/workflows/${encodeURIComponent(name)}`, { steps });
+    }
+    async startWorkflow(name, input = null) {
+        if (!(this.jsDb instanceof HttpJsDb))
+            throw new Error('Durable workflow coordination requires a server runtime');
+        return this.jsDb.command(`/workflows/${encodeURIComponent(name)}/runs`, { input });
+    }
+    async claimWorkflowStep(runId, step, worker, leaseMs = 30000) {
+        if (!(this.jsDb instanceof HttpJsDb))
+            throw new Error('Durable workflow coordination requires a server runtime');
+        return this.jsDb.command(`/workflow-runs/${encodeURIComponent(runId)}/steps/${encodeURIComponent(step)}/claim`, { worker, lease_ms: leaseMs });
+    }
+    async completeWorkflowStep(runId, step, claimId, result = null) {
+        if (!(this.jsDb instanceof HttpJsDb))
+            throw new Error('Durable workflow coordination requires a server runtime');
+        return this.jsDb.command(`/workflow-runs/${encodeURIComponent(runId)}/steps/${encodeURIComponent(step)}/complete`, { claim_id: claimId, result });
+    }
+    /** Define and start state-first agents; workers observe and advance these records externally. */
+    async defineStateAgent(name, capabilities = [], constraints = null) {
+        if (!(this.jsDb instanceof HttpJsDb))
+            throw new Error('Durable agent coordination requires a server runtime');
+        return this.jsDb.command(`/agents/${encodeURIComponent(name)}`, { capabilities, constraints });
+    }
+    async startStateAgent(name, goal, input = null) {
+        if (!(this.jsDb instanceof HttpJsDb))
+            throw new Error('Durable agent coordination requires a server runtime');
+        return this.jsDb.command(`/agents/${encodeURIComponent(name)}/runs`, { goal, input });
+    }
+    /**
+     * Define an agent with declarative configuration.
+     *
+     * Agents are durable, addressable participants in the FeltDB fabric.
+     *
+     * @example
+     * const researcher = db.defineAgent({
+     *   name: "researcher",
+     *   version: 1,
+     *   capabilities: ["vector-search", "document-read", "report-write"],
+     *   constraints: { maxLatency: 5000 }
+     * });
+     */
+    defineAgent(definition) {
+        const agentRef = createAgentRef(definition.name, definition.version);
+        this.agentRegistry.register(agentRef, definition);
+        return agentRef;
+    }
+    /**
+     * Get an agent by name.
+     *
+     * Returns the latest version of the agent if it exists.
+     *
+     * @example
+     * const researcher = db.agent("researcher");
+     */
+    agent(name) {
+        const entry = this.agentRegistry.getByName(name);
+        return entry?.agentRef;
+    }
+    /**
+     * Get the agent registry
+     */
+    getAgentRegistry() {
+        return this.agentRegistry;
+    }
+    /**
+     * Get the agent runtime
+     */
+    getAgentRuntime() {
+        return this.agentRuntime;
+    }
+    /**
+     * Create an agent execution
+     */
+    async createAgentExecution(agentRef, goal, inputs) {
+        const execution = await this.agentRuntime.createExecution(this, agentRef, goal, inputs);
+        await this.collection('_flow_agent_executions').insert(this.agentExecutionRecord(execution), execution.executionId);
+        return execution;
+    }
+    agentExecutionRecord(execution) {
+        return { ...execution, id: execution.executionId, agentRef: execution.agentRef.toString() };
+    }
+    /** Claim and durably materialize an embedded agent execution. */
+    async startAgentExecution(execution, peerId = this.instanceId()) {
+        await this.agentRuntime.start(execution, peerId);
+        await this.collection('_flow_agent_executions').update(execution.executionId, this.agentExecutionRecord(execution));
+    }
+    /** Advance an agent lifecycle and expose the transition as ordinary state. */
+    async transitionAgentExecution(execution, status) {
+        await this.agentRuntime.transition(execution, status);
+        await this.collection('_flow_agent_executions').update(execution.executionId, this.agentExecutionRecord(execution));
+    }
+    async completeAgentExecution(execution, resultRef) {
+        await this.agentRuntime.complete(execution, resultRef);
+        await this.collection('_flow_agent_executions').update(execution.executionId, this.agentExecutionRecord(execution));
+    }
+    async failAgentExecution(execution, error) {
+        await this.agentRuntime.fail(execution, error);
+        await this.collection('_flow_agent_executions').update(execution.executionId, this.agentExecutionRecord(execution));
+    }
+    /**
+     * Close the database and clean up resources.
+     */
+    async close() {
+        for (const collection of this.collections.values()) {
+            collection.close();
+        }
+        this.collections.clear();
+        await this.jsDb.close?.();
+    }
+    /**
+     * Get current sync state information.
+     *
+     * @example
+     * const syncState = db.sync();
+     * console.log(`Connected to ${syncState.connected_peers.length} peers`);
+     */
+    sync() {
+        const result = this.jsDb.sync_info();
+        if (!result.success || !result.data) {
+            throw new Error(result.error || 'Failed to get sync info');
+        }
+        return JSON.parse(result.data);
+    }
+    /**
+     * Add a peer for synchronization.
+     *
+     * @example
+     * await db.addSyncPeer('peer-123');
+     */
+    async addSyncPeer(peerId) {
+        const result = this.jsDb.add_sync_peer(peerId);
+        if (!result.success) {
+            throw new Error(result.error || 'Failed to add peer');
+        }
+    }
+    /**
+     * Remove a peer from synchronization.
+     *
+     * @example
+     * await db.removeSyncPeer('peer-123');
+     */
+    async removeSyncPeer(peerId) {
+        const result = this.jsDb.remove_sync_peer(peerId);
+        if (!result.success) {
+            throw new Error(result.error || 'Failed to remove peer');
+        }
+    }
+    /**
+     * Get pending operations for a peer.
+     *
+     * @example
+     * const ops = await db.getPendingForPeer('peer-123', 5);
+     */
+    async getPendingForPeer(peerId, sinceSequence) {
+        const result = this.jsDb.get_pending_for_peer(peerId, sinceSequence);
+        if (!result.success || !result.data) {
+            throw new Error(result.error || 'Failed to get pending operations');
+        }
+        return JSON.parse(result.data);
+    }
+    /**
+     * Acknowledge receipt of operations from a peer.
+     *
+     * @example
+     * await db.acknowledgePeerOperations('peer-123', 10);
+     */
+    async acknowledgePeerOperations(peerId, sequence) {
+        const result = this.jsDb.acknowledge_peer_operations(peerId, sequence);
+        if (!result.success) {
+            throw new Error(result.error || 'Failed to acknowledge operations');
+        }
+    }
+    /**
+     * Get the instance ID for this FeltDB instance.
+     *
+     * @example
+     * const id = db.instanceId();
+     */
+    instanceId() {
+        return this.jsDb.instance_id();
+    }
+    /**
+     * Get the current sequence number for this instance.
+     *
+     * @example
+     * const seq = db.getSequence();
+     */
+    getSequence() {
+        return this.jsDb.get_sequence();
+    }
+    /**
+     * Register a trigger that maps operations to executions
+     *
+     * @example
+     * await db.registerTrigger({
+     *   triggerId: "order-created",
+     *   capability: "process_order",
+     *   eventType: "OrderCreated",
+     *   collection: "orders"
+     * });
+     */
+    async registerTrigger(trigger) {
+        // Placeholder for execution trigger registration
+        // In full implementation, this would call into the Rust backend
+    }
+    /**
+     * Register a cron schedule
+     *
+     * @example
+     * await db.scheduleCron({
+     *   cronId: "daily-reports",
+     *   name: "Daily Reports",
+     *   cronExpr: "0 0 * * *",
+     *   capability: "generate_reports"
+     * });
+     */
+    async scheduleCron(schedule) {
+        // Placeholder for cron scheduling
+        // In full implementation, this would call into the Rust backend
+    }
+    /**
+     * Get pending executions
+     *
+     * @example
+     * const pending = await db.getPendingExecutions();
+     */
+    async getPendingExecutions() {
+        // Placeholder for retrieving pending executions
+        // In full implementation, this would call into the Rust backend
+        return [];
+    }
+    /**
+     * Mark an execution as complete
+     *
+     * @example
+     * await db.completeExecution("exec-1", { success: true });
+     */
+    async completeExecution(executionId, result) {
+        // Placeholder for marking execution as complete
+        // In full implementation, this would call into the Rust backend
+    }
+    /**
+     * Get the causal graph (provenance) for a given flow reference.
+     *
+     * Shows how a record was created, what operations it depended on,
+     * which workflows/capabilities produced it, etc.
+     *
+     * @example
+     * const graph = db.provenance('flow://documents/report-123');
+     * console.log(graph.root); // The record being inspected
+     * console.log(graph.edges); // Relationships showing causality
+     */
+    provenance(flowRef) {
+        // Parse the flow reference
+        const [namespace, ...rest] = flowRef.split('://')[1]?.split('/') || [];
+        const id = rest.join('/');
+        // Create the root node
+        const root = {
+            id: flowRef,
+            type: 'Record',
+            label: id || flowRef,
+            created_ms: Date.now(),
+        };
+        // Return a basic provenance graph
+        // In full implementation, this would reconstruct the causal history
+        // from the operation log and workflow executions
+        return {
+            root,
+            nodes: [root],
+            edges: [],
+        };
+    }
+    /**
+     * Get runtime health and diagnostics information.
+     *
+     * Provides a comprehensive view of system health across all components.
+     * Useful for debugging distributed issues and monitoring system status.
+     *
+     * @example
+     * const health = db.health();
+     * if (health.status === 'unhealthy') {
+     *   for (const issue of health.issues) {
+     *     console.warn(`${issue.component}: ${issue.message}`);
+     *   }
+     * }
+     */
+    health() {
+        const syncState = this.sync();
+        const runtime = this.runtime();
+        // Determine sync health
+        const syncHealthy = syncState.is_connected && syncState.pending_operations === 0;
+        const syncStatus = syncHealthy ? 'healthy' : 'degraded';
+        // Determine overall health
+        const issues = [];
+        if (syncState.pending_operations > 0) {
+            issues.push({
+                severity: 'info',
+                component: 'sync',
+                message: `${syncState.pending_operations} pending operations`,
+            });
+        }
+        if (!syncState.is_connected) {
+            issues.push({
+                severity: 'warning',
+                component: 'sync',
+                message: 'Network disconnected',
+            });
+        }
+        if (syncState.conflicts_detected > 0) {
+            issues.push({
+                severity: 'warning',
+                component: 'sync',
+                message: `${syncState.conflicts_detected} conflicts detected`,
+            });
+        }
+        const hasIssues = issues.length > 0;
+        const overallStatus = hasIssues ? 'degraded' : 'healthy';
+        return {
+            runtime: {
+                status: 'healthy',
+                wasm: runtime.runtime === 'wasm' || runtime.runtime === 'browser',
+                reactive: runtime.reactive,
+            },
+            storage: {
+                status: 'healthy',
+                backend: runtime.storage,
+                persistent: runtime.persistent,
+                durable: runtime.durable,
+            },
+            sync: {
+                status: syncStatus,
+                connected: syncState.is_connected,
+                peers: syncState.connected_peers.length,
+                pendingOperations: syncState.pending_operations,
+            },
+            fabric: {
+                status: 'healthy',
+                references: 0, // Would be populated from Rust backend
+                peers: syncState.connected_peers.length,
+            },
+            capabilities: {
+                status: 'healthy',
+                count: 0, // Would be populated from Rust backend
+                available: 0,
+            },
+            execution: {
+                status: 'healthy',
+                pending: 0, // Would be populated from Rust backend
+                running: 0,
+                failed: 0,
+            },
+            workflow: {
+                status: 'healthy',
+                total: 0, // Would be populated from Rust backend
+                active: 0,
+            },
+            status: overallStatus,
+            issues,
+        };
+    }
+}
+/**
+ * Open a state-first database instance.
+ *
+ * The database automatically handles:
+ * - Persistence (transparent to application)
+ * - Reactive updates (live queries by default)
+ * - Relationship loading
+ * - Differential updates (single record mutations don't re-emit entire collection)
+ *
+ * @example
+ * const db = await open(jsDbInstance);
+ * const users = db.collection("users");
+ * users.subscribe((users) => render(users));
+ *
+ * @param jsDb The underlying JsDb WASM instance
+ * @returns A new StateFirstDB instance
+ */
+export async function open(jsDb) {
+    return new StateFirstDB(jsDb);
+}
+/**
+ * Helper to create a relationship between two collections.
+ *
+ * @example
+ * const projectTasks = new Relationship(
+ *   db.collection("tasks"),
+ *   (task) => task.projectId
+ * );
+ *
+ * const tasks = await projectTasks.load(projectId);
+ */
+export function createRelationship(childCollection, foreignKey) {
+    return new Relationship(null, // We'll handle this differently in the new API
+    null, 'dummy', foreignKey);
+}