brainy/src/types/graphTypes.ts

/**
 * Graph Types - Standardized Noun and Verb Type System
 * 
 * This module defines a comprehensive, standardized set of noun and verb types
 * that can be used to model any kind of graph, semantic network, or data model.
 * 
 * ## Purpose and Design Philosophy
 * 
 * The type system is designed to be:
 * - **Universal**: Capable of representing any domain or use case
 * - **Hierarchical**: Organized into logical categories for easy navigation
 * - **Extensible**: Additional metadata can be attached to any entity or relationship
 * - **Semantic**: Types carry meaning that can be used for reasoning and inference
 * 
 * ## Noun Types (Entities)
 * 
 * Noun types represent entities in the graph and are organized into categories:
 * 
 * ### Core Entity Types
 * - **Person**: Human entities and individuals
 * - **Organization**: Formal organizations, companies, institutions
 * - **Location**: Geographic locations, places, addresses
 * - **Thing**: Physical objects and tangible items
 * - **Concept**: Abstract ideas, concepts, and intangible entities
 * - **Event**: Occurrences with time and place dimensions
 * 
 * ### Digital/Content Types
 * - **Document**: Text-based files and documents
 * - **Media**: Non-text media files (images, videos, audio)
 * - **File**: Generic digital files
 * - **Message**: Communication content
 * - **Content**: Generic content that doesn't fit other categories
 * 
 * ### Collection Types
 * - **Collection**: Generic groupings of items
 * - **Dataset**: Structured collections of data
 * 
 * ### Business/Application Types
 * - **Product**: Commercial products and offerings
 * - **Service**: Services and offerings
 * - **User**: User accounts and profiles
 * - **Task**: Actions, todos, and workflow items
 * - **Project**: Organized initiatives with goals and timelines
 * 
 * ### Descriptive Types
 * - **Process**: Workflows, procedures, and sequences
 * - **State**: States, conditions, or statuses
 * - **Role**: Roles, positions, or responsibilities
 * - **Topic**: Subjects or themes
 * - **Language**: Languages or linguistic entities
 * - **Currency**: Currencies and monetary units
 * - **Measurement**: Measurements, metrics, or quantities
 * 
 * ## Verb Types (Relationships)
 * 
 * Verb types represent relationships between entities and are organized into categories:
 * 
 * ### Core Relationship Types
 * - **RelatedTo**: Generic relationship (default fallback)
 * - **Contains**: Containment relationship
 * - **PartOf**: Part-whole relationship
 * - **LocatedAt**: Spatial relationship
 * - **References**: Reference or citation relationship
 * 
 * ### Temporal/Causal Types
 * - **Precedes/Succeeds**: Temporal sequence relationships
 * - **Causes**: Causal relationships
 * - **DependsOn**: Dependency relationships
 * - **Requires**: Necessity relationships
 * 
 * ### Creation/Transformation Types
 * - **Creates**: Creation relationships
 * - **Transforms**: Transformation relationships
 * - **Becomes**: State change relationships
 * - **Modifies**: Modification relationships
 * - **Consumes**: Consumption relationships
 * 
 * ### Ownership/Attribution Types
 * - **Owns**: Ownership relationships
 * - **AttributedTo**: Attribution or authorship
 * - **CreatedBy**: Creation attribution
 * - **BelongsTo**: Belonging relationships
 * 
 * ### Social/Organizational Types
 * - **MemberOf**: Membership or affiliation
 * - **WorksWith**: Professional relationships
 * - **FriendOf**: Friendship relationships
 * - **Follows**: Following relationships
 * - **Likes**: Liking relationships
 * - **ReportsTo**: Reporting relationships
 * - **Supervises**: Supervisory relationships
 * - **Mentors**: Mentorship relationships
 * - **Communicates**: Communication relationships
 * 
 * ### Descriptive/Functional Types
 * - **Describes**: Descriptive relationships
 * - **Defines**: Definition relationships
 * - **Categorizes**: Categorization relationships
 * - **Measures**: Measurement relationships
 * - **Evaluates**: Evaluation or assessment relationships
 * - **Uses**: Utilization relationships
 * - **Implements**: Implementation relationships
 * - **Extends**: Extension relationships
 * 
 * ## Usage with Additional Metadata
 * 
 * While the type system provides a standardized vocabulary, additional metadata
 * can be attached to any entity or relationship to capture domain-specific
 * information:
 * 
 * ```typescript
 * const person: GraphNoun = {
 *   id: 'person-123',
 *   noun: NounType.Person,
 *   data: {
 *     name: 'John Doe',
 *     age: 30,
 *     profession: 'Engineer'
 *   }
 * }
 * 
 * const worksFor: GraphVerb = {
 *   id: 'verb-456',
 *   source: 'person-123',
 *   target: 'org-789',
 *   verb: VerbType.MemberOf,
 *   data: {
 *     role: 'Senior Engineer',
 *     startDate: '2020-01-01',
 *     department: 'Engineering'
 *   }
 * }
 * ```
 * 
 * ## Modeling Different Graph Types
 * 
 * This type system can model various graph structures:
 * 
 * ### Knowledge Graphs
 * Use Person, Organization, Location, Concept entities with semantic relationships
 * like AttributedTo, LocatedAt, RelatedTo
 * 
 * ### Social Networks
 * Use Person, User entities with social relationships like FriendOf, Follows,
 * WorksWith, Communicates
 * 
 * ### Content Networks
 * Use Document, Media, Content entities with relationships like References,
 * CreatedBy, Contains, Categorizes
 * 
 * ### Business Process Models
 * Use Task, Process, Role entities with relationships like Precedes, Requires,
 * DependsOn, Transforms
 * 
 * ### Organizational Charts
 * Use Person, Role, Organization entities with relationships like ReportsTo,
 * Supervises, MemberOf
 * 
 * The flexibility of this system allows it to represent any domain while
 * maintaining semantic consistency and enabling powerful graph operations
 * and reasoning capabilities.
 */

