//#region src/internal/annotations.d.ts
/**
 * Runtime context extension system for Optique parsers.
 *
 * This module provides the annotations system that allows external runtime data
 * to be passed to parsers during the parsing session. This enables use cases like
 * config file fallbacks, environment-based validation, and shared context.
 *
 * @module
 * @since 0.10.0
 */
/**
 * Annotation key symbol for storing data in parser state.
 * @since 0.10.0
 */
declare const annotationKey: unique symbol;
/**
 * Internal marker attached during the first pass of `runWith()` so wrappers
 * with side effects can defer work until two-pass contexts have resolved.
 *
 * @internal
 */
declare const firstPassAnnotationKey: unique symbol;
/**
 * Internal key for preserving primitive parser state values when annotations
 * are injected into non-object states.
 * @internal
 */
declare const annotationStateValueKey: unique symbol;
/**
 * Internal marker key that indicates annotation wrapping was injected by
 * Optique internals for non-object states.
 * @internal
 */
declare const annotationWrapperKey: unique symbol;
/**
 * Annotations that can be passed to parsers during execution.
 * Allows external packages to provide additional data that parsers can access
 * during complete() or parse() phases.
 *
 * @example
 * ```typescript
 * const myDataKey = Symbol.for("@my-package/data");
 * const result = parse(parser, args, {
 *   annotations: {
 *     [myDataKey]: { foo: "bar" }
 *   }
 * });
 * ```
 * @since 0.10.0
 */
type Annotations = Record<symbol, unknown>;
/**
 * Options for parse functions.
 * @since 0.10.0
 */
interface ParseOptions {
  /**
   * Annotations to attach to the parsing session.
   * Parsers can access these annotations via getAnnotations(state).
   */
  readonly annotations?: Annotations;
}
/**
 * Extracts annotations from parser state.
 *
 * @param state Parser state that may contain annotations
 * @returns Annotations object or undefined if no annotations are present
 * @since 0.10.0
 *
 * @example
 * ```typescript
 * const annotations = getAnnotations(state);
 * const myData = annotations?.[myDataKey];
 * ```
 */
declare function getAnnotations(state: unknown): Annotations | undefined;
/**
 * Reattaches annotations to a freshly created array state.
 *
 * Array spread copies elements but drops symbol properties, so parsers that
 * rebuild array states need to copy annotations back explicitly.
 *
 * @param source The original state that may carry annotations.
 * @param target The freshly created array state.
 * @returns The target array, with annotations copied when available.
 * @internal
 */
declare function annotateFreshArray<T>(source: unknown, target: readonly T[]): readonly T[];
/**
 * Propagates annotations from one parser state to another.
 *
 * This is mainly used by parsers that rebuild array states with spread syntax.
 * Array spread copies elements but drops custom symbol properties, so we need
 * to reattach annotations explicitly when present. `inheritAnnotations()`
 * supports primitive and nullish targets via wrapper injection, plus arrays,
 * plain objects, and built-in container/value types that Optique clones
 * explicitly (`Date`, `Map`, `Set`, and `RegExp`). Non-plain custom objects
 * are returned unchanged to avoid mutating shared parser state.
 *
 * @param source The original state that may carry annotations.
 * @param target The new state to receive annotations when it is a supported
 *               target shape.
 * @returns A cloned or wrapped target with annotations copied when available,
 *          or the original unsupported non-plain target unchanged.
 * @since 1.0.0
 */
declare function inheritAnnotations<T>(source: unknown, target: T): T;
/**
 * Returns whether an annotations record carries at least one own symbol key.
 *
 * An annotations object with no own symbol keys is treated as a no-op by the
 * injection pipeline: it should behave identically to omitting the
 * `annotations` option entirely.  `null` and `undefined` are accepted for
 * call-site convenience and always return `false`.
 *
 * @param annotations The annotations record to check.
 * @returns `true` when the record has at least one own symbol key.
 * @internal
 */
declare function hasMeaningfulAnnotations(annotations: Annotations | null | undefined): annotations is Annotations;
/**
 * Injects annotations into parser state while preserving state shape.
 *
 * - Primitive, null, and undefined states are wrapped with internal metadata.
 * - Array states are cloned and annotated without mutating the original.
 * - Plain object states are shallow-cloned with annotations attached.
 * - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
 * - Other non-plain object states are cloned via prototype/descriptors.
 * - If the `annotations` record is nullish or has no own symbol keys, the
 *   state is returned unchanged.
 *
 * @param state The parser state to annotate.
 * @param annotations The annotations to inject.
 * @returns Annotated state.
 * @since 1.0.0
 */
declare function injectAnnotations<TState>(state: TState, annotations: Annotations | null | undefined): TState;
/**
 * Unwraps a primitive-state annotation wrapper injected by Optique internals.
 *
 * @param value Value to potentially unwrap.
 * @returns The unwrapped primitive value when the input is an injected wrapper;
 *          otherwise the original value.
 * @internal
 */
declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
/**
 * Returns whether the given value is an internal primitive-state annotation
 * wrapper that was injected by Optique.
 *
 * @param value Value to check.
 * @returns `true` if the value is an injected internal wrapper.
 * @internal
 */
declare function isInjectedAnnotationWrapper(value: unknown): boolean;
/**
 * Returns whether the given value is an injected annotation state wrapper.
 *
 * This is the public name for Optique's primitive-state annotation wrapper
 * predicate.  Use it when custom parsers need to detect whether annotations
 * were attached by wrapping a primitive or nullish state value.
 *
 * @param value Value to check.
 * @returns `true` if the value is an injected annotation state wrapper.
 * @since 1.0.0
 */
declare function isInjectedAnnotationState(value: unknown): boolean;
/**
 * Unwraps an injected annotation state wrapper when present.
 *
 * This is the public name for Optique's primitive-state annotation unwrapping
 * helper.  It returns the original value unchanged for non-wrapper inputs.
 *
 * @param value Value to potentially unwrap.
 * @returns The unwrapped primitive value when the input is an injected
 *          annotation state wrapper; otherwise the original value.
 * @since 1.0.0
 */
declare function unwrapInjectedAnnotationState<T>(value: T): T;
//#endregion
export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, isInjectedAnnotationWrapper, unwrapInjectedAnnotationState, unwrapInjectedAnnotationWrapper };