Imhotep/packages/imhotep-core/src/property-results.ts

/**
 * Property run result contracts.
 *
 * These interfaces materialize Invariant 6: every result must clearly say
 * whether it is scene-determinate, scene-indeterminate, enumerated-determinate,
 * or sampled. The mode field is a literal discriminant so switch-exhaustiveness
 * checking works.
 */

import type { ImhotepId } from './types.js'

// ---------------------------------------------------------------------------
// SampledRunResult
// ---------------------------------------------------------------------------

export interface SampledRunResult {
  mode: 'sampled'
  seed: number
  numRuns: number
  passed: boolean
  counterexample?: unknown
  shrunkCounterexample?: unknown
  failingScene?: unknown
  diagnostics: unknown[]
  // P1.3 Property-Run Reporting Upgrade
  minimalFailingCase?: unknown
  caseIndex?: number
  durationMs?: number
  replayPayload?: { props: unknown; seed: number; caseIndex: number }
}

// ---------------------------------------------------------------------------
// EnumeratedRunResult
// ---------------------------------------------------------------------------

export interface EnumeratedRunResult {
  mode: 'enumerated-determinate'
  totalCases: number
  passed: boolean
  failingCase?: unknown
  diagnostics: unknown[]
  // P1.3 Property-Run Reporting Upgrade
  minimalFailingCase?: unknown
  caseIndex?: number
  seed?: number
  durationMs?: number
  replayPayload?: { props: unknown; seed: number; caseIndex: number }
}

// ---------------------------------------------------------------------------
// Scene Evaluation Results (for completeness in the taxonomy)
// ---------------------------------------------------------------------------

export interface DeterministicSceneResult {
  mode: 'scene-determinate' | 'scene-indeterminate'
  sceneId: ImhotepId
  results: unknown[]
  proofs: unknown[]
  diagnostics: unknown[]
}

// ---------------------------------------------------------------------------
// Union type for any property or scene run result
// ---------------------------------------------------------------------------

export type PropertyRunResult =
  | SampledRunResult
  | EnumeratedRunResult
  | DeterministicSceneResult

// ---------------------------------------------------------------------------
// Type Guards
// ---------------------------------------------------------------------------

export function isSampledRunResult(result: PropertyRunResult): result is SampledRunResult {
  return result.mode === 'sampled'
}

export function isEnumeratedRunResult(result: PropertyRunResult): result is EnumeratedRunResult {
  return result.mode === 'enumerated-determinate'
}

export function isDeterministicSceneResult(result: PropertyRunResult): result is DeterministicSceneResult {
  return result.mode === 'scene-determinate' || result.mode === 'scene-indeterminate'
}