// Common metadata types
/**
 * Represents a high-precision timestamp with seconds and nanoseconds
 * Used for tracking creation and update times of graph elements
 */
interface Timestamp {
  seconds: number
  nanoseconds: number
}

/**
 * Metadata about the creator/source of a graph noun
 * Tracks which augmentation and model created the element
 */
interface CreatorMetadata {
  augmentation: string // Name of the augmentation that created this element
  version: string // Version of the augmentation
}

/**
 * Base interface for nodes (nouns) in the graph
 * Represents entities like people, places, things, etc.
 */
export interface GraphNoun {
  id: string // Unique identifier for the noun
  createdBy: CreatorMetadata // Information about what created this noun
  noun: NounType // Type classification of the noun
  createdAt: Timestamp // When the noun was created
  updatedAt: Timestamp // When the noun was last updated
  label?: string // Optional descriptive label
  data?: Record<string, any> // Additional flexible data storage
  embeddedVerbs?: EmbeddedGraphVerb[] // Optional embedded relationships
  embedding?: number[] // Vector representation of the noun
  confidence?: number // Confidence in entity type classification (0-1)
  weight?: number // Importance/salience of the entity
}

/**
 * Base interface for verbs in the graph
 * Represents relationships between nouns
 */
export interface GraphVerb {
  id: string // Unique identifier for the verb
  source: string // ID of the source noun
  target: string // ID of the target noun
  label?: string // Optional descriptive label
  verb: VerbType // Type of relationship
  createdAt: Timestamp // When the verb was created
  updatedAt: Timestamp // When the verb was last updated
  createdBy: CreatorMetadata // Information about what created this verb
  service?: string // Multi-tenancy support - which service created this verb
  data?: Record<string, any> // Additional flexible data storage
  embedding?: number[] // Vector representation of the relationship
  confidence?: number // Confidence score (0-1)
  weight?: number // Strength/importance of the relationship
}

