trellis 2.0.13 → 2.1.2

package/src/core/ontology/builtins.ts

@@ -1,248 +0,0 @@
-/**
- * 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

@@ -1,34 +0,0 @@
-/**
- * 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

@@ -1,209 +0,0 @@
-/**
- * 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

@@ -1,124 +0,0 @@
-/**
- * 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[];
-}