// Block contract for `@levelset/level-blocks`.
//
// A Block is the LCNC composition unit: a typed quadruple shared by the
// visual editor, the LLM agent, and the compiler.
// Four families differ only in the output type `O`:
//
//   • Constraint blocks  — O = Constraint
//   • Scoring blocks     — O = Scorer
//   • Search blocks      — O = Search | SearchTransformer
//   • Collector blocks   — O = Collector  (selection layer, not a solver
//     constraint — `toMiniZinc` emits an explanatory `% comment` fragment)
//
// Constraint variants are the *interchange format* between Constraint blocks
// and Search; the ADT is the wire, the Block is the cable.

import type { ZodType } from "zod";

import type {
  Collector,
  Constraint,
  Scorer,
  Search,
  SearchTransformer,
} from "../level-core/types.ts";

/** Top-level MiniZinc text emitted for a single block — `constraint`,
 *  `var`, `array`, etc. The compiler concatenates fragments and resolves
 *  shared symbols (`active[t,d]`, `tasks_demanding[r]`, `DAYS`). */
export interface MiniZincFragment {
  readonly text: string;
}

/** Optional escape hatch for blocks where MiniZinc → FlatZinc loses
 *  structure the underlying CP-SAT model can express directly. */
export interface CpSatFragment {
  readonly text: string;
}

export interface BlockDoc {
  readonly nl: string;
  readonly pseudocode: string;
}

export interface Block<I, O> {
  readonly id: string;
  readonly schema: {
    readonly input: ZodType<I>;
    readonly output: ZodType<O>;
  };
  apply(input: I): O;
  toMiniZinc(input: I): MiniZincFragment;
  toCpSat?(input: I): CpSatFragment;
  readonly doc: BlockDoc;
}

export type ConstraintBlock<I> = Block<I, Constraint>;
/** A policy/group block that expands one authored instance into several
 *  ordinary engine constraints. */
export type MultiConstraintBlock<I> = Block<I, readonly Constraint[]>;
export type ScoringBlock<I> = Block<I, Scorer>;
export type SearchBlock<I> = Block<I, Search | SearchTransformer>;
export type CollectorBlock<I> = Block<I, Collector>;