@effected/yaml 0.1.0

package/index.d.ts

@@ -0,0 +1,1331 @@
+import { Data, Effect, Option, Schema, Stream } from "effect";
+//#region src/YamlDiagnostic.d.ts
+/**
+ * Error codes emitted by the lexer stage.
+ *
+ * @public
+ */
+declare const YamlLexErrorCode: Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>;
+/**
+ * The union of all lexer-stage error code string literals.
+ *
+ * @public
+ */
+type YamlLexErrorCode = typeof YamlLexErrorCode.Type;
+/**
+ * Error codes emitted by the CST-parser stage.
+ *
+ * @public
+ */
+declare const YamlParseErrorCode: Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>;
+/**
+ * The union of all parser-stage error code string literals.
+ *
+ * @public
+ */
+type YamlParseErrorCode = typeof YamlParseErrorCode.Type;
+/**
+ * Error codes emitted by the composer stage.
+ *
+ * @public
+ */
+declare const YamlComposerErrorCode: Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>;
+/**
+ * The union of all composer-stage error code string literals.
+ *
+ * @public
+ */
+type YamlComposerErrorCode = typeof YamlComposerErrorCode.Type;
+/**
+ * Error codes emitted by the stringifier (the circular-reference guard).
+ *
+ * @public
+ */
+declare const YamlStringifyErrorCode: Schema.Literals<readonly ["CircularReference"]>;
+/**
+ * The union of all stringifier-stage error code string literals.
+ *
+ * @public
+ */
+type YamlStringifyErrorCode = typeof YamlStringifyErrorCode.Type;
+/**
+ * Error codes emitted by `YamlFormat.modify`'s path navigation against an
+ * already-composed AST — not raised by the parser/composer/stringifier.
+ *
+ * @public
+ */
+declare const YamlModifyErrorCode: Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable"]>;
+/**
+ * The union of all modify-stage error code string literals.
+ *
+ * @public
+ */
+type YamlModifyErrorCode = typeof YamlModifyErrorCode.Type;
+/**
+ * Union of all YAML error codes across all pipeline stages. Stage
+ * discrimination lives here (in the code), not in separate error classes.
+ *
+ * @public
+ */
+declare const YamlErrorCode: Schema.Union<readonly [Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>, Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>, Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>, Schema.Literals<readonly ["CircularReference"]>, Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable"]>]>;
+/**
+ * The union of all YAML error code string literals.
+ *
+ * @public
+ */
+type YamlErrorCode = typeof YamlErrorCode.Type;
+declare const YamlDiagnostic_base: Schema.Class<YamlDiagnostic, Schema.Struct<{
+  readonly code: Schema.Union<readonly [Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>, Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>, Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>, Schema.Literals<readonly ["CircularReference"]>, Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable"]>]>;
+  readonly message: Schema.String;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+  readonly line: Schema.Number;
+  readonly character: Schema.Number;
+}>, {}>;
+/**
+ * One structured diagnostic: its {@link (YamlErrorCode:type)}, a
+ * human-readable `message`, and its exact position (`offset`/`length`, plus
+ * zero-based `line`/`character`). Used for both errors and warnings-as-data;
+ * fatality is a property of the code — see {@link YamlDiagnostic.isFatal}.
+ *
+ * @remarks
+ * The five-field positional core (`code`/`offset`/`length`/`line`/`character`)
+ * is structurally identical to `@effected/jsonc`'s parse-error detail shape;
+ * `message` is this package's additive extra.
+ *
+ * @public
+ */
+declare class YamlDiagnostic extends YamlDiagnostic_base {
+  /**
+   * The single fatal-code predicate: whether diagnostics with this code
+   * abort a parse (vs. being recoverable warnings-as-data). Declared once,
+   * as a property of the code — replacing the v3 source's three
+   * subtly-differing inline fatal lists.
+   */
+  static isFatal(code: YamlErrorCode): boolean;
+  /**
+   * Materialize a raw engine diagnostic record into a `YamlDiagnostic`,
+   * deriving `line`/`character` from `offset` against the source `text`.
+   * Advanced — the parse/stringify entry points call this for you.
+   */
+  static fromRaw(raw: {
+    readonly code: YamlErrorCode;
+    readonly message: string;
+    readonly offset: number;
+    readonly length: number;
+  }, text: string): YamlDiagnostic;
+}
+//#endregion
+//#region src/Yaml.d.ts
+declare const YamlParseOptions_base: Schema.Class<YamlParseOptions, Schema.Struct<{
+  readonly strict: Schema.optionalKey<Schema.Boolean>;
+  readonly maxAliasCount: Schema.optionalKey<Schema.Number>;
+  readonly uniqueKeys: Schema.optionalKey<Schema.Boolean>;
+}>, {}>;
+/**
+ * Options controlling parse behavior. All fields are omissible; absent fields
+ * resolve to `strict` `true`, `maxAliasCount` `100` (the alias-based
+ * denial-of-service guard) and `uniqueKeys` `true` (duplicate mapping keys
+ * are errors).
+ *
+ * @public
+ */
+declare class YamlParseOptions extends YamlParseOptions_base {}
+declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Schema.Struct<{
+  readonly indent: Schema.optionalKey<Schema.Number>;
+  readonly lineWidth: Schema.optionalKey<Schema.Number>;
+  readonly defaultScalarStyle: Schema.optionalKey<Schema.Literals<readonly ["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>>;
+  readonly defaultCollectionStyle: Schema.optionalKey<Schema.Literals<readonly ["block", "flow"]>>;
+  readonly sortKeys: Schema.optionalKey<Schema.Boolean>;
+  readonly finalNewline: Schema.optionalKey<Schema.Boolean>;
+  readonly forceDefaultStyles: Schema.optionalKey<Schema.Boolean>;
+}>, {}>;
+/**
+ * Options controlling stringify behavior. All fields are omissible; absent
+ * fields resolve to `indent` `2`, `lineWidth` `80`, `defaultScalarStyle`
+ * `"plain"`, `defaultCollectionStyle` `"block"`, `sortKeys` `false`,
+ * `finalNewline` `true` and `forceDefaultStyles` `false`.
+ *
+ * @public
+ */
+declare class YamlStringifyOptions extends YamlStringifyOptions_base {}
+declare const YamlParseError_base: Schema.Class<YamlParseError, Schema.TaggedStruct<"YamlParseError", {
+  readonly diagnostics: Schema.$Array<typeof YamlDiagnostic>;
+  readonly input: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Error-recovery parse failure: aggregates every fatal {@link YamlDiagnostic}
+ * encountered, so a single failure reports the whole batch. Raised by
+ * {@link Yaml.parse}, {@link Yaml.parseAll}, `YamlDocument.parse`/`parseAll`
+ * and the decode direction of the schema factories.
+ *
+ * @public
+ */
+declare class YamlParseError extends YamlParseError_base {
+  get message(): string;
+}
+declare const YamlStringifyError_base: Schema.Class<YamlStringifyError, Schema.TaggedStruct<"YamlStringifyError", {
+  readonly diagnostics: Schema.$Array<typeof YamlDiagnostic>;
+  readonly value: Schema.Unknown;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Stringification failure (the circular-reference guard), carrying structured
+ * {@link YamlDiagnostic} entries and the offending value. Raised by
+ * {@link Yaml.stringify}, `YamlDocument#stringify` and the encode direction of
+ * the schema factories.
+ *
+ * @public
+ */
+declare class YamlStringifyError extends YamlStringifyError_base {
+  get message(): string;
+}
+/**
+ * Static entry points for YAML parsing, stringification, comment stripping,
+ * semantic equality and the schema factories. Not instantiable.
+ *
+ * @remarks
+ * `parse`/`parseAll`/`stringify` and the schema factories carry real typed
+ * error channels — including the hardening guards (an alias-expansion budget
+ * on decode, a nesting-depth cap on encode) that keep malformed or
+ * adversarial input on the typed channel instead of surfacing as an unhandled
+ * defect. `stripComments`/`equals`/`equalsValue` are pure total functions.
+ *
+ * @example
+ * ```ts
+ * import { Yaml } from "@effected/yaml";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const value = yield* Yaml.parse("name: Alice\nage: 30");
+ *   return value; // { name: "Alice", age: 30 }
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class Yaml {
+  private constructor();
+  /**
+   * Parse a single YAML document into a plain JavaScript value, resolving
+   * anchors and aliases. Error-recovery parsing: collects every fatal
+   * diagnostic and fails once with the aggregate {@link YamlParseError}.
+   * Returns `unknown`, never `any`.
+   *
+   * A "billion laughs" alias-expansion blow-up (an alias chain whose
+   * resolved size grows exponentially relative to `maxAliasCount`) also
+   * fails through {@link YamlParseError} with an `AliasCountExceeded`
+   * diagnostic, never as an unhandled defect.
+   */
+  static readonly parse: (text: string, options?: YamlParseOptions | undefined) => Effect.Effect<unknown, YamlParseError, never>;
+  /**
+   * Parse a multi-document YAML stream into an array of plain JavaScript
+   * values (one per document, in order). Any fatal diagnostic in any
+   * document — or a stream-level directive-placement error — fails the
+   * whole Effect with the aggregate {@link YamlParseError}.
+   *
+   * A "billion laughs" alias-expansion blow-up in any document also fails
+   * through {@link YamlParseError} with an `AliasCountExceeded` diagnostic,
+   * never as an unhandled defect.
+   */
+  static readonly parseAll: (text: string, options?: YamlParseOptions | undefined) => Effect.Effect<readonly unknown[], YamlParseError, never>;
+  /**
+   * Stringify a plain JavaScript value as YAML. Fails with
+   * {@link YamlStringifyError} on circular references (`CircularReference`)
+   * or on a value nested deeper than the stringifier's recursion budget
+   * (`NestingDepthExceeded`) — both surface through the typed error channel
+   * rather than as an unhandled stack-overflow defect.
+   */
+  static readonly stringify: (value: unknown, options?: YamlStringifyOptions | undefined) => Effect.Effect<string, YamlStringifyError, never>;
+  /**
+   * Strip comments from YAML text. Without `replaceCh`, comment characters
+   * are removed (line breaks are kept, so line numbers stay stable); with a
+   * `replaceCh` (e.g. `" "`), each comment character is replaced instead,
+   * keeping all offsets stable. Quote-aware: `#` inside quoted scalars is
+   * content, not a comment. Pure and total.
+   */
+  static stripComments(text: string, replaceCh?: string): string;
+  /**
+   * Compare two YAML strings for semantic equality: comments, whitespace,
+   * formatting and mapping key order are ignored; sequence order is
+   * significant. Malformed input is never equal to anything — parse errors
+   * (or duplicate keys) on either side yield `false` rather than comparing
+   * recovery-parser artifacts. Pure and total.
+   */
+  static equals(a: string, b: string): boolean;
+  /**
+   * Compare a YAML string against an existing JavaScript value with the
+   * same semantics as {@link Yaml.equals}: malformed `text` yields `false`.
+   * Pure and total.
+   */
+  static equalsValue(text: string, value: unknown): boolean;
+  /**
+   * A `Schema<unknown, string>` decoding a single YAML document with the
+   * given `options` (defaults when omitted) and encoding values back to
+   * YAML text with default stringify options.
+   *
+   * Schema-producing: each call returns a fresh schema whose derivation
+   * caches are not shared across calls. Bind the result to a `const` on hot
+   * paths; for the default-options case use {@link Yaml.YamlFromString}.
+   */
+  static fromString(options?: YamlParseOptions): Schema.Codec<unknown, string>;
+  /**
+   * The zero-config `Schema<unknown, string>` — `Yaml.fromString()` with
+   * default options, pre-bound so the common case needs no memoization
+   * discipline.
+   */
+  static readonly YamlFromString: Schema.Codec<unknown, string>;
+  /**
+   * A `Schema<ReadonlyArray<unknown>, string>` decoding a multi-document
+   * YAML stream into one value per document, and encoding an array of
+   * values back into a `---`-separated stream.
+   *
+   * Schema-producing: bind the result to a `const` on hot paths (see
+   * {@link Yaml.fromString}).
+   */
+  static allFromString(options?: YamlParseOptions): Schema.Codec<ReadonlyArray<unknown>, string>;
+  /**
+   * Compose {@link Yaml.fromString} with a target schema, yielding a
+   * `Schema<A, string>` that decodes YAML straight into a validated domain
+   * value — the single best consumer-facing feature of the library. The
+   * target's decoding/encoding service requirements flow through.
+   *
+   * Schema-producing: bind the result to a `const` on hot paths (see
+   * {@link Yaml.fromString}).
+   */
+  static schema<T, E, RD = never, RE = never>(target: Schema.Codec<T, E, RD, RE>, options?: YamlParseOptions): Schema.Codec<T, string, RD, RE>;
+}
+//#endregion
+//#region src/YamlEdit.d.ts
+/**
+ * A single path segment: a `string` for mapping keys or a `number` for
+ * sequence indices.
+ *
+ * @public
+ */
+type YamlSegment = string | number;
+/**
+ * An ordered sequence of {@link (YamlSegment:type)} values describing a
+ * location within a YAML document tree.
+ *
+ * @public
+ */
+type YamlPath = ReadonlyArray<YamlSegment>;
+declare const YamlRange_base: Schema.Class<YamlRange, Schema.Struct<{
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A range within a YAML document, expressed as a zero-based character
+ * `offset` and a `length` in UTF-16 code units. Pass to `YamlFormat.format`
+ * to restrict formatting to a region.
+ *
+ * @public
+ */
+declare class YamlRange extends YamlRange_base {}
+declare const YamlEdit_base: Schema.Class<YamlEdit, Schema.Struct<{
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+  readonly content: Schema.String;
+}>, {}>;
+/**
+ * A non-mutating text edit: replace the span `[offset, offset + length)` with
+ * `content`. Set `length` to `0` to insert, `content` to `""` to delete.
+ *
+ * @remarks
+ * Structurally identical to `@effected/jsonc`'s edit shape (same field names,
+ * types and semantics) per the jsonc/yaml parity convention, so consumer code
+ * can be written once over "a document codec's Edit/Range/Path".
+ *
+ * @public
+ */
+declare class YamlEdit extends YamlEdit_base {
+  /**
+   * Apply `edits` to `text`, producing a new string. Edits are applied in
+   * reverse-offset order so earlier offsets stay valid; the input `edits`
+   * array is not mutated. Pure and total.
+   */
+  static applyAll(text: string, edits: ReadonlyArray<YamlEdit>): string;
+}
+//#endregion
+//#region src/YamlNode.d.ts
+/**
+ * YAML scalar presentation styles.
+ *
+ * @public
+ */
+declare const ScalarStyle: Schema.Literals<readonly ["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>;
+/**
+ * The union of all scalar style string literals.
+ *
+ * @public
+ */
+type ScalarStyle = typeof ScalarStyle.Type;
+/**
+ * YAML collection presentation styles.
+ *
+ * @public
+ */
+declare const CollectionStyle: Schema.Literals<readonly ["block", "flow"]>;
+/**
+ * The union of all collection style string literals.
+ *
+ * @public
+ */
+type CollectionStyle = typeof CollectionStyle.Type;
+/**
+ * Block-scalar chomping indicators (`-` strip, default clip, `+` keep).
+ * Referenced by the {@link YamlScalar} `chomp` field schema.
+ *
+ * @public
+ */
+declare const ScalarChomp: Schema.Literals<readonly ["strip", "clip", "keep"]>;
+/**
+ * The union of all block-scalar chomping indicator string literals.
+ *
+ * @public
+ */
+type ScalarChomp = typeof ScalarChomp.Type;
+declare const YamlScalar_base: Schema.Class<YamlScalar, Schema.TaggedStruct<"YamlScalar", {
+  readonly value: Schema.Unknown;
+  readonly tag: Schema.optionalKey<Schema.String>;
+  readonly style: Schema.Literals<readonly ["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>;
+  readonly anchor: Schema.optionalKey<Schema.String>;
+  readonly comment: Schema.optionalKey<Schema.String>;
+  readonly chomp: Schema.optionalKey<Schema.Literals<readonly ["strip", "clip", "keep"]>>;
+  readonly raw: Schema.optionalKey<Schema.String>;
+  readonly sourceMultiline: Schema.optionalKey<Schema.Boolean>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A YAML scalar AST node, representing a leaf value such as a string,
+ * number, boolean, or null.
+ *
+ * - `value` — the resolved JavaScript value (null, boolean, number, bigint or
+ *   string).
+ * - `style` — the scalar presentation style in the source document.
+ * - `tag` — optional explicit YAML tag (e.g. `!!str`, `!!int`).
+ * - `anchor` — optional anchor name for aliasing.
+ * - `comment` — optional trailing or leading comment text.
+ * - `chomp` — block-scalar chomping indicator, when the scalar is a block
+ *   scalar.
+ * - `raw` — the raw source text, preserved when it differs from the resolved
+ *   value in a way stringification needs to know about.
+ * - `sourceMultiline` — `true` when the source span covers two or more lines;
+ *   absent on synthetic nodes.
+ * - `offset` / `length` — the node's span in the source.
+ *
+ * @public
+ */
+declare class YamlScalar extends YamlScalar_base {
+  /**
+   * Navigate to a descendant by path (string segments for mapping keys,
+   * numbers for sequence indices). `Option.none()` when any segment cannot
+   * be resolved. Pure.
+   */
+  find(path: YamlPath): Option.Option<YamlNode>;
+  /**
+   * Find the deepest node whose span contains `offset` (half-open interval),
+   * or `Option.none()` when the offset falls outside this subtree. Pure.
+   */
+  findAtOffset(offset: number): Option.Option<YamlNode>;
+  /**
+   * Return the path from this node to the given descendant node (matched by
+   * reference identity), or `Option.none()` when it is not in this subtree.
+   * The inverse of {@link YamlScalar.find}. Pure.
+   */
+  pathOf(node: YamlNode): Option.Option<YamlPath>;
+  /**
+   * Reconstruct the plain JavaScript value of this subtree. Aliases resolve
+   * through `anchors` (anchors encountered during the walk register
+   * incrementally, so an alias sees the most recent definition at its point
+   * of use); unresolvable aliases yield `null`. Pure and total.
+   */
+  toValue(anchors?: Map<string, YamlNode>): unknown;
+}
+declare const YamlAlias_base: Schema.Class<YamlAlias, Schema.TaggedStruct<"YamlAlias", {
+  readonly name: Schema.String;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A YAML alias AST node, referencing a previously defined anchor by name
+ * (without the leading `*`).
+ *
+ * @public
+ */
+declare class YamlAlias extends YamlAlias_base {
+  /** See `YamlScalar.find`. Pure. */
+  find(path: YamlPath): Option.Option<YamlNode>;
+  /** See `YamlScalar.findAtOffset`. Pure. */
+  findAtOffset(offset: number): Option.Option<YamlNode>;
+  /** See `YamlScalar.pathOf`. Pure. */
+  pathOf(node: YamlNode): Option.Option<YamlPath>;
+  /** See `YamlScalar.toValue`. Pure and total. */
+  toValue(anchors?: Map<string, YamlNode>): unknown;
+}
+/**
+ * A discriminated-union schema covering all four YAML AST value node types:
+ * {@link YamlScalar}, {@link YamlMap}, {@link YamlSeq} and {@link YamlAlias}.
+ * Defined lazily via `Schema.suspend` to break the recursive reference chain
+ * `YamlNode → YamlMap → YamlPair → YamlNode`.
+ *
+ * @remarks
+ * Construct member nodes via their `.make(...)` static (e.g.
+ * `YamlScalar.make(...)`), never `new YamlScalar(...)` — the internal
+ * composer's hot-path `new` construction is the one recorded exception, kept
+ * internal to the engine for its allocation-sensitive walk.
+ *
+ * @public
+ */
+declare const YamlNode: Schema.Schema<YamlScalar | YamlMap | YamlSeq | YamlAlias>;
+/**
+ * The union of all YAML AST value node types.
+ *
+ * @public
+ */
+type YamlNode = YamlScalar | YamlMap | YamlSeq | YamlAlias;
+declare const YamlPair_base: Schema.Class<YamlPair, Schema.TaggedStruct<"YamlPair", {
+  readonly key: Schema.suspend<Schema.Schema<YamlNode>>;
+  readonly value: Schema.NullOr<Schema.suspend<Schema.Schema<YamlNode>>>;
+  readonly comment: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * A YAML key-value pair AST node, representing one entry within a mapping.
+ * `value` is `null` when absent (e.g. `key:` with no value).
+ *
+ * @public
+ */
+declare class YamlPair extends YamlPair_base {}
+declare const YamlMap_base: Schema.Class<YamlMap, Schema.TaggedStruct<"YamlMap", {
+  readonly items: Schema.$Array<Schema.suspend<Schema.Schema<YamlPair>>>;
+  readonly tag: Schema.optionalKey<Schema.String>;
+  readonly anchor: Schema.optionalKey<Schema.String>;
+  readonly style: Schema.Literals<readonly ["block", "flow"]>;
+  readonly comment: Schema.optionalKey<Schema.String>;
+  readonly sourceMultiline: Schema.optionalKey<Schema.Boolean>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A YAML mapping AST node, representing a collection of {@link YamlPair}
+ * entries.
+ *
+ * - `style` — the presentation style: `"block"` or `"flow"`.
+ * - `sourceMultiline` — `true` when the source span covers two or more lines;
+ *   used by the canonical stringifier. Absent on synthetic nodes.
+ *
+ * @public
+ */
+declare class YamlMap extends YamlMap_base {
+  /** See `YamlScalar.find`. Pure. */
+  find(path: YamlPath): Option.Option<YamlNode>;
+  /** See `YamlScalar.findAtOffset`. Pure. */
+  findAtOffset(offset: number): Option.Option<YamlNode>;
+  /** See `YamlScalar.pathOf`. Pure. */
+  pathOf(node: YamlNode): Option.Option<YamlPath>;
+  /** See `YamlScalar.toValue`. Pure and total. */
+  toValue(anchors?: Map<string, YamlNode>): unknown;
+}
+declare const YamlSeq_base: Schema.Class<YamlSeq, Schema.TaggedStruct<"YamlSeq", {
+  readonly items: Schema.$Array<Schema.suspend<Schema.Schema<YamlNode>>>;
+  readonly tag: Schema.optionalKey<Schema.String>;
+  readonly anchor: Schema.optionalKey<Schema.String>;
+  readonly style: Schema.Literals<readonly ["block", "flow"]>;
+  readonly comment: Schema.optionalKey<Schema.String>;
+  readonly sourceMultiline: Schema.optionalKey<Schema.Boolean>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+}>, {}>;
+/**
+ * A YAML sequence AST node, representing an ordered list of
+ * {@link (YamlNode:type)} values.
+ *
+ * @public
+ */
+declare class YamlSeq extends YamlSeq_base {
+  /** See `YamlScalar.find`. Pure. */
+  find(path: YamlPath): Option.Option<YamlNode>;
+  /** See `YamlScalar.findAtOffset`. Pure. */
+  findAtOffset(offset: number): Option.Option<YamlNode>;
+  /** See `YamlScalar.pathOf`. Pure. */
+  pathOf(node: YamlNode): Option.Option<YamlPath>;
+  /** See `YamlScalar.toValue`. Pure and total. */
+  toValue(anchors?: Map<string, YamlNode>): unknown;
+}
+//#endregion
+//#region src/YamlDocument.d.ts
+declare const YamlDirective_base: Schema.Class<YamlDirective, Schema.Struct<{
+  readonly name: Schema.String;
+  readonly parameters: Schema.$Array<Schema.String>;
+}>, {}>;
+/**
+ * A YAML directive appearing before a document (e.g. `%YAML 1.2` or
+ * `%TAG ! tag:example.com,2000:`). `"YAML"` and `"TAG"` are the YAML 1.2
+ * spec-defined directives; any other name is a reserved directive preserved
+ * for round-trip fidelity.
+ *
+ * @public
+ */
+declare class YamlDirective extends YamlDirective_base {}
+declare const YamlDocument_base: Schema.Class<YamlDocument, Schema.Struct<{
+  readonly contents: Schema.NullOr<Schema.suspend<Schema.Schema<YamlNode>>>;
+  readonly errors: Schema.$Array<typeof YamlDiagnostic>;
+  readonly warnings: Schema.$Array<typeof YamlDiagnostic>;
+  readonly directives: Schema.$Array<typeof YamlDirective>;
+  readonly comment: Schema.optionalKey<Schema.String>;
+  readonly hasDocumentStart: Schema.optionalKey<Schema.Boolean>;
+  readonly hasDocumentEnd: Schema.optionalKey<Schema.Boolean>;
+  readonly hasDocumentStartTab: Schema.optionalKey<Schema.Boolean>;
+}>, {}>;
+/**
+ * A parsed YAML document: the root {@link (YamlNode:type)} (or `null` when
+ * empty), recovered `errors` and `warnings` as {@link YamlDiagnostic} data,
+ * the {@link YamlDirective} list, an optional document-level comment, and the
+ * `---`/`...` framing flags (absent flags read as `false`).
+ *
+ * Construct via `YamlDocument.parse` / `parseAll`; `YamlDocument.make` is for
+ * synthetic documents.
+ *
+ * @public
+ */
+declare class YamlDocument extends YamlDocument_base {
+  /**
+   * Parse a single YAML document, keeping the full AST, directives and
+   * recovered diagnostics. Fails with the aggregate {@link YamlParseError}
+   * when any fatal-code diagnostic is present; non-fatal diagnostics are
+   * data on the returned document.
+   */
+  static readonly parse: (text: string, options?: YamlParseOptions | undefined) => Effect.Effect<YamlDocument, YamlParseError, never>;
+  /**
+   * Parse a multi-document YAML stream into one {@link YamlDocument} per
+   * document. Any fatal diagnostic in any document — or a stream-level
+   * directive-placement error — fails the whole Effect.
+   */
+  static readonly parseAll: (text: string, options?: YamlParseOptions | undefined) => Effect.Effect<readonly YamlDocument[], YamlParseError, never>;
+  /**
+   * A `Schema<YamlDocument, string>` decoding YAML text into a full
+   * document (AST, directives, diagnostics) and encoding a document back to
+   * YAML text.
+   *
+   * Schema-producing: each call returns a fresh schema whose derivation
+   * caches are not shared across calls; bind the result to a `const` on hot
+   * paths.
+   */
+  static schema(options?: YamlParseOptions): Schema.Codec<YamlDocument, string>;
+  /**
+   * Stringify this document (contents, directives and framing) as YAML.
+   * Fails with {@link YamlStringifyError} on circular references introduced
+   * into a synthetic AST (`CircularReference`) or on a synthetic AST nested
+   * deeper than the stringifier's recursion budget (`NestingDepthExceeded`)
+   * — both surface through the typed error channel rather than as an
+   * unhandled stack-overflow defect.
+   */
+  stringify(options?: YamlStringifyOptions): Effect.Effect<string, YamlStringifyError>;
+  /**
+   * Reconstruct the plain JavaScript value of this document's contents,
+   * resolving anchors and aliases. `null` for an empty document. Pure and
+   * total.
+   */
+  toValue(): unknown;
+}
+//#endregion
+//#region src/YamlFormat.d.ts
+/**
+ * A range accepted at the `format`/`formatToString`/etc. call sites: either a
+ * {@link YamlRange} instance or a plain `{ offset, length }` literal (the two
+ * are structurally interchangeable — only `offset`/`length` are read).
+ *
+ * @public
+ */
+type YamlRangeLike = YamlRange | {
+  readonly offset: number;
+  readonly length: number;
+};
+declare const YamlFormattingOptions_base: Schema.Class<YamlFormattingOptions, Schema.Struct<{
+  readonly indent: Schema.optionalKey<Schema.Number>;
+  readonly lineWidth: Schema.optionalKey<Schema.Number>;
+  readonly defaultScalarStyle: Schema.optionalKey<Schema.Literals<readonly ["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>>;
+  readonly defaultCollectionStyle: Schema.optionalKey<Schema.Literals<readonly ["block", "flow"]>>;
+  readonly sortKeys: Schema.optionalKey<Schema.Boolean>;
+  readonly finalNewline: Schema.optionalKey<Schema.Boolean>;
+  readonly forceDefaultStyles: Schema.optionalKey<Schema.Boolean>;
+  readonly preserveComments: Schema.optionalKey<Schema.Boolean>;
+  readonly range: Schema.optionalKey<typeof YamlRange>;
+}>, {}>;
+/**
+ * Options controlling formatting behavior: every {@link YamlStringifyOptions}
+ * field (derived, not hand-duplicated) plus `preserveComments` (default
+ * `true`) and `range` (restrict edits to a region; see the module-level
+ * remarks on the `range` parameter vs. this field).
+ *
+ * @public
+ */
+declare class YamlFormattingOptions extends YamlFormattingOptions_base {}
+declare const YamlModificationError_base: Schema.Class<YamlModificationError, Schema.TaggedStruct<"YamlModificationError", {
+  readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>;
+  readonly diagnostics: Schema.$Array<typeof YamlDiagnostic>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when `YamlFormat.modify` cannot navigate the requested path against
+ * the composed AST (a structural mismatch) or the source fails to parse.
+ * Carries structured {@link YamlDiagnostic} entries — never a collapsed
+ * `reason` string (the structure-preserving-errors house rule).
+ *
+ * @public
+ */
+declare class YamlModificationError extends YamlModificationError_base {
+  get message(): string;
+}
+/**
+ * Formatting and modification statics. Not instantiable.
+ *
+ * @remarks
+ * `format`/`formatToString` are pure and total (edit computation never fails
+ * — malformed input yields no edits rather than corrupting the document).
+ * `modify`/`modifyToString` carry a real error channel: navigation failures
+ * against the composed AST raise {@link YamlModificationError}, which — per
+ * the structure-preserving-errors house rule — carries
+ * `diagnostics: ReadonlyArray<YamlDiagnostic>`, never a collapsed `reason`
+ * string.
+ *
+ * @public
+ */
+declare class YamlFormat {
+  private constructor();
+  /**
+   * Compute formatting edits for a YAML document. Non-mutating — apply the
+   * result with `YamlEdit.applyAll` (or use {@link YamlFormat.formatToString}).
+   * Pure and total: malformed input (a fatal parse error) yields `[]` rather
+   * than corrupting the document.
+   *
+   * @remarks
+   * The positional `range` argument takes precedence over
+   * `options?.range` when both are given; either accepts a plain
+   * `{ offset, length }` object as well as a {@link YamlRange} instance, so
+   * callers do not need `YamlRange.make(...)` for the common case.
+   */
+  static format(text: string, range?: YamlRangeLike, options?: YamlFormattingOptions): ReadonlyArray<YamlEdit>;
+  /**
+   * Format `text` and apply the resulting edits in one step
+   * (`YamlEdit.applyAll ∘ format`). Pure and total.
+   */
+  static formatToString(text: string, range?: YamlRangeLike, options?: YamlFormattingOptions): string;
+  /**
+   * Compute the edits that insert, replace, or remove a value at `path`.
+   * Passing `value === undefined` removes the target key/element; a missing
+   * insertion target appends after the last pair/element. Only
+   * scalar-compatible values are supported (matching v3 — arbitrary object
+   * graphs are not recursively lowered into AST nodes). Fails with
+   * {@link YamlModificationError} on a fatal parse error or a structural
+   * navigation mismatch.
+   *
+   * @remarks
+   * `options` is a bare {@link YamlStringifyOptions} — it controls only the
+   * internal re-stringify step, not a range (there is no range to restrict
+   * for a path-targeted modification).
+   */
+  static readonly modify: (text: string, path: YamlPath, value: unknown, options?: YamlStringifyOptions | undefined) => Effect.Effect<readonly YamlEdit[], YamlModificationError, never>;
+  /**
+   * Modify `text` and apply the resulting edits in one step
+   * (`YamlEdit.applyAll ∘ modify`).
+   */
+  static readonly modifyToString: (text: string, path: YamlPath, value: unknown, options?: YamlStringifyOptions | undefined) => Effect.Effect<string, YamlModificationError, never>;
+}
+//#endregion
+//#region src/YamlVisitor.d.ts
+/**
+ * The discriminated union of YAML AST visitor events. Every variant carries
+ * `path` (segments from the document root) and `depth` (zero-based nesting
+ * level); collection/scalar begin events also carry `style` and the optional
+ * `tag`/`anchor`. `Error` carries a materialized {@link YamlDiagnostic} for
+ * every diagnostic recorded while composing the document — fatal or not.
+ *
+ * @public
+ */
+type YamlVisitorEvent = Data.TaggedEnum<{
+  DocumentStart: {
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly directives: ReadonlyArray<{
+      readonly name: string;
+      readonly parameters: ReadonlyArray<string>;
+    }>;
+  };
+  DocumentEnd: {
+    readonly path: YamlPath;
+    readonly depth: number;
+  };
+  MapStart: {
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly style: CollectionStyle;
+    readonly tag?: string;
+    readonly anchor?: string;
+  };
+  MapEnd: {
+    readonly path: YamlPath;
+    readonly depth: number;
+  };
+  SeqStart: {
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly style: CollectionStyle;
+    readonly tag?: string;
+    readonly anchor?: string;
+  };
+  SeqEnd: {
+    readonly path: YamlPath;
+    readonly depth: number;
+  };
+  Pair: {
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly key: unknown;
+    readonly value: unknown;
+  };
+  Scalar: {
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly value: unknown;
+    readonly style: ScalarStyle;
+    readonly tag?: string;
+    readonly anchor?: string;
+  };
+  Alias: {
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly name: string;
+  };
+  Comment: {
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly text: string;
+  };
+  Directive: {
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly name: string;
+    readonly parameters: string;
+  };
+  Error: {
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly diagnostic: YamlDiagnostic;
+  };
+}>;
+/**
+ * Constructors and matchers for the `YamlVisitorEvent` union (e.g.
+ * `YamlVisitorEvent.Scalar({ path, depth, value, style })`,
+ * `YamlVisitorEvent.$is("MapStart")`).
+ *
+ * @public
+ */
+declare const YamlVisitorEvent: {
+  readonly $is: <Tag extends "Alias" | "Comment" | "Directive" | "DocumentEnd" | "DocumentStart" | "Error" | "MapEnd" | "MapStart" | "Pair" | "Scalar" | "SeqEnd" | "SeqStart">(tag: Tag) => (u: unknown) => u is Extract<{
+    readonly _tag: "Alias";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly name: string;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Comment";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly text: string;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Directive";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly name: string;
+    readonly parameters: string;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "DocumentEnd";
+    readonly path: YamlPath;
+    readonly depth: number;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "DocumentStart";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly directives: ReadonlyArray<{
+      readonly name: string;
+      readonly parameters: ReadonlyArray<string>;
+    }>;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Error";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly diagnostic: YamlDiagnostic;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "MapEnd";
+    readonly path: YamlPath;
+    readonly depth: number;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "MapStart";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly style: CollectionStyle;
+    readonly tag?: string | undefined;
+    readonly anchor?: string | undefined;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Pair";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly key: unknown;
+    readonly value: unknown;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Scalar";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly value: unknown;
+    readonly style: ScalarStyle;
+    readonly tag?: string | undefined;
+    readonly anchor?: string | undefined;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "SeqEnd";
+    readonly path: YamlPath;
+    readonly depth: number;
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "SeqStart";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly style: CollectionStyle;
+    readonly tag?: string | undefined;
+    readonly anchor?: string | undefined;
+  }, {
+    readonly _tag: Tag;
+  }>;
+  readonly $match: {
+    <Cases extends {
+      readonly Alias: (args: {
+        readonly _tag: "Alias";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly name: string;
+      }) => any;
+      readonly Comment: (args: {
+        readonly _tag: "Comment";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly text: string;
+      }) => any;
+      readonly Directive: (args: {
+        readonly _tag: "Directive";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly name: string;
+        readonly parameters: string;
+      }) => any;
+      readonly DocumentEnd: (args: {
+        readonly _tag: "DocumentEnd";
+        readonly path: YamlPath;
+        readonly depth: number;
+      }) => any;
+      readonly DocumentStart: (args: {
+        readonly _tag: "DocumentStart";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly directives: ReadonlyArray<{
+          readonly name: string;
+          readonly parameters: ReadonlyArray<string>;
+        }>;
+      }) => any;
+      readonly Error: (args: {
+        readonly _tag: "Error";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly diagnostic: YamlDiagnostic;
+      }) => any;
+      readonly MapEnd: (args: {
+        readonly _tag: "MapEnd";
+        readonly path: YamlPath;
+        readonly depth: number;
+      }) => any;
+      readonly MapStart: (args: {
+        readonly _tag: "MapStart";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly style: CollectionStyle;
+        readonly tag?: string | undefined;
+        readonly anchor?: string | undefined;
+      }) => any;
+      readonly Pair: (args: {
+        readonly _tag: "Pair";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly key: unknown;
+        readonly value: unknown;
+      }) => any;
+      readonly Scalar: (args: {
+        readonly _tag: "Scalar";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly value: unknown;
+        readonly style: ScalarStyle;
+        readonly tag?: string | undefined;
+        readonly anchor?: string | undefined;
+      }) => any;
+      readonly SeqEnd: (args: {
+        readonly _tag: "SeqEnd";
+        readonly path: YamlPath;
+        readonly depth: number;
+      }) => any;
+      readonly SeqStart: (args: {
+        readonly _tag: "SeqStart";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly style: CollectionStyle;
+        readonly tag?: string | undefined;
+        readonly anchor?: string | undefined;
+      }) => any;
+    }>(cases: Cases): (value: {
+      readonly _tag: "Alias";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly name: string;
+    } | {
+      readonly _tag: "Comment";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly text: string;
+    } | {
+      readonly _tag: "Directive";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly name: string;
+      readonly parameters: string;
+    } | {
+      readonly _tag: "DocumentEnd";
+      readonly path: YamlPath;
+      readonly depth: number;
+    } | {
+      readonly _tag: "DocumentStart";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly directives: ReadonlyArray<{
+        readonly name: string;
+        readonly parameters: ReadonlyArray<string>;
+      }>;
+    } | {
+      readonly _tag: "Error";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly diagnostic: YamlDiagnostic;
+    } | {
+      readonly _tag: "MapEnd";
+      readonly path: YamlPath;
+      readonly depth: number;
+    } | {
+      readonly _tag: "MapStart";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly style: CollectionStyle;
+      readonly tag?: string | undefined;
+      readonly anchor?: string | undefined;
+    } | {
+      readonly _tag: "Pair";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly key: unknown;
+      readonly value: unknown;
+    } | {
+      readonly _tag: "Scalar";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly value: unknown;
+      readonly style: ScalarStyle;
+      readonly tag?: string | undefined;
+      readonly anchor?: string | undefined;
+    } | {
+      readonly _tag: "SeqEnd";
+      readonly path: YamlPath;
+      readonly depth: number;
+    } | {
+      readonly _tag: "SeqStart";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly style: CollectionStyle;
+      readonly tag?: string | undefined;
+      readonly anchor?: string | undefined;
+    }) => import("effect/Unify").Unify<ReturnType<Cases["Alias" | "Comment" | "Directive" | "DocumentEnd" | "DocumentStart" | "Error" | "MapEnd" | "MapStart" | "Pair" | "Scalar" | "SeqEnd" | "SeqStart"]>>;
+    <Cases extends {
+      readonly Alias: (args: {
+        readonly _tag: "Alias";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly name: string;
+      }) => any;
+      readonly Comment: (args: {
+        readonly _tag: "Comment";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly text: string;
+      }) => any;
+      readonly Directive: (args: {
+        readonly _tag: "Directive";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly name: string;
+        readonly parameters: string;
+      }) => any;
+      readonly DocumentEnd: (args: {
+        readonly _tag: "DocumentEnd";
+        readonly path: YamlPath;
+        readonly depth: number;
+      }) => any;
+      readonly DocumentStart: (args: {
+        readonly _tag: "DocumentStart";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly directives: ReadonlyArray<{
+          readonly name: string;
+          readonly parameters: ReadonlyArray<string>;
+        }>;
+      }) => any;
+      readonly Error: (args: {
+        readonly _tag: "Error";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly diagnostic: YamlDiagnostic;
+      }) => any;
+      readonly MapEnd: (args: {
+        readonly _tag: "MapEnd";
+        readonly path: YamlPath;
+        readonly depth: number;
+      }) => any;
+      readonly MapStart: (args: {
+        readonly _tag: "MapStart";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly style: CollectionStyle;
+        readonly tag?: string | undefined;
+        readonly anchor?: string | undefined;
+      }) => any;
+      readonly Pair: (args: {
+        readonly _tag: "Pair";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly key: unknown;
+        readonly value: unknown;
+      }) => any;
+      readonly Scalar: (args: {
+        readonly _tag: "Scalar";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly value: unknown;
+        readonly style: ScalarStyle;
+        readonly tag?: string | undefined;
+        readonly anchor?: string | undefined;
+      }) => any;
+      readonly SeqEnd: (args: {
+        readonly _tag: "SeqEnd";
+        readonly path: YamlPath;
+        readonly depth: number;
+      }) => any;
+      readonly SeqStart: (args: {
+        readonly _tag: "SeqStart";
+        readonly path: YamlPath;
+        readonly depth: number;
+        readonly style: CollectionStyle;
+        readonly tag?: string | undefined;
+        readonly anchor?: string | undefined;
+      }) => any;
+    }>(value: {
+      readonly _tag: "Alias";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly name: string;
+    } | {
+      readonly _tag: "Comment";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly text: string;
+    } | {
+      readonly _tag: "Directive";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly name: string;
+      readonly parameters: string;
+    } | {
+      readonly _tag: "DocumentEnd";
+      readonly path: YamlPath;
+      readonly depth: number;
+    } | {
+      readonly _tag: "DocumentStart";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly directives: ReadonlyArray<{
+        readonly name: string;
+        readonly parameters: ReadonlyArray<string>;
+      }>;
+    } | {
+      readonly _tag: "Error";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly diagnostic: YamlDiagnostic;
+    } | {
+      readonly _tag: "MapEnd";
+      readonly path: YamlPath;
+      readonly depth: number;
+    } | {
+      readonly _tag: "MapStart";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly style: CollectionStyle;
+      readonly tag?: string | undefined;
+      readonly anchor?: string | undefined;
+    } | {
+      readonly _tag: "Pair";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly key: unknown;
+      readonly value: unknown;
+    } | {
+      readonly _tag: "Scalar";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly value: unknown;
+      readonly style: ScalarStyle;
+      readonly tag?: string | undefined;
+      readonly anchor?: string | undefined;
+    } | {
+      readonly _tag: "SeqEnd";
+      readonly path: YamlPath;
+      readonly depth: number;
+    } | {
+      readonly _tag: "SeqStart";
+      readonly path: YamlPath;
+      readonly depth: number;
+      readonly style: CollectionStyle;
+      readonly tag?: string | undefined;
+      readonly anchor?: string | undefined;
+    }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Alias" | "Comment" | "Directive" | "DocumentEnd" | "DocumentStart" | "Error" | "MapEnd" | "MapStart" | "Pair" | "Scalar" | "SeqEnd" | "SeqStart"]>>;
+  };
+  readonly Alias: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Alias";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly name: string;
+  }, "_tag">;
+  readonly Comment: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Comment";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly text: string;
+  }, "_tag">;
+  readonly Directive: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Directive";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly name: string;
+    readonly parameters: string;
+  }, "_tag">;
+  readonly DocumentEnd: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "DocumentEnd";
+    readonly path: YamlPath;
+    readonly depth: number;
+  }, "_tag">;
+  readonly DocumentStart: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "DocumentStart";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly directives: ReadonlyArray<{
+      readonly name: string;
+      readonly parameters: ReadonlyArray<string>;
+    }>;
+  }, "_tag">;
+  readonly Error: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Error";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly diagnostic: YamlDiagnostic;
+  }, "_tag">;
+  readonly MapEnd: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "MapEnd";
+    readonly path: YamlPath;
+    readonly depth: number;
+  }, "_tag">;
+  readonly MapStart: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "MapStart";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly style: CollectionStyle;
+    readonly tag?: string | undefined;
+    readonly anchor?: string | undefined;
+  }, "_tag">;
+  readonly Pair: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Pair";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly key: unknown;
+    readonly value: unknown;
+  }, "_tag">;
+  readonly Scalar: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "Scalar";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly value: unknown;
+    readonly style: ScalarStyle;
+    readonly tag?: string | undefined;
+    readonly anchor?: string | undefined;
+  }, "_tag">;
+  readonly SeqEnd: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "SeqEnd";
+    readonly path: YamlPath;
+    readonly depth: number;
+  }, "_tag">;
+  readonly SeqStart: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "SeqStart";
+    readonly path: YamlPath;
+    readonly depth: number;
+    readonly style: CollectionStyle;
+    readonly tag?: string | undefined;
+    readonly anchor?: string | undefined;
+  }, "_tag">;
+};
+/**
+ * SAX-style YAML AST visitor statics. Not instantiable.
+ *
+ * @public
+ */
+declare class YamlVisitor {
+  private constructor();
+  /**
+   * Create a lazy `Stream` of `YamlVisitorEvent` from YAML text, in document
+   * order. Multi-document streams (separated by `---`) produce a separate
+   * `DocumentStart`/`DocumentEnd` pair per document. Events are produced on
+   * demand, so combining with `Stream.take` allows efficient partial scans
+   * of large documents without materializing the whole event sequence.
+   *
+   * @remarks
+   * Infallible at the type level: diagnostics recorded while composing
+   * (fatal or not, including an exceeded `maxAliasCount`, recorded as
+   * `AliasCountExceeded`) surface as `Error` events inside the stream rather
+   * than failing it.
+   */
+  static visit(text: string, options?: YamlParseOptions): Stream.Stream<YamlVisitorEvent>;
+}
+//#endregion
+export { CollectionStyle, ScalarChomp, ScalarStyle, Yaml, YamlAlias, YamlComposerErrorCode, YamlDiagnostic, YamlDirective, YamlDocument, YamlEdit, YamlErrorCode, YamlFormat, YamlFormattingOptions, YamlLexErrorCode, YamlMap, YamlModificationError, YamlModifyErrorCode, YamlNode, YamlPair, YamlParseError, YamlParseErrorCode, YamlParseOptions, type YamlPath, YamlRange, type YamlRangeLike, YamlScalar, type YamlSegment, YamlSeq, YamlStringifyError, YamlStringifyErrorCode, YamlStringifyOptions, YamlVisitor, YamlVisitorEvent };
+//# sourceMappingURL=index.d.ts.map