@feltdb/core 0.2.0

package/dist/agent.js

@@ -0,0 +1,58 @@
+/**
+ * FeltDB Agent Runtime
+ *
+ * Agents are durable, addressable participants in the FeltDB fabric.
+ * An agent's observations, decisions, actions, and results are all part
+ * of the same causal graph.
+ */
+/**
+ * Lifecycle states for agent execution
+ */
+export var AgentExecutionStatus;
+(function (AgentExecutionStatus) {
+    AgentExecutionStatus["Created"] = "Created";
+    AgentExecutionStatus["Planning"] = "Planning";
+    AgentExecutionStatus["Observing"] = "Observing";
+    AgentExecutionStatus["Deciding"] = "Deciding";
+    AgentExecutionStatus["Acting"] = "Acting";
+    AgentExecutionStatus["Waiting"] = "Waiting";
+    AgentExecutionStatus["Completed"] = "Completed";
+    AgentExecutionStatus["Failed"] = "Failed";
+    AgentExecutionStatus["Cancelled"] = "Cancelled";
+    AgentExecutionStatus["Blocked"] = "Blocked";
+})(AgentExecutionStatus || (AgentExecutionStatus = {}));
+/**
+ * Parse an agent reference from its canonical form
+ * @example parseAgentRef("flow://agent/researcher@1")
+ */
+export function parseAgentRef(ref) {
+    const match = ref.match(/^flow:\/\/agent\/([^@]+)@(\d+)$/);
+    if (!match) {
+        throw new Error(`Invalid agent reference format: ${ref}`);
+    }
+    return {
+        name: match[1],
+        version: parseInt(match[2], 10),
+        toString() {
+            return `flow://agent/${this.name}@${this.version}`;
+        },
+    };
+}
+/**
+ * Create an agent reference
+ */
+export function createAgentRef(name, version) {
+    return {
+        name,
+        version,
+        toString() {
+            return `flow://agent/${this.name}@${this.version}`;
+        },
+    };
+}
+/**
+ * Generate a unique execution ID
+ */
+export function generateExecutionId(agentName) {
+    return `exec-${agentName}-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}

package/dist/capability.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Capability registration and execution
+ *
+ * Capabilities are distributed, pluggable features like search, vector embeddings, etc.
+ */
+export interface Capability {
+    id: string;
+    name: string;
+    execute(...args: any[]): Promise<any>;
+}
+export interface CapabilityDefinition {
+    name: string;
+    handler: (...args: any[]) => Promise<any>;
+}
+export declare class CapabilityRegistry {
+    private capabilities;
+    register(capability: Capability): void;
+    get(id: string): Capability | undefined;
+    execute(capabilityId: string, ...args: any[]): Promise<any>;
+}
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CAC3C;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,YAAY,CAAiC;IAErD,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IAItC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIjC,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC;CAOlE"}

package/dist/capability.js

@@ -0,0 +1,23 @@
+/**
+ * Capability registration and execution
+ *
+ * Capabilities are distributed, pluggable features like search, vector embeddings, etc.
+ */
+export class CapabilityRegistry {
+    constructor() {
+        this.capabilities = new Map();
+    }
+    register(capability) {
+        this.capabilities.set(capability.id, capability);
+    }
+    get(id) {
+        return this.capabilities.get(id);
+    }
+    async execute(capabilityId, ...args) {
+        const capability = this.get(capabilityId);
+        if (!capability) {
+            throw new Error(`Capability not found: ${capabilityId}`);
+        }
+        return capability.execute(...args);
+    }
+}

package/dist/collection.d.ts

@@ -0,0 +1,95 @@
+/**
+ * FeltDB State-First Collections API
+ *
+ * Provides a high-level, state-oriented collection abstraction
+ * that makes the database disappear from the programming model.
+ *
+ * Collections now use reactive dependency graphs instead of polling
+ * for efficient, real-time state propagation.
+ */
+import type { JsDb } from './feltdb.js';
+export type Predicate<T> = (item: T) => boolean;
+export type Subscriber<T> = (items: T[]) => void;
+/**
+ * A live collection that automatically updates when underlying data changes.
+ * Represents application state, not a one-time query result.
+ *
+ * Uses reactive dependency graph instead of polling for efficient updates.
+ */
+export declare class Collection<T> {
+    private db;
+    private name;
+    private collectionId;
+    private predicate;
+    private cache;
+    private subscribers;
+    private parent;
+    private parentId;
+    private isInitialized;
+    private unsubscribeFunctions;
+    private graphUnsubscribe;
+    private runtimeUnsubscribe;
+    constructor(db: JsDb, name: string, predicate?: Predicate<T>, parent?: Collection<T>);
+    /**
+     * Get all records in this collection.
+     * Returns cached results (live-updated).
+     */
+    all(): Promise<T[]>;
+    /** Find records whose fields match the supplied query. */
+    find(query?: Partial<T>): Promise<T[]>;
+    /**
+     * Get a single record by ID.
+     */
+    get(id: string | number): Promise<T | null>;
+    /**
+     * Find records matching a predicate.
+     * Returns a derived collection that automatically updates.
+     */
+    where(predicate: Predicate<T>): Collection<T>;
+    /**
+     * Insert a new record into this collection.
+     */
+    insert(data: Partial<T>, id?: string | number): Promise<string>;
+    /**
+     * Update a record in this collection.
+     */
+    update(id: string | number, changes: Partial<T>): Promise<void>;
+    /**
+     * Delete a record from this collection.
+     */
+    delete(id: string | number): Promise<void>;
+    /**
+     * Count records in this collection.
+     */
+    count(): Promise<number>;
+    /**
+     * Check if a record exists.
+     */
+    exists(id: string | number): Promise<boolean>;
+    /**
+     * Subscribe to changes in this collection using reactive dependency graph.
+     * Returns an unsubscribe function.
+     */
+    subscribe(subscriber: Subscriber<T>, _pollInterval?: number): () => void;
+    /** Release runtime subscriptions owned by this live collection. */
+    close(): void;
+    /**
+     * Refresh data from the database and notify subscribers.
+     */
+    refresh(): Promise<void>;
+}
+/**
+ * Relationship helper for loading related data.
+ */
+export declare class Relationship<Parent, Child> {
+    private parentDb;
+    private childDb;
+    private childCollection;
+    private foreignKey;
+    constructor(parentDb: JsDb, childDb: JsDb, childCollection: string, foreignKey: (child: Child) => string | number);
+    /**
+     * Load related children for a parent item.
+     */
+    load(parentId: string | number): Promise<Child[]>;
+}
+//# sourceMappingURL=collection.d.ts.map

package/dist/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAGxC,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;AAChD,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;AAEjD;;;;;GAKG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,OAAO,CAAC,EAAE,CAAO;IACjB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,oBAAoB,CAA8B;IAC1D,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,kBAAkB,CAA6B;gBAE3C,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IAepF;;;OAGG;IACG,GAAG,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAKzB,0DAA0D;IACpD,IAAI,CAAC,KAAK,GAAE,OAAO,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAQhD;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAajD;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAO7C;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAyBrE;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BrE;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBhD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAK9B;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKnD;;;OAGG;IACH,SAAS,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI;IAwCxE,mEAAmE;IACnE,KAAK,IAAI,IAAI;IASb;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAgC/B;AAED;;GAEG;AACH,qBAAa,YAAY,CAAC,MAAM,EAAE,KAAK;IACrC,OAAO,CAAC,QAAQ,CAAO;IACvB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,UAAU,CAAoC;gBAGpD,QAAQ,EAAE,IAAI,EACd,OAAO,EAAE,IAAI,EACb,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,GAAG,MAAM;IAQ/C;;OAEG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;CAoBxD"}

package/dist/collection.js

@@ -0,0 +1,289 @@
+/**
+ * FeltDB State-First Collections API
+ *
+ * Provides a high-level, state-oriented collection abstraction
+ * that makes the database disappear from the programming model.
+ *
+ * Collections now use reactive dependency graphs instead of polling
+ * for efficient, real-time state propagation.
+ */
+import { getReactiveDependencyGraph } from './reactive-graph.js';
+/**
+ * A live collection that automatically updates when underlying data changes.
+ * Represents application state, not a one-time query result.
+ *
+ * Uses reactive dependency graph instead of polling for efficient updates.
+ */
+export class Collection {
+    constructor(db, name, predicate, parent) {
+        this.predicate = null;
+        this.cache = [];
+        this.subscribers = new Set();
+        this.parent = null;
+        this.parentId = null;
+        this.isInitialized = false;
+        this.unsubscribeFunctions = new Set();
+        this.graphUnsubscribe = null;
+        this.runtimeUnsubscribe = null;
+        this.db = db;
+        this.name = name;
+        this.collectionId = `${name}-${Math.random().toString(36).substr(2, 9)}`;
+        this.predicate = predicate || null;
+        this.parent = parent || null;
+        this.parentId = parent ? parent.collectionId : null;
+        // Register dependency if this is a derived collection
+        if (parent) {
+            const graph = getReactiveDependencyGraph();
+            graph.registerDependency(parent.collectionId, this.collectionId);
+        }
+    }
+    /**
+     * Get all records in this collection.
+     * Returns cached results (live-updated).
+     */
+    async all() {
+        await this.refresh();
+        return [...this.cache];
+    }
+    /** Find records whose fields match the supplied query. */
+    async find(query = {}) {
+        const items = await this.all();
+        const entries = Object.entries(query);
+        return items.filter((item) => entries.every(([field, expected]) => item[field] === expected));
+    }
+    /**
+     * Get a single record by ID.
+     */
+    async get(id) {
+        const key = `${this.name}:${id}`;
+        const result = await this.db.get(key);
+        if (result.success && result.data) {
+            try {
+                return JSON.parse(result.data);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Find records matching a predicate.
+     * Returns a derived collection that automatically updates.
+     */
+    where(predicate) {
+        return new Collection(this.db, this.name, (item) => {
+            const parentMatch = this.predicate ? this.predicate(item) : true;
+            return parentMatch && predicate(item);
+        }, this.parent || this);
+    }
+    /**
+     * Insert a new record into this collection.
+     */
+    async insert(data, id) {
+        const recordId = id ?? `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+        const key = `${this.name}:${recordId}`;
+        const stored = typeof data === 'object' && data !== null
+            ? { ...data, id: recordId }
+            : data;
+        const result = await this.db.insert(key, JSON.stringify(stored));
+        if (!result.success) {
+            throw new Error(`Insert failed: ${result.error}`);
+        }
+        // Emit change through reactive dependency graph
+        const change = {
+            type: 'insert',
+            key,
+            value: stored,
+            timestamp: Date.now(),
+        };
+        const graph = getReactiveDependencyGraph();
+        await graph.emitChange(this.name, change);
+        return String(recordId);
+    }
+    /**
+     * Update a record in this collection.
+     */
+    async update(id, changes) {
+        const current = await this.get(id);
+        if (!current) {
+            throw new Error(`Record ${id} not found`);
+        }
+        const updated = { ...current, ...changes };
+        const key = `${this.name}:${id}`;
+        const result = await (this.db.update
+            ? this.db.update(key, JSON.stringify(updated))
+            : this.db.insert(key, JSON.stringify(updated)));
+        if (!result.success) {
+            throw new Error(`Update failed: ${result.error}`);
+        }
+        // Emit change through reactive dependency graph
+        const change = {
+            type: 'update',
+            key,
+            value: updated,
+            timestamp: Date.now(),
+        };
+        const graph = getReactiveDependencyGraph();
+        await graph.emitChange(this.name, change);
+    }
+    /**
+     * Delete a record from this collection.
+     */
+    async delete(id) {
+        const key = `${this.name}:${id}`;
+        if (!this.db.delete) {
+            throw new Error('Delete is not supported by this FeltDB runtime');
+        }
+        const result = await this.db.delete(key);
+        if (!result.success) {
+            throw new Error(`Delete failed: ${result.error}`);
+        }
+        // Emit delete change through reactive dependency graph
+        const change = {
+            type: 'delete',
+            key,
+            value: null,
+            timestamp: Date.now(),
+        };
+        const graph = getReactiveDependencyGraph();
+        await graph.emitChange(this.name, change);
+    }
+    /**
+     * Count records in this collection.
+     */
+    async count() {
+        const items = await this.all();
+        return items.length;
+    }
+    /**
+     * Check if a record exists.
+     */
+    async exists(id) {
+        const item = await this.get(id);
+        return item !== null;
+    }
+    /**
+     * Subscribe to changes in this collection using reactive dependency graph.
+     * Returns an unsubscribe function.
+     */
+    subscribe(subscriber, _pollInterval) {
+        this.subscribers.add(subscriber);
+        // Initialize cache if needed
+        if (!this.isInitialized) {
+            this.refresh().catch(err => console.error('Failed to initialize collection:', err));
+        }
+        // Subscribe to changes via reactive dependency graph
+        if (!this.graphUnsubscribe) {
+            const notify = async () => {
+                await this.refresh();
+                for (const sub of this.subscribers)
+                    sub([...this.cache]);
+            };
+            const graph = getReactiveDependencyGraph();
+            this.graphUnsubscribe = graph.subscribe(this.name, notify);
+            if (this.db.subscribe_changes) {
+                this.runtimeUnsubscribe = this.db.subscribe_changes(collection => {
+                    if (collection === this.name)
+                        void notify();
+                });
+            }
+        }
+        // Return unsubscribe function
+        return () => {
+            this.subscribers.delete(subscriber);
+            // If no more subscribers, cleanup
+            if (this.subscribers.size === 0) {
+                // Unsubscribe from graph
+                this.graphUnsubscribe?.();
+                this.runtimeUnsubscribe?.();
+                this.graphUnsubscribe = null;
+                this.runtimeUnsubscribe = null;
+                for (const unsub of this.unsubscribeFunctions)
+                    unsub();
+                this.unsubscribeFunctions.clear();
+            }
+        };
+    }
+    /** Release runtime subscriptions owned by this live collection. */
+    close() {
+        this.graphUnsubscribe?.();
+        this.runtimeUnsubscribe?.();
+        this.graphUnsubscribe = null;
+        this.runtimeUnsubscribe = null;
+        this.subscribers.clear();
+        for (const unsubscribe of this.unsubscribeFunctions)
+            unsubscribe();
+        this.unsubscribeFunctions.clear();
+    }
+    /**
+     * Refresh data from the database and notify subscribers.
+     */
+    async refresh() {
+        try {
+            const result = await this.db.query(this.name);
+            if (result.success && result.data) {
+                try {
+                    let items = JSON.parse(result.data);
+                    // Apply predicate if this is a derived collection
+                    if (this.predicate) {
+                        items = items.filter((item) => {
+                            try {
+                                return this.predicate(item);
+                            }
+                            catch {
+                                return false;
+                            }
+                        });
+                    }
+                    // Update cache with all results
+                    this.cache = items;
+                    this.isInitialized = true;
+                }
+                catch (err) {
+                    console.error('Failed to parse query results:', err);
+                }
+            }
+            else if (!result.success) {
+                console.error('Query failed:', result.error);
+            }
+        }
+        catch (err) {
+            console.error('Refresh error:', err);
+        }
+    }
+}
+/**
+ * Relationship helper for loading related data.
+ */
+export class Relationship {
+    constructor(parentDb, childDb, childCollection, foreignKey) {
+        this.parentDb = parentDb;
+        this.childDb = childDb;
+        this.childCollection = childCollection;
+        this.foreignKey = foreignKey;
+    }
+    /**
+     * Load related children for a parent item.
+     */
+    async load(parentId) {
+        const result = await this.childDb.query(this.childCollection);
+        if (!result.success || !result.data) {
+            return [];
+        }
+        try {
+            const children = JSON.parse(result.data);
+            return children.filter((child) => {
+                try {
+                    return this.foreignKey(child) === parentId;
+                }
+                catch {
+                    return false;
+                }
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+}