trellis 2.0.8 → 2.0.13

package/src/core/ontology/builtins.ts

@@ -0,0 +1,248 @@
+/**
+ * Built-in Ontology Definitions
+ *
+ * Pre-defined ontologies for common domain models:
+ *   - Project: software project management entities
+ *   - Team: team/developer organizational entities
+ *   - Agent: AI agent entities for the agent harness
+ *
+ * @module trellis/core/ontology
+ */
+
+import type { OntologySchema } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Project Ontology
+// ---------------------------------------------------------------------------
+
+export const projectOntology: OntologySchema = {
+  id: 'trellis:project',
+  name: 'Project Ontology',
+  version: '1.0.0',
+  description: 'Entity types for software project management.',
+  entities: [
+    {
+      name: 'Project',
+      description: 'A software project or repository.',
+      attributes: [
+        { name: 'name', type: 'string', required: true, description: 'Project name' },
+        { name: 'description', type: 'string', description: 'Project description' },
+        { name: 'status', type: 'string', enum: ['active', 'archived', 'draft', 'deprecated'], default: 'active' },
+        { name: 'url', type: 'string', description: 'Project URL or repository link' },
+        { name: 'language', type: 'string', description: 'Primary programming language' },
+        { name: 'createdAt', type: 'date', description: 'Creation timestamp' },
+        { name: 'updatedAt', type: 'date', description: 'Last update timestamp' },
+      ],
+    },
+    {
+      name: 'Module',
+      description: 'A logical module or package within a project.',
+      attributes: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'path', type: 'string', description: 'Filesystem path relative to project root' },
+        { name: 'description', type: 'string' },
+      ],
+    },
+    {
+      name: 'Feature',
+      description: 'A product feature or capability.',
+      attributes: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'description', type: 'string' },
+        { name: 'status', type: 'string', enum: ['planned', 'in-progress', 'shipped', 'cut'], default: 'planned' },
+        { name: 'priority', type: 'string', enum: ['critical', 'high', 'medium', 'low'], default: 'medium' },
+      ],
+    },
+    {
+      name: 'Dependency',
+      description: 'An external dependency or library.',
+      attributes: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'version', type: 'string' },
+        { name: 'registry', type: 'string', description: 'Package registry (npm, pypi, etc.)' },
+        { name: 'scope', type: 'string', enum: ['runtime', 'dev', 'optional'], default: 'runtime' },
+      ],
+    },
+    {
+      name: 'Config',
+      description: 'A configuration entry or setting.',
+      attributes: [
+        { name: 'key', type: 'string', required: true },
+        { name: 'value', type: 'any', required: true },
+        { name: 'description', type: 'string' },
+        { name: 'scope', type: 'string', enum: ['project', 'user', 'system'], default: 'project' },
+      ],
+    },
+    {
+      name: 'Artifact',
+      description: 'A build artifact, release asset, or output file.',
+      attributes: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'path', type: 'string' },
+        { name: 'size', type: 'number' },
+        { name: 'hash', type: 'string' },
+        { name: 'format', type: 'string' },
+      ],
+    },
+    {
+      name: 'Release',
+      description: 'A versioned release of a project.',
+      attributes: [
+        { name: 'version', type: 'string', required: true },
+        { name: 'tag', type: 'string' },
+        { name: 'date', type: 'date' },
+        { name: 'notes', type: 'string' },
+        { name: 'status', type: 'string', enum: ['draft', 'published', 'yanked'], default: 'draft' },
+      ],
+    },
+  ],
+  relations: [
+    { name: 'contains', sourceTypes: ['Project'], targetTypes: ['Module', 'Feature', 'Config'], cardinality: 'many', description: 'Project contains modules/features/configs' },
+    { name: 'dependsOn', sourceTypes: ['Project', 'Module'], targetTypes: ['Dependency', 'Module', 'Project'], cardinality: 'many', description: 'Depends on another entity' },
+    { name: 'implementedBy', sourceTypes: ['Feature'], targetTypes: ['Module'], cardinality: 'many', description: 'Feature is implemented by modules' },
+    { name: 'produces', sourceTypes: ['Project', 'Release'], targetTypes: ['Artifact'], cardinality: 'many', description: 'Produces artifacts' },
+    { name: 'releases', sourceTypes: ['Project'], targetTypes: ['Release'], cardinality: 'many', description: 'Project has releases' },
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// Team / Developer Ontology
+// ---------------------------------------------------------------------------
+
+export const teamOntology: OntologySchema = {
+  id: 'trellis:team',
+  name: 'Team Ontology',
+  version: '1.0.0',
+  description: 'Entity types for team and developer organization.',
+  entities: [
+    {
+      name: 'Team',
+      description: 'A team or organizational group.',
+      attributes: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'description', type: 'string' },
+        { name: 'slug', type: 'string', description: 'URL-safe identifier' },
+      ],
+    },
+    {
+      name: 'Developer',
+      description: 'A developer or contributor.',
+      attributes: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'email', type: 'string' },
+        { name: 'handle', type: 'string', description: 'Username or handle' },
+        { name: 'role', type: 'string', enum: ['admin', 'maintainer', 'contributor', 'reviewer'] },
+      ],
+    },
+    {
+      name: 'Role',
+      description: 'A named role with specific permissions.',
+      attributes: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'description', type: 'string' },
+        { name: 'permissions', type: 'string', unique: false, description: 'Permission strings (multi-valued)' },
+      ],
+    },
+    {
+      name: 'Capability',
+      description: 'A skill or capability.',
+      attributes: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'category', type: 'string' },
+        { name: 'level', type: 'string', enum: ['beginner', 'intermediate', 'advanced', 'expert'] },
+      ],
+    },
+  ],
+  relations: [
+    { name: 'hasMember', sourceTypes: ['Team'], targetTypes: ['Developer'], cardinality: 'many', inverse: 'memberOf', description: 'Team has member' },
+    { name: 'memberOf', sourceTypes: ['Developer'], targetTypes: ['Team'], cardinality: 'many', inverse: 'hasMember', description: 'Developer is member of team' },
+    { name: 'owns', sourceTypes: ['Developer'], targetTypes: ['Project', 'Module'], cardinality: 'many', description: 'Developer owns/maintains' },
+    { name: 'reviewsFor', sourceTypes: ['Developer'], targetTypes: ['Project', 'Module'], cardinality: 'many', description: 'Developer reviews for' },
+    { name: 'hasCapability', sourceTypes: ['Developer'], targetTypes: ['Capability'], cardinality: 'many', description: 'Developer has capability' },
+    { name: 'hasRole', sourceTypes: ['Developer'], targetTypes: ['Role'], cardinality: 'many', description: 'Developer has role' },
+    { name: 'assignedTo', sourceTypes: ['Developer'], targetTypes: ['Feature'], cardinality: 'many', description: 'Developer is assigned to feature' },
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// Agent Ontology
+// ---------------------------------------------------------------------------
+
+export const agentOntology: OntologySchema = {
+  id: 'trellis:agent',
+  name: 'Agent Ontology',
+  version: '1.0.0',
+  description: 'Entity types for AI agents, runs, plans, and tools.',
+  entities: [
+    {
+      name: 'Agent',
+      description: 'An AI agent definition.',
+      attributes: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'description', type: 'string' },
+        { name: 'model', type: 'string', description: 'LLM model identifier' },
+        { name: 'provider', type: 'string', description: 'LLM provider (openai, anthropic, local, etc.)' },
+        { name: 'systemPrompt', type: 'string' },
+        { name: 'status', type: 'string', enum: ['active', 'inactive', 'deprecated'], default: 'active' },
+      ],
+    },
+    {
+      name: 'AgentCapability',
+      description: 'A capability or skill an agent possesses.',
+      attributes: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'description', type: 'string' },
+        { name: 'category', type: 'string' },
+      ],
+    },
+    {
+      name: 'AgentRun',
+      description: 'A single execution run of an agent.',
+      attributes: [
+        { name: 'startedAt', type: 'date', required: true },
+        { name: 'completedAt', type: 'date' },
+        { name: 'status', type: 'string', enum: ['running', 'completed', 'failed', 'cancelled'], default: 'running' },
+        { name: 'input', type: 'string' },
+        { name: 'output', type: 'string' },
+        { name: 'tokenCount', type: 'number' },
+      ],
+    },
+    {
+      name: 'AgentPlan',
+      description: 'A plan or strategy created by an agent.',
+      attributes: [
+        { name: 'title', type: 'string', required: true },
+        { name: 'description', type: 'string' },
+        { name: 'status', type: 'string', enum: ['draft', 'active', 'completed', 'abandoned'], default: 'draft' },
+      ],
+    },
+    {
+      name: 'Tool',
+      description: 'A tool available to agents.',
+      attributes: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'description', type: 'string' },
+        { name: 'schema', type: 'string', description: 'JSON schema for tool parameters' },
+        { name: 'endpoint', type: 'string' },
+      ],
+    },
+  ],
+  relations: [
+    { name: 'hasCapability', sourceTypes: ['Agent'], targetTypes: ['AgentCapability'], cardinality: 'many' },
+    { name: 'hasTool', sourceTypes: ['Agent'], targetTypes: ['Tool'], cardinality: 'many' },
+    { name: 'executedBy', sourceTypes: ['AgentRun'], targetTypes: ['Agent'], cardinality: 'one' },
+    { name: 'hasPlan', sourceTypes: ['AgentRun'], targetTypes: ['AgentPlan'], cardinality: 'many' },
+    { name: 'usedTool', sourceTypes: ['AgentRun'], targetTypes: ['Tool'], cardinality: 'many' },
+    { name: 'createdBy', sourceTypes: ['AgentPlan'], targetTypes: ['Agent'], cardinality: 'one' },
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// All built-in ontologies
+// ---------------------------------------------------------------------------
+
+export const builtinOntologies: OntologySchema[] = [
+  projectOntology,
+  teamOntology,
+  agentOntology,
+];

package/src/core/ontology/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Ontology Module — Public API Surface
+ *
+ * @module trellis/core/ontology
+ */
+
+// Types
+export type {
+  AttrType,
+  AttributeDef,
+  RelationDef,
+  EntityDef,
+  OntologySchema,
+  ValidationError,
+  ValidationResult,
+} from './types.js';
+
+// Registry
+export { OntologyRegistry } from './registry.js';
+
+// Built-in ontologies
+export {
+  projectOntology,
+  teamOntology,
+  agentOntology,
+  builtinOntologies,
+} from './builtins.js';
+
+// Validation
+export {
+  validateEntity,
+  validateStore,
+  createValidationMiddleware,
+} from './validator.js';

package/src/core/ontology/registry.ts

@@ -0,0 +1,209 @@
+/**
+ * Ontology Registry — Manages loaded ontology schemas.
+ *
+ * Provides registration, lookup, inheritance resolution, and
+ * entity-type-to-schema mapping.
+ *
+ * @module trellis/core/ontology
+ */
+
+import type {
+  OntologySchema,
+  EntityDef,
+  RelationDef,
+  AttributeDef,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export class OntologyRegistry {
+  private schemas: Map<string, OntologySchema> = new Map();
+  /** Resolved entity defs (with inherited attributes merged). */
+  private resolvedEntities: Map<string, { def: EntityDef; ontologyId: string }> = new Map();
+  /** Resolved relation defs. */
+  private resolvedRelations: Map<string, { def: RelationDef; ontologyId: string }[]> = new Map();
+
+  /**
+   * Register an ontology schema.
+   * Throws if an ontology with the same ID is already registered at the same version.
+   */
+  register(schema: OntologySchema): void {
+    const existing = this.schemas.get(schema.id);
+    if (existing && existing.version === schema.version) {
+      throw new Error(
+        `Ontology "${schema.id}" v${schema.version} is already registered.`,
+      );
+    }
+    this.schemas.set(schema.id, schema);
+    this._resolve(schema);
+  }
+
+  /**
+   * Unregister an ontology by ID.
+   */
+  unregister(id: string): void {
+    const schema = this.schemas.get(id);
+    if (!schema) return;
+
+    // Remove entities belonging to this ontology
+    for (const [name, entry] of this.resolvedEntities) {
+      if (entry.ontologyId === id) {
+        this.resolvedEntities.delete(name);
+      }
+    }
+
+    // Remove relations belonging to this ontology
+    for (const [name, entries] of this.resolvedRelations) {
+      const filtered = entries.filter((e) => e.ontologyId !== id);
+      if (filtered.length === 0) {
+        this.resolvedRelations.delete(name);
+      } else {
+        this.resolvedRelations.set(name, filtered);
+      }
+    }
+
+    this.schemas.delete(id);
+  }
+
+  /**
+   * Get a registered ontology schema by ID.
+   */
+  get(id: string): OntologySchema | undefined {
+    return this.schemas.get(id);
+  }
+
+  /**
+   * List all registered ontology schemas.
+   */
+  list(): OntologySchema[] {
+    return [...this.schemas.values()];
+  }
+
+  /**
+   * Get the resolved entity definition for an entity type name.
+   * Returns the entity def with inherited attributes merged in.
+   */
+  getEntityDef(typeName: string): EntityDef | undefined {
+    return this.resolvedEntities.get(typeName)?.def;
+  }
+
+  /**
+   * Get the ontology ID that defines a given entity type.
+   */
+  getEntityOntology(typeName: string): string | undefined {
+    return this.resolvedEntities.get(typeName)?.ontologyId;
+  }
+
+  /**
+   * List all known entity type names.
+   */
+  listEntityTypes(): string[] {
+    return [...this.resolvedEntities.keys()];
+  }
+
+  /**
+   * Get all relation definitions involving a given entity type
+   * (either as source or target).
+   */
+  getRelationsForType(typeName: string): RelationDef[] {
+    const results: RelationDef[] = [];
+    for (const [, entries] of this.resolvedRelations) {
+      for (const entry of entries) {
+        if (
+          entry.def.sourceTypes.includes(typeName) ||
+          entry.def.targetTypes.includes(typeName)
+        ) {
+          results.push(entry.def);
+        }
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Get a specific relation definition by name.
+   */
+  getRelationDef(name: string): RelationDef | undefined {
+    const entries = this.resolvedRelations.get(name);
+    return entries?.[0]?.def;
+  }
+
+  /**
+   * List all known relation names.
+   */
+  listRelationNames(): string[] {
+    return [...this.resolvedRelations.keys()];
+  }
+
+  /**
+   * Check if an entity type is known to any registered ontology.
+   */
+  hasEntityType(typeName: string): boolean {
+    return this.resolvedEntities.has(typeName);
+  }
+
+  /**
+   * Get the required attributes for an entity type.
+   */
+  getRequiredAttributes(typeName: string): AttributeDef[] {
+    const def = this.getEntityDef(typeName);
+    if (!def) return [];
+    return def.attributes.filter((a) => a.required);
+  }
+
+  // -------------------------------------------------------------------------
+  // Resolution (inheritance)
+  // -------------------------------------------------------------------------
+
+  private _resolve(schema: OntologySchema): void {
+    // Register entities
+    for (const entity of schema.entities) {
+      const resolved = this._resolveEntity(entity, schema);
+      this.resolvedEntities.set(entity.name, {
+        def: resolved,
+        ontologyId: schema.id,
+      });
+    }
+
+    // Register relations
+    for (const relation of schema.relations) {
+      const existing = this.resolvedRelations.get(relation.name) ?? [];
+      existing.push({ def: relation, ontologyId: schema.id });
+      this.resolvedRelations.set(relation.name, existing);
+    }
+  }
+
+  private _resolveEntity(entity: EntityDef, schema: OntologySchema): EntityDef {
+    if (!entity.extends) return entity;
+
+    // Find parent — check current schema first, then all registered
+    let parent = schema.entities.find((e) => e.name === entity.extends);
+    if (!parent) {
+      const resolved = this.resolvedEntities.get(entity.extends!);
+      parent = resolved?.def;
+    }
+
+    if (!parent) {
+      throw new Error(
+        `Entity "${entity.name}" extends "${entity.extends}" which is not defined.`,
+      );
+    }
+
+    // Resolve parent first (recursive)
+    const resolvedParent = this._resolveEntity(parent, schema);
+
+    // Merge: child attributes override parent attributes with same name
+    const childAttrNames = new Set(entity.attributes.map((a) => a.name));
+    const mergedAttrs = [
+      ...resolvedParent.attributes.filter((a) => !childAttrNames.has(a.name)),
+      ...entity.attributes,
+    ];
+
+    return {
+      ...entity,
+      attributes: mergedAttrs,
+    };
+  }
+}

package/src/core/ontology/types.ts

@@ -0,0 +1,124 @@
+/**
+ * Ontology Type System — Declarative schemas for entity types, attributes,
+ * constraints, and relationships.
+ *
+ * Ontologies define the "shape" of entities in the graph. They are used for:
+ *   - Schema validation (reject mutations that violate constraints)
+ *   - Documentation (describe what entity types exist and their attributes)
+ *   - Code generation and tooling (auto-complete, type checking)
+ *
+ * @module trellis/core/ontology
+ */
+
+import type { Atom } from '../store/eav-store.js';
+
+// ---------------------------------------------------------------------------
+// Attribute types
+// ---------------------------------------------------------------------------
+
+export type AttrType = 'string' | 'number' | 'boolean' | 'date' | 'ref' | 'any';
+
+export interface AttributeDef {
+  /** Attribute name (fact key). */
+  name: string;
+  /** Expected value type. */
+  type: AttrType;
+  /** Human-readable description. */
+  description?: string;
+  /** Whether this attribute is required on entity creation. */
+  required?: boolean;
+  /** Whether only one value is allowed (default: true). */
+  unique?: boolean;
+  /** Default value if not provided. */
+  default?: Atom;
+  /** Allowed values (enum constraint). */
+  enum?: Atom[];
+  /** Regex pattern for string values. */
+  pattern?: string;
+  /** Minimum value (for numbers) or min length (for strings). */
+  min?: number;
+  /** Maximum value (for numbers) or max length (for strings). */
+  max?: number;
+  /** If type is 'ref', the target entity type(s) this can reference. */
+  refTypes?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Relation types
+// ---------------------------------------------------------------------------
+
+export interface RelationDef {
+  /** Relation attribute name (link key). */
+  name: string;
+  /** Human-readable description. */
+  description?: string;
+  /** Source entity type(s) that can have this relation. */
+  sourceTypes: string[];
+  /** Target entity type(s) this relation can point to. */
+  targetTypes: string[];
+  /** Cardinality: 'one' = at most one target, 'many' = unlimited. */
+  cardinality?: 'one' | 'many';
+  /** Whether this relation is required. */
+  required?: boolean;
+  /** Inverse relation name (auto-created on the target). */
+  inverse?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Entity type definitions
+// ---------------------------------------------------------------------------
+
+export interface EntityDef {
+  /** Entity type name (e.g. "Project", "User", "Agent"). */
+  name: string;
+  /** Human-readable description. */
+  description?: string;
+  /** Attribute definitions for this entity type. */
+  attributes: AttributeDef[];
+  /** Whether this entity type is abstract (cannot be instantiated directly). */
+  abstract?: boolean;
+  /** Parent entity type (for inheritance). */
+  extends?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Ontology Schema
+// ---------------------------------------------------------------------------
+
+export interface OntologySchema {
+  /** Unique ontology identifier (e.g. "trellis:project", "trellis:team"). */
+  id: string;
+  /** Human-readable name. */
+  name: string;
+  /** Semantic version. */
+  version: string;
+  /** Human-readable description. */
+  description?: string;
+  /** Entity type definitions. */
+  entities: EntityDef[];
+  /** Relation definitions. */
+  relations: RelationDef[];
+}
+
+// ---------------------------------------------------------------------------
+// Validation result
+// ---------------------------------------------------------------------------
+
+export interface ValidationError {
+  /** Entity ID that failed validation. */
+  entityId: string;
+  /** Entity type. */
+  entityType: string;
+  /** Which attribute or relation failed. */
+  field: string;
+  /** Error message. */
+  message: string;
+  /** Severity: 'error' = hard failure, 'warning' = advisory. */
+  severity: 'error' | 'warning';
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationError[];
+}