v1.1.0: pooled runtime, 959 tests, production hardening (0 squash)

2025-08-15 10:00:00 -07:00
commit 92deb689cd
321 changed files with 79170 additions and 0 deletions
@@ -0,0 +1,221 @@
+/**
+ * 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(),
+  }
+}