/**
 * Version of GraphVerb for embedded relationships
 * Used when the source is implicit from the parent document
 */
export type EmbeddedGraphVerb = Omit<GraphVerb, 'source'>

// Proper Noun interfaces - extend GraphNoun with specific noun types

/**
 * Represents a person entity in the graph
 */
export interface Person extends GraphNoun {
  noun: typeof NounType.Person
}

/**
 * Represents a physical location in the graph
 */
export interface Location extends GraphNoun {
  noun: typeof NounType.Location
}

/**
 * Represents a physical or virtual object in the graph
 */
export interface Thing extends GraphNoun {
  noun: typeof NounType.Thing
}

/**
 * Represents an event or occurrence in the graph
 */
export interface Event extends GraphNoun {
  noun: typeof NounType.Event
}

/**
 * Represents an abstract concept or idea in the graph
 */
export interface Concept extends GraphNoun {
  noun: typeof NounType.Concept
}

export interface Collection extends GraphNoun {
  noun: typeof NounType.Collection
}

export interface Organization extends GraphNoun {
  noun: typeof NounType.Organization
}

export interface Document extends GraphNoun {
  noun: typeof NounType.Document
}

export interface Media extends GraphNoun {
  noun: typeof NounType.Media
}

export interface File extends GraphNoun {
  noun: typeof NounType.File
}

export interface Message extends GraphNoun {
  noun: typeof NounType.Message
}

export interface Dataset extends GraphNoun {
  noun: typeof NounType.Dataset
}

export interface Product extends GraphNoun {
  noun: typeof NounType.Product
}

export interface Service extends GraphNoun {
  noun: typeof NounType.Service
}

export interface User extends GraphNoun {
  noun: typeof NounType.User
}

export interface Task extends GraphNoun {
  noun: typeof NounType.Task
}

export interface Project extends GraphNoun {
  noun: typeof NounType.Project
}

export interface Process extends GraphNoun {
  noun: typeof NounType.Process
}

export interface State extends GraphNoun {
  noun: typeof NounType.State
}

export interface Role extends GraphNoun {
  noun: typeof NounType.Role
}

export interface Topic extends GraphNoun {
  noun: typeof NounType.Topic
}

export interface Language extends GraphNoun {
  noun: typeof NounType.Language
}

export interface Currency extends GraphNoun {
  noun: typeof NounType.Currency
}

export interface Measurement extends GraphNoun {
  noun: typeof NounType.Measurement
}

/**
 * Represents content (text, media, etc.) in the graph
 */
export interface Content extends GraphNoun {
  noun: typeof NounType.Content
}

/**
 * Represents a scientific hypothesis or theory in the graph
 */
export interface Hypothesis extends GraphNoun {
  noun: typeof NounType.Hypothesis
}

/**
 * Represents an experiment, study, or research trial in the graph
 */
export interface Experiment extends GraphNoun {
  noun: typeof NounType.Experiment
}

/**
 * Represents a legal contract or agreement in the graph
 */
export interface Contract extends GraphNoun {
  noun: typeof NounType.Contract
}

/**
 * Represents a regulation, law, or compliance requirement in the graph
 */
export interface Regulation extends GraphNoun {
  noun: typeof NounType.Regulation
}

/**
 * Represents an interface, API, or protocol specification in the graph
 */
export interface Interface extends GraphNoun {
  noun: typeof NounType.Interface
}

/**
 * Represents a computational or infrastructure resource in the graph
 */
export interface Resource extends GraphNoun {
  noun: typeof NounType.Resource
}

/**
 * Defines valid noun types for graph entities
 * Used for categorizing different types of nodes
 */

