trellis 2.0.13 → 2.1.2

package/src/core/kernel/trellis-kernel.ts

@@ -1,593 +0,0 @@
-/**
- * TrellisKernel — Generic Graph Kernel
- *
- * The composition root for the Trellis semantic kernel. Orchestrates the
- * EAV store, persistence backend, middleware chain, and snapshot lifecycle.
- *
- * The VCS engine (`TrellisVcsEngine`) sits on top of this generic kernel.
- * Non-VCS consumers can use TrellisKernel directly for pure graph CRUD.
- *
- * @module trellis/core
- */
-
-import { EAVStore } from '../store/eav-store.js';
-import type { Fact, Link, Atom } from '../store/eav-store.js';
-import type {
-  KernelOp,
-  KernelOpKind,
-  KernelBackend,
-} from '../persist/backend.js';
-import type {
-  KernelMiddleware,
-  MiddlewareContext,
-  OpMiddlewareNext,
-} from './middleware.js';
-import { QueryEngine } from '../query/engine.js';
-import type { Query } from '../query/types.js';
-import type { QueryResult } from '../query/engine.js';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface KernelConfig {
-  /** Persistence backend (SQLite or in-memory). */
-  backend: KernelBackend;
-  /** Agent ID for attributing operations. */
-  agentId: string;
-  /** Middleware chain applied to every mutation. */
-  middleware?: KernelMiddleware[];
-  /** Auto-snapshot after this many ops (0 = disabled). */
-  snapshotThreshold?: number;
-}
-
-export interface MutateResult {
-  op: KernelOp;
-  factsDelta: { added: number; deleted: number };
-  linksDelta: { added: number; deleted: number };
-}
-
-export interface EntityRecord {
-  id: string;
-  type: string;
-  facts: Fact[];
-  links: Link[];
-}
-
-// ---------------------------------------------------------------------------
-// Content-addressed hash
-// ---------------------------------------------------------------------------
-
-async function hashOp(
-  kind: string,
-  timestamp: string,
-  agentId: string,
-  previousHash: string | undefined,
-  payload: string,
-): Promise<string> {
-  const data = `${kind}|${timestamp}|${agentId}|${previousHash ?? ''}|${payload}`;
-  const buf = new TextEncoder().encode(data);
-  const hashBuf = await crypto.subtle.digest('SHA-256', buf);
-  const hex = Array.from(new Uint8Array(hashBuf))
-    .map((b) => b.toString(16).padStart(2, '0'))
-    .join('');
-  return `trellis:op:${hex}`;
-}
-
-// ---------------------------------------------------------------------------
-// Kernel
-// ---------------------------------------------------------------------------
-
-export class TrellisKernel {
-  private store: EAVStore;
-  private backend: KernelBackend;
-  private middleware: KernelMiddleware[];
-  private agentId: string;
-  private snapshotThreshold: number;
-  private opsSinceSnapshot: number = 0;
-  private _booted: boolean = false;
-
-  constructor(config: KernelConfig) {
-    this.store = new EAVStore();
-    this.backend = config.backend;
-    this.agentId = config.agentId;
-    this.middleware = config.middleware ?? [];
-    this.snapshotThreshold = config.snapshotThreshold ?? 0;
-  }
-
-  // -------------------------------------------------------------------------
-  // Lifecycle
-  // -------------------------------------------------------------------------
-
-  /**
-   * Initialize the backend and replay persisted state.
-   * Loads latest snapshot if available, then replays ops after it.
-   */
-  boot(): { opsReplayed: number; fromSnapshot: boolean } {
-    this.backend.init();
-
-    let opsReplayed = 0;
-    let fromSnapshot = false;
-
-    // Try loading from snapshot
-    const snapshot = this.backend.loadLatestSnapshot();
-    if (snapshot) {
-      this.store.restore(snapshot.data);
-      fromSnapshot = true;
-
-      // Replay only ops after the snapshot
-      const recentOps = this.backend.readAfter(snapshot.lastOpHash);
-      for (const op of recentOps) {
-        this._replayOp(op);
-        opsReplayed++;
-      }
-    } else {
-      // Full replay
-      const allOps = this.backend.readAll();
-      for (const op of allOps) {
-        this._replayOp(op);
-        opsReplayed++;
-      }
-    }
-
-    this._booted = true;
-    return { opsReplayed, fromSnapshot };
-  }
-
-  /**
-   * Close the backend connection.
-   */
-  close(): void {
-    this.backend.close?.();
-    this._booted = false;
-  }
-
-  isBooted(): boolean {
-    return this._booted;
-  }
-
-  // -------------------------------------------------------------------------
-  // Mutations
-  // -------------------------------------------------------------------------
-
-  /**
-   * Apply a mutation to the graph. Creates an op, runs it through middleware,
-   * decomposes into EAV primitives, persists, and returns the result.
-   */
-  async mutate(
-    kind: KernelOpKind | string,
-    payload: {
-      facts?: Fact[];
-      links?: Link[];
-      deleteFacts?: Fact[];
-      deleteLinks?: Link[];
-      meta?: Record<string, unknown>;
-    },
-    ctx?: Partial<MiddlewareContext>,
-  ): Promise<MutateResult> {
-    const timestamp = new Date().toISOString();
-    const lastOp = this.backend.getLastOp();
-    const agentId = ctx?.agentId ?? this.agentId;
-
-    const payloadStr = JSON.stringify(payload);
-    const hash = await hashOp(
-      kind,
-      timestamp,
-      agentId,
-      lastOp?.hash,
-      payloadStr,
-    );
-
-    const op: KernelOp = {
-      hash,
-      kind: kind as KernelOpKind,
-      timestamp,
-      agentId,
-      previousHash: lastOp?.hash,
-      facts: [...(payload.facts ?? [])],
-      links: [...(payload.links ?? [])],
-      deleteFacts: payload.deleteFacts?.length
-        ? [...payload.deleteFacts]
-        : undefined,
-      deleteLinks: payload.deleteLinks?.length
-        ? [...payload.deleteLinks]
-        : undefined,
-    };
-
-    // Attach meta as extra properties for middleware consumption
-    const extOp = op as any;
-    if (payload.meta) {
-      for (const [k, v] of Object.entries(payload.meta)) {
-        extOp[k] = v;
-      }
-    }
-
-    // Run through middleware chain
-    const mwCtx: MiddlewareContext = { agentId, ...ctx };
-    await this._runMiddleware(op, mwCtx);
-
-    // Apply to store
-    let factsAdded = 0;
-    let factsDeleted = 0;
-    let linksAdded = 0;
-    let linksDeleted = 0;
-
-    if (payload.deleteFacts && payload.deleteFacts.length > 0) {
-      this.store.deleteFacts(payload.deleteFacts);
-      factsDeleted = payload.deleteFacts.length;
-    }
-    if (payload.deleteLinks && payload.deleteLinks.length > 0) {
-      this.store.deleteLinks(payload.deleteLinks);
-      linksDeleted = payload.deleteLinks.length;
-    }
-    if (payload.facts && payload.facts.length > 0) {
-      this.store.addFacts(payload.facts);
-      factsAdded = payload.facts.length;
-    }
-    if (payload.links && payload.links.length > 0) {
-      this.store.addLinks(payload.links);
-      linksAdded = payload.links.length;
-    }
-
-    // Persist
-    this.backend.append(op);
-
-    // Auto-snapshot
-    this.opsSinceSnapshot++;
-    if (
-      this.snapshotThreshold > 0 &&
-      this.opsSinceSnapshot >= this.snapshotThreshold
-    ) {
-      this.checkpoint();
-    }
-
-    return {
-      op,
-      factsDelta: { added: factsAdded, deleted: factsDeleted },
-      linksDelta: { added: linksAdded, deleted: linksDeleted },
-    };
-  }
-
-  /**
-   * Create a snapshot of the current store state.
-   */
-  checkpoint(): void {
-    const lastOp = this.backend.getLastOp();
-    if (!lastOp) return;
-    this.backend.saveSnapshot(lastOp.hash, this.store.snapshot());
-    this.opsSinceSnapshot = 0;
-  }
-
-  // -------------------------------------------------------------------------
-  // Queries
-  // -------------------------------------------------------------------------
-
-  /**
-   * Get the underlying EAV store for direct queries.
-   */
-  getStore(): EAVStore {
-    return this.store;
-  }
-
-  /**
-   * Get the persistence backend.
-   */
-  getBackend(): KernelBackend {
-    return this.backend;
-  }
-
-  /**
-   * Get the agent ID.
-   */
-  getAgentId(): string {
-    return this.agentId;
-  }
-
-  /**
-   * Read all persisted ops.
-   */
-  readAllOps(): KernelOp[] {
-    return this.backend.readAll();
-  }
-
-  /**
-   * Get the last persisted op.
-   */
-  getLastOp(): KernelOp | undefined {
-    return this.backend.getLastOp();
-  }
-
-  /**
-   * Create a QueryEngine bound to this kernel's store.
-   */
-  createQueryEngine(): QueryEngine {
-    return new QueryEngine(this.store);
-  }
-
-  /**
-   * Execute an EQL-S query, routing through middleware handleQuery hooks.
-   * If no middleware intercepts, the query runs directly against the store.
-   */
-  async query(q: Query): Promise<QueryResult> {
-    const engine = new QueryEngine(this.store);
-    const ctx: MiddlewareContext = { agentId: this.agentId };
-
-    // Build middleware chain for queries
-    const chain = this.middleware.filter((m) => m.handleQuery);
-
-    if (chain.length === 0) {
-      return engine.execute(q);
-    }
-
-    let result: QueryResult | undefined;
-    let idx = 0;
-
-    const next = (query: unknown, context: MiddlewareContext): QueryResult => {
-      if (idx < chain.length) {
-        const mw = chain[idx++];
-        return mw.handleQuery!(query, context, next);
-      }
-      result = engine.execute(query as Query);
-      return result;
-    };
-
-    result = next(q, ctx);
-    return result!;
-  }
-
-  /**
-   * Time-travel: reconstruct the store state at a specific op hash.
-   * Returns a new EAVStore with state replayed up to (and including) that op.
-   */
-  timeTravel(opHash: string): EAVStore {
-    const ops = this.backend.readUntil(opHash);
-    const snapshot = new EAVStore();
-
-    for (const op of ops) {
-      if (op.deleteFacts && op.deleteFacts.length > 0) {
-        snapshot.deleteFacts(op.deleteFacts);
-      }
-      if (op.deleteLinks && op.deleteLinks.length > 0) {
-        snapshot.deleteLinks(op.deleteLinks);
-      }
-      if (op.facts && op.facts.length > 0) {
-        snapshot.addFacts(op.facts);
-      }
-      if (op.links && op.links.length > 0) {
-        snapshot.addLinks(op.links);
-      }
-    }
-
-    return snapshot;
-  }
-
-  // -------------------------------------------------------------------------
-  // Entity CRUD (high-level graph operations)
-  // -------------------------------------------------------------------------
-
-  /**
-   * Create a new entity with the given type and attributes.
-   * Returns the entity ID.
-   */
-  async createEntity(
-    entityId: string,
-    type: string,
-    attributes: Record<string, Atom> = {},
-    links?: Array<{ attribute: string; targetEntityId: string }>,
-  ): Promise<MutateResult> {
-    const facts: Fact[] = [
-      { e: entityId, a: 'type', v: type },
-      { e: entityId, a: 'createdAt', v: new Date().toISOString() },
-    ];
-
-    for (const [attr, value] of Object.entries(attributes)) {
-      facts.push({ e: entityId, a: attr, v: value });
-    }
-
-    const linkRecords: Link[] = (links ?? []).map((l) => ({
-      e1: entityId,
-      a: l.attribute,
-      e2: l.targetEntityId,
-    }));
-
-    return this.mutate('addFacts', {
-      facts,
-      links: linkRecords.length > 0 ? linkRecords : undefined,
-    });
-  }
-
-  /**
-   * Get an entity by ID, returning all its facts and links.
-   */
-  getEntity(entityId: string): EntityRecord | null {
-    const facts = this.store.getFactsByEntity(entityId);
-    if (facts.length === 0) return null;
-
-    const typeFact = facts.find((f) => f.a === 'type');
-
-    return {
-      id: entityId,
-      type: (typeFact?.v as string) ?? 'unknown',
-      facts,
-      links: this.store.getLinksByEntity(entityId),
-    };
-  }
-
-  /**
-   * Update an entity's attributes. Deletes old values and adds new ones.
-   */
-  async updateEntity(
-    entityId: string,
-    updates: Record<string, Atom>,
-  ): Promise<MutateResult> {
-    const existingFacts = this.store.getFactsByEntity(entityId);
-    const deleteFacts: Fact[] = [];
-    const addFacts: Fact[] = [];
-
-    for (const [attr, newValue] of Object.entries(updates)) {
-      // Find existing facts for this attribute
-      const existing = existingFacts.filter((f) => f.a === attr);
-      deleteFacts.push(...existing);
-      addFacts.push({ e: entityId, a: attr, v: newValue });
-    }
-
-    // Add updatedAt
-    const updatedAtFacts = existingFacts.filter((f) => f.a === 'updatedAt');
-    deleteFacts.push(...updatedAtFacts);
-    addFacts.push({ e: entityId, a: 'updatedAt', v: new Date().toISOString() });
-
-    return this.mutate('addFacts', {
-      facts: addFacts,
-      deleteFacts,
-    });
-  }
-
-  /**
-   * Delete an entity and all its facts and links.
-   */
-  async deleteEntity(entityId: string): Promise<MutateResult> {
-    const facts = this.store.getFactsByEntity(entityId);
-    const links = this.store.getLinksByEntity(entityId);
-
-    return this.mutate('deleteFacts', {
-      deleteFacts: facts,
-      deleteLinks: links,
-    });
-  }
-
-  /**
-   * List entities by type, with optional attribute filters.
-   */
-  listEntities(type?: string, filters?: Record<string, Atom>): EntityRecord[] {
-    let entityIds: Set<string>;
-
-    if (type) {
-      const typeFacts = this.store.getFactsByValue('type', type);
-      entityIds = new Set(typeFacts.map((f) => f.e));
-    } else {
-      const allTypeFacts = this.store.getFactsByAttribute('type');
-      entityIds = new Set(allTypeFacts.map((f) => f.e));
-    }
-
-    // Apply attribute filters
-    if (filters) {
-      for (const [attr, value] of Object.entries(filters)) {
-        const matchingFacts = this.store.getFactsByValue(attr, value);
-        const matchingEntities = new Set(matchingFacts.map((f) => f.e));
-        for (const id of entityIds) {
-          if (!matchingEntities.has(id)) {
-            entityIds.delete(id);
-          }
-        }
-      }
-    }
-
-    return Array.from(entityIds)
-      .map((id) => this.getEntity(id)!)
-      .filter(Boolean);
-  }
-
-  /**
-   * Add a link between two entities.
-   */
-  async addLink(
-    sourceId: string,
-    attribute: string,
-    targetId: string,
-  ): Promise<MutateResult> {
-    return this.mutate('addLinks', {
-      links: [{ e1: sourceId, a: attribute, e2: targetId }],
-    });
-  }
-
-  /**
-   * Remove a link between two entities.
-   */
-  async removeLink(
-    sourceId: string,
-    attribute: string,
-    targetId: string,
-  ): Promise<MutateResult> {
-    return this.mutate('deleteLinks', {
-      deleteLinks: [{ e1: sourceId, a: attribute, e2: targetId }],
-    });
-  }
-
-  /**
-   * Add a fact to an entity.
-   */
-  async addFact(
-    entityId: string,
-    attribute: string,
-    value: Atom,
-  ): Promise<MutateResult> {
-    return this.mutate('addFacts', {
-      facts: [{ e: entityId, a: attribute, v: value }],
-    });
-  }
-
-  /**
-   * Remove a fact from an entity.
-   */
-  async removeFact(
-    entityId: string,
-    attribute: string,
-    value: Atom,
-  ): Promise<MutateResult> {
-    return this.mutate('deleteFacts', {
-      deleteFacts: [{ e: entityId, a: attribute, v: value }],
-    });
-  }
-
-  // -------------------------------------------------------------------------
-  // Middleware
-  // -------------------------------------------------------------------------
-
-  addMiddleware(mw: KernelMiddleware): void {
-    this.middleware.push(mw);
-  }
-
-  removeMiddleware(name: string): void {
-    this.middleware = this.middleware.filter((m) => m.name !== name);
-  }
-
-  // -------------------------------------------------------------------------
-  // Internal
-  // -------------------------------------------------------------------------
-
-  private async _runMiddleware(
-    op: KernelOp,
-    ctx: MiddlewareContext,
-  ): Promise<void> {
-    const chain = [...this.middleware];
-    let idx = 0;
-
-    const next: OpMiddlewareNext = async (op, ctx) => {
-      const mw = chain[idx++];
-      if (mw?.handleOp) {
-        await mw.handleOp(op, ctx, next);
-      }
-    };
-
-    if (chain.length > 0) {
-      await next(op, ctx);
-    }
-  }
-
-  private _replayOp(op: KernelOp): void {
-    // Replay without persisting or middleware — just apply to store
-    // Deletions first, then additions (same order as mutate)
-    if (op.deleteFacts && op.deleteFacts.length > 0) {
-      this.store.deleteFacts(op.deleteFacts);
-    }
-    if (op.deleteLinks && op.deleteLinks.length > 0) {
-      this.store.deleteLinks(op.deleteLinks);
-    }
-    if (op.facts && op.facts.length > 0) {
-      this.store.addFacts(op.facts);
-    }
-    if (op.links && op.links.length > 0) {
-      this.store.addLinks(op.links);
-    }
-  }
-}