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,211 @@
+/**
+ * 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[]
+}