/*
<MODULE_CONTRACT>
  <purpose>journal types — operation journal type definitions: JournalRecord, OperationStep, OperationDefinition (RFC-0958).</purpose>
  <non-goals>
    <item>Do not import mission-specific types — the journal is pure infrastructure.</item>
    <item>Do not implement journal I/O or step execution — those live in jsonl.ts and runner.ts.</item>
  </non-goals>
</MODULE_CONTRACT>
<CHANGE_SUMMARY>
  <item>RFC-0958: initial journal type definitions — JournalRecord discriminated union, OperationStep, OperationDefinition.</item>
  <item>RFC-0962 fo-fix: OperationStep.run returns optional metadata, StepResult interface added, RunOperationResult includes stepResults.</item>
  <item>RFC-1219: op-interrupted record kind — non-terminal resumable-failure marker (additive; older readers ignore it).</item>
  <item>RFC-1097: sweep — werkstatt-engine clean

Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
</CHANGE_SUMMARY>
*/

export type JournalRecord =
  | {
      kind: "op-started";
      opId: string;
      op: string;
      missionId: string;
      at: string;
      platformVersion: string;
    }
  | { kind: "step-started"; opId: string; step: string; seq: number; at: string }
  | {
      kind: "step-done";
      opId: string;
      step: string;
      seq: number;
      at: string;
      meta?: Record<string, unknown>;
    }
  | { kind: "step-failed"; opId: string; step: string; seq: number; at: string; error: string }
  | {
      kind: "step-skipped";
      opId: string;
      step: string;
      seq: number;
      at: string;
      reason: "already-satisfied" | "resume";
    }
  | { kind: "op-done"; opId: string; at: string }
  | { kind: "op-abandoned"; opId: string; at: string; reason: string }
  // RFC-1219: non-terminal marker — the op stopped on a failed step and is
  // resumable. Older readers ignore the unknown kind and still see the op as
  // open; findIncompleteOperation treats it as non-terminal either way.
  | { kind: "op-interrupted"; opId: string; at: string; failedStep: string };

export interface OperationStep<C> {
  name: string;
  run(ctx: C): Promise<void | Record<string, unknown>>;
  verify?(ctx: C): Promise<boolean>;
}

export interface OperationDefinition<C> {
  op: string;
  steps: OperationStep<C>[];
}

export interface StepResult {
  step: string;
  status: "done" | "skipped" | "failed";
  durationMs: number;
  meta?: Record<string, unknown>;
}

export interface RunOperationResult {
  opId: string;
  completed: boolean;
  failedStep?: string;
  failedStepError?: string;
  skipped: string[];
  executed: string[];
  stepResults: StepResult[];
}