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

/**
 * Extractor and solver contract interfaces for Imhotep.
 *
 * The extractor is a compiler target: it consumes a fact request plan and
 * produces a geometry world. The solver operates on explicit clause families
 * with declared fact requirements and deterministic outputs.
 */

import type {
  ImhotepId,
  Environment,
  StateSnapshot,
  TimelineSnapshot,
  Subject,
  ClauseResult,
  GroupResult,
  Proof,
} from './types.js'

import type { GeometryWorld, FactRequestPlan } from './world.js'

import type { ExtractionTrace, EvaluationTrace, Diagnostic } from './diagnostics.js'

import type { SceneTarget, RenderCase } from './scene-target.js'

export type { SceneTarget, RenderCase }

// ---------------------------------------------------------------------------
// Extractor Request
// ---------------------------------------------------------------------------

export interface ExtractorRequest {
  requestId: ImhotepId
  sceneTarget: SceneTarget
  env: Environment
  statePlan: {
    snapshots: string[]
  }
  timelinePlan: {
    mode: string
  }
  subjects: Array<{
    id: ImhotepId
    selector: string
  }>
  requiredFacts: FactRequestPlan
}

// ---------------------------------------------------------------------------
// Extractor Response
// ---------------------------------------------------------------------------

export interface ExtractorResponse {
  requestId: ImhotepId
  status: 'ok' | 'partial' | 'error'
  snapshots: GeometryWorld[]
  diagnostics: Diagnostic[]
  extractionTrace: ExtractionTrace
}

// ---------------------------------------------------------------------------
// Extractor Contract
// ---------------------------------------------------------------------------

export interface ExtractorContract {
  /**
   * Consume a fact request plan and produce a geometry world.
   */
  extract(request: ExtractorRequest, runtime: unknown): Promise<ExtractorResponse>
}

// ---------------------------------------------------------------------------
// Extractor Adapter Interface
// ---------------------------------------------------------------------------

export interface ExtractorAdapter {
  name: string
  version: string
  supportedFacts: string[]
  execute(request: ExtractorRequest): Promise<AdapterExtractionResult>
}

export interface AdapterExtractionResult {
  status: 'ok' | 'partial' | 'error'
  world: GeometryWorld
  diagnostics: Diagnostic[]
  trace: ExtractionTrace
}

// ---------------------------------------------------------------------------
// Solver Clause Contract
// ---------------------------------------------------------------------------

export interface SolverClauseContract {
  /**
   * Descriptor declaring what facts this clause family requires.
   */
  descriptor: ClauseDescriptor

  /**
   * Evaluate a single clause against the geometry world.
   */
  evaluate(world: GeometryWorld, clauseId: ImhotepId, traceBuilder: TraceBuilder): ClauseResult
}

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

export interface TraceBuilder {
  addStep(step: unknown): void
  build(): unknown[]
}

// ---------------------------------------------------------------------------
// Evaluation Result
// ---------------------------------------------------------------------------

export interface EvaluationResult {
  clauseResults: ClauseResult[]
  groupResults: GroupResult[]
  proofs: Proof[]
  diagnostics: Diagnostic[]
  trace: EvaluationTrace
}

// ---------------------------------------------------------------------------
// Solver Evaluation Contract
// ---------------------------------------------------------------------------

export interface SolverContract {
  /**
   * Evaluate compiled execution IR against a set of geometry worlds.
   */
  evaluate(executionIr: unknown, worldSet: GeometryWorld[]): EvaluationResult
}

// ---------------------------------------------------------------------------
// Compiler Contract
// ---------------------------------------------------------------------------

export interface CompilerContract {
  compile(input: string | unknown): CompilerOutput
}

export interface CompilerOutput {
  ast: unknown
  semanticIr: unknown
  executionIr: unknown
  diagnostics: Diagnostic[]
}

// ---------------------------------------------------------------------------
// Reporter Contract
// ---------------------------------------------------------------------------

export interface ReporterContract {
  report(evaluationResult: EvaluationResult, options: ReporterOptions): ReporterOutput
}

export interface ReporterOptions {
  format: 'text' | 'json' | 'html'
  includeTrace: boolean
  includeProofs: boolean
}

export interface ReporterOutput {
  text: string
  json: string
  overlays: unknown[]
}

// ---------------------------------------------------------------------------
// Fact Requirement Analysis
// ---------------------------------------------------------------------------

export interface FactRequirementAnalysis {
  requiredFacts: string[]
  optionalFacts: string[]
  unsupportedFacts: string[]
  plan: FactRequestPlan
}

// ---------------------------------------------------------------------------
// Scene Closure
// ---------------------------------------------------------------------------

export interface SceneClosure {
  subjects: Map<ImhotepId, Subject>
  frames: Map<ImhotepId, unknown>
  states: Map<ImhotepId, StateSnapshot>
  timelines: Map<ImhotepId, TimelineSnapshot>
  resolved: boolean
  diagnostics: Diagnostic[]
}

// ---------------------------------------------------------------------------
// Validation Contract
// ---------------------------------------------------------------------------

export interface ValidationContract {
  validateAst(ast: unknown): ValidationResult
  validateSemanticIr(semanticIr: unknown): ValidationResult
}

export interface ValidationResult {
  valid: boolean
  diagnostics: Diagnostic[]
}