/**
 * Graph Model v2 — YAML/JSON Deserializer
 *
 * Phase 1, Subtask 2 (parsing & validation).
 *
 * Produces a `GraphDocument` (a `GraphDeclaration` whose `version` is optional
 * at the type level so that a missing/invalid `version` can flow through to the
 * structural validator, which reports it) from a YAML string, a JSON string, or
 * an already-parsed object tree (as produced by `JSON.parse` or a YAML loader).
 *
 * The parser performs SHAPE / required-field mapping only:
 *   - extracts the top-level `graph:` block (legacy `dag:` accepted as alias)
 *   - coerces YAML idioms into the TS v2 types (see field-mapping notes below)
 *   - reports deserialization-level errors (missing required scalars, unknown
 *     edge `type`, non-array collections)
 *
 * CROSS-REFERENTIAL structural rules (node-id uniqueness, edge endpoint
 * validity, cycle containment, loop-group node refs, approval-node outgoing
 * constraints) are NOT checked here — they belong to
 * `validateGraphDeclaration` in ./validator-v2.ts. The existing v1 split
 * (parser.ts maps, validator.ts checks) is preserved for v2.
 *
 * Field-mapping divergence notes (YAML schema §dag-yaml-schema.md vs TS types):
 *   - `data_passthrough.include` (YAML) -> `DataMapping.fields` (TS);
 *     `data_passthrough.exclude` -> `DataMapping.exclude` (string array), and
 *     `data_passthrough.max_chars` -> `DataMapping.maxChars` (number).
 *   - `retry` may be a bare number (YAML §2.4) or `{max, backoff_ms}` (TS
 *     RetryConfig); both forms are accepted.
 *   - `join.strategy` uses the `"quorum:N"` combined string form (YAML §2.3.1)
 *     which is expanded into `{ strategy: "quorum", quorum: N }` (TS JoinConfig).
 *     An unrecognized strategy — including a bare `"quorum"` with no count —
 *     is a deserialization ERROR, exactly like an unknown edge `type`: the
 *     join shapes downstream fan-in semantics, so dropping it silently would
 *     re-interpret "first answer wins" as "wait for everyone" (Y6).
 *   - `loop_groups[].mode` is read and checked against `LoopMode` instead of
 *     being dropped; an unknown value is a deserialization error (Y6).
 *   - `template` / `max_iterations` are mapped onto the declaration (they used
 *     to be documented as round-trip metadata but were never read, so every
 *     parse → serialize lost them) (Y6).
 *
 * Design reference: .rolebox/design/dag-yaml-schema.md (Appendix B canonical
 * example), src/types.graph-v2.ts, src/constants.ts (JoinStrategy).
 */
import { type Result } from "../utils/result.ts";
import type { GraphDeclaration } from "../types.graph-v2.ts";
/**
 * A graph document as parsed from disk. `version` is optional at the type level
 * so a document missing `version` is representable here and handed to the
 * validator, which is responsible for the "version missing" structural error.
 * When `version === 2` this is exactly a `GraphDeclaration`.
 */
export type GraphDocument = Omit<GraphDeclaration, "version"> & {
    version?: number;
};
/** Result of parsing — a discriminated union so callers never cast. */
export type GraphParseResult = Result<GraphDocument, string[]>;
/**
 * Deserialize a graph from a YAML/JSON string or an already-parsed object.
 *
 * @param source - YAML/JSON text, or a parsed object tree.
 * @returns `ok(graph)` on success, or `err(errors)` with the human-readable
 *   deserialization errors on failure. Never throws for malformed *content*;
 *   throws nothing at all on the happy path.
 */
export declare function parseGraph(source: string | unknown): GraphParseResult;
/**
 * Load a graph declaration from a serialized YAML/JSON file on disk.
 *
 * Reads the file, deserializes it via the v2 parser (`parseGraph` in this
 * module — YAML and JSON are both accepted), then runs structural validation
 * (`validateGraphDeclaration` in ./validator-v2.ts) in EXECUTION mode — a
 * graph that could not actually run (an uncontained revise-free cycle, an
 * unknown `on_condition` name) is rejected. Returns the validated
 * `GraphDeclaration`, or `null` when the file is unreadable, fails to
 * deserialize, or fails execution-mode structural validation.
 *
 * @param filePath - absolute or relative path to a `.yaml`/`.yml`/`.json` graph file.
 * @returns the validated v2 graph declaration, or `null` on any failure.
 */
export declare function importGraphFromFile(filePath: string): GraphDeclaration | null;
//# sourceMappingURL=parser-v2.d.ts.map