Imhotep/packages/imhotep-core/src/ir.ts

/**
 * Semantic IR and Execution IR definitions for Imhotep.
 *
 * Semantic IR:
 *   Normalized graph of explicit obligations, frames, selectors, states,
 *   environments, and tolerances. Stored as tables keyed by stable id.
 *
 * Execution IR:
 *   Flattened, data-oriented arrays optimized for bulk evaluation against
 *   a geometry world. This is the hot-path representation.
 */

import type {
  ImhotepId,
  SourceOrigin,
  LengthLiteral,
  Environment,
  StateSnapshot,
  TimelineSnapshot,
  Frame,
  Subject,
} from './types.js'

// ---------------------------------------------------------------------------
// Semantic IR Tables
// ---------------------------------------------------------------------------

export interface SemanticIr {
  subjects: Map<ImhotepId, SemanticSubject>
  frames: Map<ImhotepId, SemanticFrame>
  states: Map<ImhotepId, SemanticState>
  timelines: Map<ImhotepId, SemanticTimeline>
  tolerances: Map<ImhotepId, SemanticTolerance>
  envGuards: Map<ImhotepId, SemanticEnvGuard>
  clauses: Map<ImhotepId, SemanticClause>
  groups: Map<ImhotepId, SemanticGroup>
  diagnosticMetadata: Map<ImhotepId, SemanticDiagnosticMeta>
}

export interface SemanticSubject {
  id: ImhotepId
  selector: string
  kind: Subject['kind']
  origin: SourceOrigin
}

export interface SemanticFrame {
  id: ImhotepId
  kind: Frame['kind']
  selector?: string
  name?: string
  originX: number
  originY: number
  writingMode: Frame['writingMode']
  origin: SourceOrigin
}

export interface SemanticState {
  id: ImhotepId
  kind: StateSnapshot['kind']
  name?: string
  origin: SourceOrigin
}

export interface SemanticTimeline {
  id: ImhotepId
  mode: TimelineSnapshot['mode']
  samples?: number[]
  origin: SourceOrigin
}

export interface SemanticTolerance {
  id: ImhotepId
  value: number
  unit: 'jnd' | 'px'
  origin: SourceOrigin
}

export interface SemanticEnvGuard {
  id: ImhotepId
  expression: string
  normalizedCases: Environment[]
  origin: SourceOrigin
}

export interface SemanticClause {
  id: ImhotepId
  origin: SourceOrigin
  subjectRef: ImhotepId
  referenceRef?: ImhotepId
  relation: string
  frameRef: ImhotepId
  stateRef: ImhotepId
  timelineRef: ImhotepId
  envGuardRef: ImhotepId
  toleranceRef: ImhotepId
  bounds: {
    minGap?: LengthLiteral
    maxGap?: LengthLiteral
  }
}

export interface SemanticGroup {
  id: ImhotepId
  origin: SourceOrigin
  operator: 'and' | 'or' | 'not' | 'quantifier'
  quantifier?: {
    kind: string
    count?: number
  }
  clauseRefs: ImhotepId[]
  groupRefs?: ImhotepId[]
}

export interface SemanticDiagnosticMeta {
  id: ImhotepId
  clauseRef?: ImhotepId
  messageTemplate: string
  origin: SourceOrigin
}

// ---------------------------------------------------------------------------
// Execution IR Tables
// ---------------------------------------------------------------------------

/**
 * Execution IR stores clause data in parallel typed arrays for bulk
 * evaluation. Every array is indexed by clauseIndex.
 */
export interface ExecutionIr {
  clauseCount: number

  // Clause classification and cross-references (all Uint32Array)
  clauseType: Uint16Array
  clauseSubject: Uint32Array
  clauseReference: Uint32Array
  clauseFrame: Uint32Array
  clauseState: Uint32Array
  clauseTimeline: Uint32Array
  clauseTolerance: Uint32Array
  clauseEnvGuard: Uint32Array

  // Numeric bounds (Float64Array)
  clauseArg0: Float64Array
  clauseArg1: Float64Array

  // Flags and origin (Uint32Array)
  clauseFlags: Uint32Array
  clauseOrigin: Uint32Array
}

export interface ExecutionIrBuilder {
  addClause(descriptor: ExecutionClauseDescriptor): number
  build(): ExecutionIr
}

export interface ExecutionClauseDescriptor {
  clauseType: number
  subjectIndex: number
  referenceIndex: number
  frameIndex: number
  stateIndex: number
  timelineIndex: number
  toleranceIndex: number
  envGuardIndex: number
  arg0: number
  arg1: number
  flags: number
  originIndex: number
}

// ---------------------------------------------------------------------------
// IR Lowering Pipeline Stages
// ---------------------------------------------------------------------------

export type LoweringStage =
  | 'parse'
  | 'validate'
  | 'normalize'
  | 'resolve-defaults'
  | 'compile'
  | 'derive-facts'

export interface LoweringPipeline {
  stages: LoweringStage[]
  currentStage: LoweringStage
  diagnostics: unknown[]
}

// ---------------------------------------------------------------------------
// Clause Family Registry
// ---------------------------------------------------------------------------

export interface ClauseFamilyDescriptor {
  clauseKind: string
  version: number
  requiredFacts: string[]
}

export interface ClauseFamilyRegistry {
  register(descriptor: ClauseFamilyDescriptor): void
  lookup(clauseKind: string): ClauseFamilyDescriptor | undefined
}

// ---------------------------------------------------------------------------
// Helper: Create empty Semantic IR
// ---------------------------------------------------------------------------

export function createEmptySemanticIr(): SemanticIr {
  return {
    subjects: new Map(),
    frames: new Map(),
    states: new Map(),
    timelines: new Map(),
    tolerances: new Map(),
    envGuards: new Map(),
    clauses: new Map(),
    groups: new Map(),
    diagnosticMetadata: new Map(),
  }
}