// Coded issues for the `.conf` layer — the LEVELSET_E3## band, joining the
// E1## run-analysis / E2## warning namespace (level-core/errors.ts) as conf's
// own union. A `.conf` file is a text projection of a RunConfig; every way it
// can be malformed gets a stable, searchable code and an actionable message,
// with line/column for syntax errors and instanceId attribution for the
// registry-validation ones (so a canvas/editor can point at the offending
// block).

/** Where in the source a conf issue lands (1-based), when known. */
export interface ConfSourcePos {
  readonly line: number;
  readonly column: number;
}

export type ConfIssueCode =
  /** TOML syntax error — the text is not a well-formed TOML document. Carries
   *  the parser's line/column. */
  | "LEVELSET_E301"
  /** Config shape error — a value in a valid TOML document violates the
   *  RunConfig schema (wrong type, unknown key in a strict section, a missing
   *  required field). Carries the dotted config path. */
  | "LEVELSET_E302"
  /** Missing or unsupported `[levelset] format` — the required format marker
   *  is absent or not `1`. */
  | "LEVELSET_E303"
  /** A TOML datetime literal was used where an ISO date string is required —
   *  quote it (`epoch = "2026-01-01"`), don't write a bare date. */
  | "LEVELSET_E304"
  /** A block param name collides with a reserved block-table key
   *  (`code` / `enabled` / `provenance` / `shadow`), so the param is
   *  unreachable through the conf format. */
  | "LEVELSET_E305"
  /** A non-finite number (`inf` / `nan`) appeared — configs must be finite;
   *  model "unbounded" as an absent optional param, never Infinity. */
  | "LEVELSET_E306"
  /** Registry validation failed — a mapped GraphIssue (unknown code, invalid
   *  params, cardinality, or a weights/objective/collector reference that
   *  doesn't resolve to a scorer-family instance), attributed to its
   *  instanceId. */
  | "LEVELSET_E308";

export interface ConfIssue {
  readonly code: ConfIssueCode;
  readonly message: string;
  /** The block instanceId the issue attributes to, when it is block-scoped
   *  (E308, E305). */
  readonly instanceId?: string;
  /** Dotted path to the offending value, when known (E302 shape issues,
   *  E304/E306 value issues). */
  readonly path?: string;
  /** Source line/column, when known (E301). */
  readonly pos?: ConfSourcePos;
}