export const NounType = {
  // Core Entity Types
  Person: 'person', // Human entities
  Organization: 'organization', // Formal organizations (companies, institutions, etc.)
  Location: 'location', // Geographic locations (merges previous Place and Location)
  Thing: 'thing', // Physical objects (generic items/entities should use this)
  Concept: 'concept', // Abstract ideas, concepts, and intangible entities
  Event: 'event', // Occurrences with time and place

  // Digital/Content Types
  Document: 'document', // Text-based files and documents (reports, articles, etc.)
  Media: 'media', // Non-text media files (images, videos, audio)
  File: 'file', // Generic digital files (merges aspects of Digital with file-specific focus)
  Message: 'message', // Communication content (emails, chat messages, posts)
  Content: 'content', // Generic content that doesn't fit other categories

  // Collection Types
  Collection: 'collection', // Generic grouping of items (merges Group, List, and Category)
  Dataset: 'dataset', // Structured collections of data

  // Business/Application Types  
  Product: 'product', // Commercial products and offerings
  Service: 'service', // Services and offerings
  User: 'user', // User accounts and profiles
  Task: 'task', // Actions, todos, and workflow items
  Project: 'project', // Organized initiatives with goals and timelines

  // Descriptive Types
  Process: 'process', // Workflows, procedures, and sequences
  State: 'state', // States, conditions, or statuses
  Role: 'role', // Roles, positions, or responsibilities
  Topic: 'topic', // Subjects or themes
  Language: 'language', // Languages or linguistic entities
  Currency: 'currency', // Currencies and monetary units
  Measurement: 'measurement', // Measurements, metrics, or quantities

  // Scientific/Research Types (100% Coverage)
  Hypothesis: 'hypothesis', // Scientific theories, research hypotheses, propositions
  Experiment: 'experiment', // Controlled studies, trials, tests, research methodologies

  // Legal/Regulatory Types (100% Coverage)
  Contract: 'contract', // Legal agreements, terms, policies, binding documents
  Regulation: 'regulation', // Laws, rules, compliance requirements, standards

  // Technical Infrastructure Types (100% Coverage)
  Interface: 'interface', // APIs, protocols, contracts, specifications, endpoints
  Resource: 'resource' // Compute resources, bandwidth, storage, infrastructure assets
} as const
export type NounType = (typeof NounType)[keyof typeof NounType]

/**
 * Defines valid verb types for relationships
 * Used for categorizing different types of connections
 */
export const VerbType = {
  // Core Relationship Types
  RelatedTo: 'relatedTo', // Generic relationship (default fallback)
  Contains: 'contains', // Containment relationship (parent contains child)
  PartOf: 'partOf', // Part-whole relationship (child is part of parent)
  LocatedAt: 'locatedAt', // Spatial relationship
  References: 'references', // Reference or citation relationship

  // Temporal/Causal Types
  Precedes: 'precedes', // Temporal sequence (comes before)
  Succeeds: 'succeeds', // Temporal sequence (comes after)
  Causes: 'causes', // Causal relationship (merges Influences and Causes)
  DependsOn: 'dependsOn', // Dependency relationship
  Requires: 'requires', // Necessity relationship (new)

  // Creation/Transformation Types
  Creates: 'creates', // Creation relationship (merges Created and Produces)
  Transforms: 'transforms', // Transformation relationship
  Becomes: 'becomes', // State change relationship
  Modifies: 'modifies', // Modification relationship
  Consumes: 'consumes', // Consumption relationship

  // Ownership/Attribution Types
  Owns: 'owns', // Ownership relationship (merges Controls and Owns)
  AttributedTo: 'attributedTo', // Attribution or authorship
  CreatedBy: 'createdBy', // Creation attribution (new, distinct from Creates)
  BelongsTo: 'belongsTo', // Belonging relationship (new)

  // Social/Organizational Types
  MemberOf: 'memberOf', // Membership or affiliation
  WorksWith: 'worksWith', // Professional relationship
  FriendOf: 'friendOf', // Friendship relationship
  Follows: 'follows', // Following relationship
  Likes: 'likes', // Liking relationship
  ReportsTo: 'reportsTo', // Reporting relationship
  Supervises: 'supervises', // Supervisory relationship
  Mentors: 'mentors', // Mentorship relationship
  Communicates: 'communicates', // Communication relationship (merges Communicates and Collaborates)

  // Descriptive/Functional Types
  Describes: 'describes', // Descriptive relationship
  Defines: 'defines', // Definition relationship
  Categorizes: 'categorizes', // Categorization relationship
  Measures: 'measures', // Measurement relationship
  Evaluates: 'evaluates', // Evaluation or assessment relationship
  Uses: 'uses', // Utilization relationship (new)
  Implements: 'implements', // Implementation relationship
  Extends: 'extends', // Extension relationship (enhancement, building upon)

  // Enhanced Relationships (100% Coverage)
  Inherits: 'inherits', // True inheritance relationship (class inheritance, legacy)
  Conflicts: 'conflicts', // Contradictions, incompatibilities, opposing forces
  Synchronizes: 'synchronizes', // Coordination, timing, synchronized operations
  Competes: 'competes' // Competition, rivalry, competing relationships
} as const
export type VerbType = (typeof VerbType)[keyof typeof VerbType]

