trellis 2.0.8 → 2.0.13

package/src/core/ontology/validator.ts

@@ -0,0 +1,382 @@
+/**
+ * Ontology Validation — Schema enforcement for graph mutations.
+ *
+ * Provides both standalone validation (check existing entities against schemas)
+ * and a kernel middleware that rejects mutations violating ontology constraints.
+ *
+ * @module trellis/core/ontology
+ */
+
+import type { EAVStore, Fact, Link, Atom } from '../store/eav-store.js';
+import type { KernelOp } from '../persist/backend.js';
+import type { KernelMiddleware, MiddlewareContext, OpMiddlewareNext } from '../kernel/middleware.js';
+import type { OntologyRegistry } from './registry.js';
+import type {
+  AttributeDef,
+  AttrType,
+  EntityDef,
+  ValidationError,
+  ValidationResult,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Standalone Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a single entity against the ontology registry.
+ */
+export function validateEntity(
+  entityId: string,
+  store: EAVStore,
+  registry: OntologyRegistry,
+): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationError[] = [];
+
+  const facts = store.getFactsByEntity(entityId);
+  if (facts.length === 0) {
+    return { valid: true, errors: [], warnings: [] };
+  }
+
+  const typeFact = facts.find((f) => f.a === 'type');
+  if (!typeFact) {
+    warnings.push({
+      entityId,
+      entityType: '(unknown)',
+      field: 'type',
+      message: 'Entity has no "type" attribute.',
+      severity: 'warning',
+    });
+    return { valid: true, errors, warnings };
+  }
+
+  const entityType = String(typeFact.v);
+  const def = registry.getEntityDef(entityType);
+
+  if (!def) {
+    // Type not in any registered ontology — that's OK, just warn
+    warnings.push({
+      entityId,
+      entityType,
+      field: 'type',
+      message: `Entity type "${entityType}" is not defined in any registered ontology.`,
+      severity: 'warning',
+    });
+    return { valid: true, errors, warnings };
+  }
+
+  // Check abstract
+  if (def.abstract) {
+    errors.push({
+      entityId,
+      entityType,
+      field: 'type',
+      message: `Cannot instantiate abstract entity type "${entityType}".`,
+      severity: 'error',
+    });
+  }
+
+  // Check required attributes
+  for (const attr of def.attributes) {
+    if (attr.required && attr.name !== 'type') {
+      const hasFact = facts.some((f) => f.a === attr.name);
+      if (!hasFact) {
+        errors.push({
+          entityId,
+          entityType,
+          field: attr.name,
+          message: `Required attribute "${attr.name}" is missing.`,
+          severity: 'error',
+        });
+      }
+    }
+  }
+
+  // Validate each fact against its attribute def
+  for (const fact of facts) {
+    if (fact.a === 'type' || fact.a === 'createdAt' || fact.a === 'updatedAt') continue;
+
+    const attrDef = def.attributes.find((a) => a.name === fact.a);
+    if (!attrDef) {
+      // Unknown attribute — warn but don't error (open-world assumption)
+      warnings.push({
+        entityId,
+        entityType,
+        field: fact.a,
+        message: `Attribute "${fact.a}" is not defined in the "${entityType}" ontology.`,
+        severity: 'warning',
+      });
+      continue;
+    }
+
+    // Type check
+    const typeErr = validateAttrType(fact.v, attrDef);
+    if (typeErr) {
+      errors.push({
+        entityId,
+        entityType,
+        field: fact.a,
+        message: typeErr,
+        severity: 'error',
+      });
+    }
+
+    // Enum check
+    if (attrDef.enum && !attrDef.enum.includes(fact.v)) {
+      errors.push({
+        entityId,
+        entityType,
+        field: fact.a,
+        message: `Value "${fact.v}" is not in allowed values: [${attrDef.enum.join(', ')}].`,
+        severity: 'error',
+      });
+    }
+
+    // Pattern check
+    if (attrDef.pattern && typeof fact.v === 'string') {
+      if (!new RegExp(attrDef.pattern).test(fact.v)) {
+        errors.push({
+          entityId,
+          entityType,
+          field: fact.a,
+          message: `Value "${fact.v}" does not match pattern /${attrDef.pattern}/.`,
+          severity: 'error',
+        });
+      }
+    }
+
+    // Range check
+    if (attrDef.min !== undefined) {
+      if (typeof fact.v === 'number' && fact.v < attrDef.min) {
+        errors.push({
+          entityId,
+          entityType,
+          field: fact.a,
+          message: `Value ${fact.v} is below minimum ${attrDef.min}.`,
+          severity: 'error',
+        });
+      }
+      if (typeof fact.v === 'string' && fact.v.length < attrDef.min) {
+        errors.push({
+          entityId,
+          entityType,
+          field: fact.a,
+          message: `String length ${fact.v.length} is below minimum ${attrDef.min}.`,
+          severity: 'error',
+        });
+      }
+    }
+    if (attrDef.max !== undefined) {
+      if (typeof fact.v === 'number' && fact.v > attrDef.max) {
+        errors.push({
+          entityId,
+          entityType,
+          field: fact.a,
+          message: `Value ${fact.v} exceeds maximum ${attrDef.max}.`,
+          severity: 'error',
+        });
+      }
+      if (typeof fact.v === 'string' && fact.v.length > attrDef.max) {
+        errors.push({
+          entityId,
+          entityType,
+          field: fact.a,
+          message: `String length ${fact.v.length} exceeds maximum ${attrDef.max}.`,
+          severity: 'error',
+        });
+      }
+    }
+  }
+
+  // Validate links
+  const links = store.getLinksByEntity(entityId);
+  for (const link of links) {
+    if (link.e1 !== entityId) continue; // Only validate outgoing links
+    const relDef = registry.getRelationDef(link.a);
+    if (!relDef) continue;
+
+    // Check source type is allowed
+    if (!relDef.sourceTypes.includes(entityType)) {
+      errors.push({
+        entityId,
+        entityType,
+        field: link.a,
+        message: `Entity type "${entityType}" is not allowed as source for relation "${link.a}".`,
+        severity: 'error',
+      });
+    }
+
+    // Check target type
+    const targetFacts = store.getFactsByEntity(link.e2);
+    const targetType = targetFacts.find((f) => f.a === 'type');
+    if (targetType && !relDef.targetTypes.includes(String(targetType.v))) {
+      errors.push({
+        entityId,
+        entityType,
+        field: link.a,
+        message: `Target type "${targetType.v}" is not allowed for relation "${link.a}" (expected: ${relDef.targetTypes.join(', ')}).`,
+        severity: 'error',
+      });
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Validate all entities in the store against the ontology registry.
+ */
+export function validateStore(
+  store: EAVStore,
+  registry: OntologyRegistry,
+): ValidationResult {
+  const allErrors: ValidationError[] = [];
+  const allWarnings: ValidationError[] = [];
+
+  const typeFacts = store.getFactsByAttribute('type');
+  const entityIds = new Set(typeFacts.map((f) => f.e));
+
+  for (const entityId of entityIds) {
+    const result = validateEntity(entityId, store, registry);
+    allErrors.push(...result.errors);
+    allWarnings.push(...result.warnings);
+  }
+
+  return {
+    valid: allErrors.length === 0,
+    errors: allErrors,
+    warnings: allWarnings,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Type checking helper
+// ---------------------------------------------------------------------------
+
+function validateAttrType(value: Atom, def: AttributeDef): string | null {
+  if (def.type === 'any') return null;
+
+  switch (def.type) {
+    case 'string':
+      if (typeof value !== 'string') return `Expected string, got ${typeof value}.`;
+      break;
+    case 'number':
+      if (typeof value !== 'number') return `Expected number, got ${typeof value}.`;
+      break;
+    case 'boolean':
+      if (typeof value !== 'boolean') return `Expected boolean, got ${typeof value}.`;
+      break;
+    case 'date':
+      if (typeof value === 'string') {
+        if (isNaN(Date.parse(value))) return `Expected ISO date string, got "${value}".`;
+      } else if (!(value instanceof Date)) {
+        return `Expected date, got ${typeof value}.`;
+      }
+      break;
+    case 'ref':
+      if (typeof value !== 'string') return `Expected entity reference (string), got ${typeof value}.`;
+      break;
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Validation Middleware
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a kernel middleware that validates mutations against the ontology.
+ *
+ * - On `addFacts`: validates that new facts conform to attribute definitions
+ * - On `addLinks`: validates that links conform to relation definitions
+ * - Blocks operations that would create invalid data (throws on error)
+ *
+ * @param registry The ontology registry to validate against
+ * @param strict If true, unknown entity types cause errors (default: false = warnings only)
+ */
+export function createValidationMiddleware(
+  registry: OntologyRegistry,
+  options?: { strict?: boolean },
+): KernelMiddleware {
+  const strict = options?.strict ?? false;
+
+  return {
+    name: 'ontology-validator',
+
+    handleOp: (op: KernelOp, ctx: MiddlewareContext, next: OpMiddlewareNext) => {
+      // Validate new facts
+      if (op.facts && op.facts.length > 0) {
+        for (const fact of op.facts) {
+          if (fact.a === 'type') continue; // type facts are always allowed
+          if (fact.a === 'createdAt' || fact.a === 'updatedAt') continue;
+
+          // Find the entity type from the same op's facts or skip
+          const typeFact = op.facts.find((f) => f.e === fact.e && f.a === 'type');
+          if (!typeFact) continue; // Can't validate without knowing the type
+
+          const entityType = String(typeFact.v);
+          const def = registry.getEntityDef(entityType);
+          if (!def) {
+            if (strict) {
+              throw new Error(
+                `[ontology-validator] Unknown entity type "${entityType}" for entity "${fact.e}".`,
+              );
+            }
+            continue;
+          }
+
+          const attrDef = def.attributes.find((a) => a.name === fact.a);
+          if (!attrDef) {
+            if (strict) {
+              throw new Error(
+                `[ontology-validator] Unknown attribute "${fact.a}" for type "${entityType}".`,
+              );
+            }
+            continue;
+          }
+
+          // Type check
+          const typeErr = validateAttrType(fact.v, attrDef);
+          if (typeErr) {
+            throw new Error(
+              `[ontology-validator] Entity "${fact.e}" attribute "${fact.a}": ${typeErr}`,
+            );
+          }
+
+          // Enum check
+          if (attrDef.enum && !attrDef.enum.includes(fact.v)) {
+            throw new Error(
+              `[ontology-validator] Entity "${fact.e}" attribute "${fact.a}": value "${fact.v}" not in [${attrDef.enum.join(', ')}].`,
+            );
+          }
+        }
+      }
+
+      // Validate new links
+      if (op.links && op.links.length > 0) {
+        for (const link of op.links) {
+          const relDef = registry.getRelationDef(link.a);
+          if (!relDef) continue; // Unknown relation — skip
+
+          // Source type check (from op facts)
+          const sourceTypeFact = op.facts?.find(
+            (f) => f.e === link.e1 && f.a === 'type',
+          );
+          if (sourceTypeFact && !relDef.sourceTypes.includes(String(sourceTypeFact.v))) {
+            throw new Error(
+              `[ontology-validator] Relation "${link.a}": source type "${sourceTypeFact.v}" not allowed (expected: ${relDef.sourceTypes.join(', ')}).`,
+            );
+          }
+        }
+      }
+
+      return next(op, ctx);
+    },
+  };
+}

package/src/core/persist/backend.ts

@@ -45,6 +45,16 @@ export interface KernelOp {
    */
   facts?: Fact[];
   links?: Link[];
+
+  /**
+   * Facts to delete (for update/delete operations).
+   */
+  deleteFacts?: Fact[];
+
+  /**
+   * Links to delete (for update/delete operations).
+   */
+  deleteLinks?: Link[];
 }
 
 export interface KernelBackend {

package/src/core/persist/sqlite-backend.ts

@@ -0,0 +1,298 @@
+/**
+ * SQLite-backed Kernel Backend
+ *
+ * Replaces the P0 JsonOpLog with a proper WAL-mode SQLite database.
+ * Stores ops, snapshots, and blobs in a single database file.
+ *
+ * @module trellis/core
+ */
+
+import { Database } from 'bun:sqlite';
+import type { KernelOp, KernelBackend } from './backend.js';
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS ops (
+  hash TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  timestamp TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  previous_hash TEXT,
+  payload TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS snapshots (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  last_op_hash TEXT NOT NULL,
+  data TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS blobs (
+  hash TEXT PRIMARY KEY,
+  content BLOB NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_ops_kind ON ops(kind);
+CREATE INDEX IF NOT EXISTS idx_ops_timestamp ON ops(timestamp);
+CREATE INDEX IF NOT EXISTS idx_ops_agent ON ops(agent_id);
+CREATE INDEX IF NOT EXISTS idx_ops_previous ON ops(previous_hash);
+CREATE INDEX IF NOT EXISTS idx_snapshots_op ON snapshots(last_op_hash);
+`;
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+export class SqliteKernelBackend implements KernelBackend {
+  private db: Database;
+  private _stmts: {
+    insert: ReturnType<Database['prepare']>;
+    readAll: ReturnType<Database['prepare']>;
+    readUntil: ReturnType<Database['prepare']>;
+    readAfter: ReturnType<Database['prepare']>;
+    getByHash: ReturnType<Database['prepare']>;
+    getLast: ReturnType<Database['prepare']>;
+    count: ReturnType<Database['prepare']>;
+    saveSnapshot: ReturnType<Database['prepare']>;
+    loadSnapshot: ReturnType<Database['prepare']>;
+    putBlob: ReturnType<Database['prepare']>;
+    getBlob: ReturnType<Database['prepare']>;
+    hasBlob: ReturnType<Database['prepare']>;
+  } | null = null;
+
+  constructor(private dbPath: string) {
+    this.db = new Database(dbPath);
+  }
+
+  init(): void {
+    this.db.exec('PRAGMA journal_mode=WAL;');
+    this.db.exec('PRAGMA foreign_keys=ON;');
+    this.db.exec('PRAGMA synchronous=NORMAL;');
+    this.db.exec(SCHEMA_SQL);
+    this._prepareStatements();
+  }
+
+  private _prepareStatements(): void {
+    this._stmts = {
+      insert: this.db.prepare(`
+        INSERT OR IGNORE INTO ops (hash, kind, timestamp, agent_id, previous_hash, payload)
+        VALUES ($hash, $kind, $timestamp, $agentId, $previousHash, $payload)
+      `),
+      readAll: this.db.prepare(`
+        SELECT hash, kind, timestamp, agent_id, previous_hash, payload
+        FROM ops ORDER BY rowid ASC
+      `),
+      readUntil: this.db.prepare(`
+        SELECT hash, kind, timestamp, agent_id, previous_hash, payload
+        FROM ops WHERE rowid <= (SELECT rowid FROM ops WHERE hash = $hash)
+        ORDER BY rowid ASC
+      `),
+      readAfter: this.db.prepare(`
+        SELECT hash, kind, timestamp, agent_id, previous_hash, payload
+        FROM ops WHERE rowid > (SELECT rowid FROM ops WHERE hash = $hash)
+        ORDER BY rowid ASC
+      `),
+      getByHash: this.db.prepare(`
+        SELECT hash, kind, timestamp, agent_id, previous_hash, payload
+        FROM ops WHERE hash = $hash
+      `),
+      getLast: this.db.prepare(`
+        SELECT hash, kind, timestamp, agent_id, previous_hash, payload
+        FROM ops ORDER BY rowid DESC LIMIT 1
+      `),
+      count: this.db.prepare('SELECT COUNT(*) as cnt FROM ops'),
+      saveSnapshot: this.db.prepare(`
+        INSERT INTO snapshots (last_op_hash, data)
+        VALUES ($lastOpHash, $data)
+      `),
+      loadSnapshot: this.db.prepare(`
+        SELECT last_op_hash, data FROM snapshots
+        ORDER BY id DESC LIMIT 1
+      `),
+      putBlob: this.db.prepare(`
+        INSERT OR IGNORE INTO blobs (hash, content) VALUES ($hash, $content)
+      `),
+      getBlob: this.db.prepare(`
+        SELECT content FROM blobs WHERE hash = $hash
+      `),
+      hasBlob: this.db.prepare(`
+        SELECT 1 FROM blobs WHERE hash = $hash
+      `),
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Op operations
+  // -------------------------------------------------------------------------
+
+  append(op: KernelOp): void {
+    const payload = JSON.stringify({
+      facts: op.facts,
+      links: op.links,
+      ...(op.deleteFacts?.length ? { deleteFacts: op.deleteFacts } : {}),
+      ...(op.deleteLinks?.length ? { deleteLinks: op.deleteLinks } : {}),
+      ...((op as any).vcs ? { vcs: (op as any).vcs } : {}),
+      ...((op as any).signature ? { signature: (op as any).signature } : {}),
+    });
+
+    this._stmts!.insert.run({
+      $hash: op.hash,
+      $kind: op.kind,
+      $timestamp: op.timestamp,
+      $agentId: op.agentId,
+      $previousHash: op.previousHash ?? null,
+      $payload: payload,
+    });
+  }
+
+  appendBatch(ops: KernelOp[]): void {
+    if (ops.length === 0) return;
+    this.db.transaction(() => {
+      for (const op of ops) {
+        this.append(op);
+      }
+    })();
+  }
+
+  readAll(): KernelOp[] {
+    const rows = this._stmts!.readAll.all() as any[];
+    return rows.map(rowToOp);
+  }
+
+  readUntil(hash: string): KernelOp[] {
+    const rows = this._stmts!.readUntil.all({ $hash: hash }) as any[];
+    return rows.map(rowToOp);
+  }
+
+  readAfter(hash: string): KernelOp[] {
+    const rows = this._stmts!.readAfter.all({ $hash: hash }) as any[];
+    return rows.map(rowToOp);
+  }
+
+  readUntilTimestamp(isoTimestamp: string): KernelOp[] {
+    const rows = this.db
+      .prepare(
+        `SELECT hash, kind, timestamp, agent_id, previous_hash, payload
+         FROM ops WHERE timestamp <= $ts ORDER BY rowid ASC`,
+      )
+      .all({ $ts: isoTimestamp }) as any[];
+    return rows.map(rowToOp);
+  }
+
+  getLastOp(): KernelOp | undefined {
+    const row = this._stmts!.getLast.get() as any;
+    return row ? rowToOp(row) : undefined;
+  }
+
+  getOpByHash(hash: string): KernelOp | undefined {
+    const row = this._stmts!.getByHash.get({ $hash: hash }) as any;
+    return row ? rowToOp(row) : undefined;
+  }
+
+  count(): number {
+    const row = this._stmts!.count.get() as any;
+    return row?.cnt ?? 0;
+  }
+
+  /**
+   * Find the common ancestor op of two op hashes by walking
+   * previousHash chains until they converge.
+   */
+  findCommonAncestor(hashA: string, hashB: string): KernelOp | undefined {
+    // Collect ancestors of A
+    const ancestorsA = new Set<string>();
+    let cursor: string | undefined = hashA;
+    while (cursor) {
+      ancestorsA.add(cursor);
+      const op = this.getOpByHash(cursor);
+      cursor = op?.previousHash;
+    }
+
+    // Walk B's chain until we find a common ancestor
+    cursor = hashB;
+    while (cursor) {
+      if (ancestorsA.has(cursor)) {
+        return this.getOpByHash(cursor);
+      }
+      const op = this.getOpByHash(cursor);
+      cursor = op?.previousHash;
+    }
+
+    return undefined;
+  }
+
+  // -------------------------------------------------------------------------
+  // Snapshot operations
+  // -------------------------------------------------------------------------
+
+  saveSnapshot(lastOpHash: string, data: any): void {
+    this._stmts!.saveSnapshot.run({
+      $lastOpHash: lastOpHash,
+      $data: JSON.stringify(data),
+    });
+  }
+
+  loadLatestSnapshot(): { lastOpHash: string; data: any } | undefined {
+    const row = this._stmts!.loadSnapshot.get() as any;
+    if (!row) return undefined;
+    return {
+      lastOpHash: row.last_op_hash,
+      data: JSON.parse(row.data),
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Blob operations
+  // -------------------------------------------------------------------------
+
+  putBlob(hash: string, content: Uint8Array): void {
+    this._stmts!.putBlob.run({
+      $hash: hash,
+      $content: Buffer.from(content),
+    });
+  }
+
+  getBlob(hash: string): Uint8Array | undefined {
+    const row = this._stmts!.getBlob.get({ $hash: hash }) as any;
+    if (!row) return undefined;
+    return new Uint8Array(row.content);
+  }
+
+  hasBlob(hash: string): boolean {
+    return !!this._stmts!.hasBlob.get({ $hash: hash });
+  }
+
+  // -------------------------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------------------------
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rowToOp(row: any): KernelOp {
+  const payload = JSON.parse(row.payload);
+  const op: any = {
+    hash: row.hash,
+    kind: row.kind,
+    timestamp: row.timestamp,
+    agentId: row.agent_id,
+  };
+  if (row.previous_hash) op.previousHash = row.previous_hash;
+  if (payload.facts) op.facts = payload.facts;
+  if (payload.links) op.links = payload.links;
+  if (payload.deleteFacts) op.deleteFacts = payload.deleteFacts;
+  if (payload.deleteLinks) op.deleteLinks = payload.deleteLinks;
+  if (payload.vcs) op.vcs = payload.vcs;
+  if (payload.signature) op.signature = payload.signature;
+  return op;
+}

package/src/core/plugins/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Plugin System — Public API Surface
+ *
+ * @module trellis/core/plugins
+ */
+
+export { PluginRegistry, EventBus } from './registry.js';
+
+export type {
+  PluginDef,
+  PluginContext,
+  PluginManifest,
+  EventCallback,
+  EventHandler,
+  WellKnownEvent,
+  WorkspaceConfig,
+} from './types.js';