// src/core/effects/backend.ts
// Source of truth: VISION-FIXED-POINT.md Section 4.3

import type { State } from "../eval/machine";
import type { OpCall } from "./opcall";

/**
 * THE interface for pluggable CESK effect backends.
 *
 * To add a new effect backend:
 *   1. Implement this interface
 *   2. Register it: runtime.registerBackend(myBackend)
 *   3. Lisp code can now (effect my-op arg1 arg2)
 */
export interface EffectBackend {
  /** Which effect op names this backend handles */
  readonly ops: readonly string[];

  /**
   * Handle an effect.
   *
   * You receive the current State and the OpCall (which contains the op name,
   * args, and a Resumption). Do your work — call an API, manipulate the
   * continuation stack, compute something — then call:
   *
   *   opcall.resumption.invoke(yourResultAsVal)
   *
   * That returns the next State, which you return from handle().
   */
  handle(state: State, opcall: OpCall): Promise<State>;

  /** Optional cleanup */
  dispose?(): Promise<void>;
}