/**
 * Noun type enum for O(1) lookups and type safety
 * Maps each noun type to a unique index (0-30)
 * Used for fixed-size array operations and bitmap indices
 */
export enum NounTypeEnum {
  person = 0,
  organization = 1,
  location = 2,
  thing = 3,
  concept = 4,
  event = 5,
  document = 6,
  media = 7,
  file = 8,
  message = 9,
  content = 10,
  collection = 11,
  dataset = 12,
  product = 13,
  service = 14,
  user = 15,
  task = 16,
  project = 17,
  process = 18,
  state = 19,
  role = 20,
  topic = 21,
  language = 22,
  currency = 23,
  measurement = 24,
  hypothesis = 25,
  experiment = 26,
  contract = 27,
  regulation = 28,
  interface = 29,
  resource = 30
}

/**
 * Verb type enum for O(1) lookups and type safety
 * Maps each verb type to a unique index (0-39)
 * Used for fixed-size array operations and bitmap indices
 */
export enum VerbTypeEnum {
  relatedTo = 0,
  contains = 1,
  partOf = 2,
  locatedAt = 3,
  references = 4,
  precedes = 5,
  succeeds = 6,
  causes = 7,
  dependsOn = 8,
  requires = 9,
  creates = 10,
  transforms = 11,
  becomes = 12,
  modifies = 13,
  consumes = 14,
  owns = 15,
  attributedTo = 16,
  createdBy = 17,
  belongsTo = 18,
  memberOf = 19,
  worksWith = 20,
  friendOf = 21,
  follows = 22,
  likes = 23,
  reportsTo = 24,
  supervises = 25,
  mentors = 26,
  communicates = 27,
  describes = 28,
  defines = 29,
  categorizes = 30,
  measures = 31,
  evaluates = 32,
  uses = 33,
  implements = 34,
  extends = 35,
  inherits = 36,
  conflicts = 37,
  synchronizes = 38,
  competes = 39
}

/**
 * Total number of noun types (for array allocations)
 */
export const NOUN_TYPE_COUNT = 31

/**
 * Total number of verb types (for array allocations)
 */
export const VERB_TYPE_COUNT = 40

/**
 * Type utilities for O(1) conversions between string types and numeric indices
 * Enables efficient fixed-size array operations and bitmap indexing
 */
export const TypeUtils = {
  /**
   * Get numeric index for a noun type
   * @param type - NounType string (e.g., 'person')
   * @returns Numeric index (0-30)
   */
  getNounIndex: (type: NounType): number => {
    return NounTypeEnum[type as keyof typeof NounTypeEnum]
  },

  /**
   * Get numeric index for a verb type
   * @param type - VerbType string (e.g., 'relatedTo')
   * @returns Numeric index (0-39)
   */
  getVerbIndex: (type: VerbType): number => {
    return VerbTypeEnum[type as keyof typeof VerbTypeEnum]
  },

  /**
   * Get noun type string from numeric index
   * @param index - Numeric index (0-30)
   * @returns NounType string or 'thing' as default
   */
  getNounFromIndex: (index: number): NounType => {
    const entry = Object.entries(NounTypeEnum).find(([_, idx]) => idx === index)
    return entry ? (entry[0] as NounType) : NounType.Thing
  },

  /**
   * Get verb type string from numeric index
   * @param index - Numeric index (0-39)
   * @returns VerbType string or 'relatedTo' as default
   */
  getVerbFromIndex: (index: number): VerbType => {
    const entry = Object.entries(VerbTypeEnum).find(([_, idx]) => idx === index)
    return entry ? (entry[0] as VerbType) : VerbType.RelatedTo
  }
}

/**
 * Type-specific metadata for optimization hints
 * Provides per-type configuration for bloom filters, chunking, and indexing
 */
export const TypeMetadata: Record<
  NounType,
  {
    expectedFields: number // Average number of metadata fields for this type
    bloomBits: number // Bloom filter size in bits (128 or 256)
    avgChunkSize: number // Average entities per index chunk
  }
> = {
  person: { expectedFields: 10, bloomBits: 256, avgChunkSize: 100 },
  organization: { expectedFields: 12, bloomBits: 256, avgChunkSize: 80 },
  document: { expectedFields: 8, bloomBits: 256, avgChunkSize: 100 },
  event: { expectedFields: 6, bloomBits: 128, avgChunkSize: 50 },
  location: { expectedFields: 7, bloomBits: 128, avgChunkSize: 60 },
  thing: { expectedFields: 5, bloomBits: 128, avgChunkSize: 50 },
  concept: { expectedFields: 4, bloomBits: 128, avgChunkSize: 40 },
  media: { expectedFields: 6, bloomBits: 128, avgChunkSize: 50 },
  file: { expectedFields: 5, bloomBits: 128, avgChunkSize: 50 },
  message: { expectedFields: 7, bloomBits: 128, avgChunkSize: 60 },
  content: { expectedFields: 5, bloomBits: 128, avgChunkSize: 50 },
  collection: { expectedFields: 4, bloomBits: 128, avgChunkSize: 40 },
  dataset: { expectedFields: 6, bloomBits: 128, avgChunkSize: 50 },
  product: { expectedFields: 8, bloomBits: 256, avgChunkSize: 70 },
  service: { expectedFields: 7, bloomBits: 128, avgChunkSize: 60 },
  user: { expectedFields: 9, bloomBits: 256, avgChunkSize: 80 },
  task: { expectedFields: 6, bloomBits: 128, avgChunkSize: 50 },
  project: { expectedFields: 8, bloomBits: 256, avgChunkSize: 70 },
  process: { expectedFields: 5, bloomBits: 128, avgChunkSize: 50 },
  state: { expectedFields: 3, bloomBits: 128, avgChunkSize: 30 },
  role: { expectedFields: 4, bloomBits: 128, avgChunkSize: 40 },
  topic: { expectedFields: 4, bloomBits: 128, avgChunkSize: 40 },
  language: { expectedFields: 3, bloomBits: 128, avgChunkSize: 30 },
  currency: { expectedFields: 3, bloomBits: 128, avgChunkSize: 30 },
  measurement: { expectedFields: 4, bloomBits: 128, avgChunkSize: 40 },
  hypothesis: { expectedFields: 6, bloomBits: 128, avgChunkSize: 50 },
  experiment: { expectedFields: 7, bloomBits: 128, avgChunkSize: 60 },
  contract: { expectedFields: 8, bloomBits: 256, avgChunkSize: 70 },
  regulation: { expectedFields: 6, bloomBits: 128, avgChunkSize: 50 },
  interface: { expectedFields: 5, bloomBits: 128, avgChunkSize: 50 },
  resource: { expectedFields: 5, bloomBits: 128, avgChunkSize: 50 }
}