/**
 * Shared types and helpers for the standardized discovery envelope.
 *
 * All discovery operations (query.match, comments.list, trackChanges.list,
 * lists.list, find) return a `DiscoveryResult<DiscoveryItem<TDomain>>` -
 * a uniform envelope with pagination, revision tracking, and mutation-ready
 * handles.
 *
 * See plans/master-api-unification-plan.md for design rationale.
 */
export type KnownTargetKind = 'text' | 'node' | 'list' | 'comment' | 'trackedChange' | 'table' | 'tableCell' | 'tableOfContents' | 'section' | 'sdt' | 'field';
export type ExtensionTargetKind = `ext:${string}`;
export type TargetKind = KnownTargetKind | ExtensionTargetKind;
export type RefStability = 'stable' | 'ephemeral';
export interface ResolvedHandle {
    /** Mutation-ready ref string (e.g., V3 encoded ref, stable nodeId, 'comment:<id>'). */
    ref: string;
    /** Whether the ref survives across revisions. */
    refStability: RefStability;
    /** Semantic type of the target this handle points to. */
    targetKind: TargetKind;
}
export interface PageInfo {
    /** Maximum items requested per page. */
    limit: number;
    /** Zero-based offset into the total result set. */
    offset: number;
    /** Actual number of items returned in this page. Invariant: `returned === items.length`. */
    returned: number;
}
/**
 * A single discoverable entity with a mutation-ready handle and domain payload.
 *
 * `TDomain` carries the operation-specific fields (e.g., `snippet`, `address`,
 * `blocks` for query.match; `status`, `text` for comments.list).
 */
export type DiscoveryItem<TDomain> = {
    /** Deterministic identity, scoped to the evaluated revision. */
    id: string;
    /** Mutation-ready handle for chaining into `mutations.apply` or direct operations. */
    handle: ResolvedHandle;
} & TDomain;
/**
 * Standard discovery result envelope returned by all discovery operations.
 *
 * Provides revision tracking, total count, paginated items, and page metadata.
 * The optional `TMeta` type parameter allows operation-specific metadata
 * (e.g., `query.match` uses it for `effectiveResolved`). Defaults to `undefined`
 * for operations that don't use it: backwards compatible.
 */
export interface DiscoveryResult<TItem, TMeta = undefined> {
    /** Document revision at which the query was evaluated. */
    evaluatedRevision: string;
    /** Total number of matching entities (before pagination). */
    total: number;
    /** Paginated list of discovery items. */
    items: TItem[];
    /** Pagination metadata. Invariant: `page.returned === items.length`. */
    page: PageInfo;
    /** Operation-specific metadata. Present only when `TMeta` is specified. */
    meta?: TMeta;
}
/**
 * Convenience alias: `DiscoveryResult` wrapping `DiscoveryItem<TDomain>`.
 *
 * This is the return type of every standardized discovery operation.
 */
export type DiscoveryOutput<TDomain, TMeta = undefined> = DiscoveryResult<DiscoveryItem<TDomain>, TMeta>;
/**
 * Constructs a {@link ResolvedHandle}.
 */
export declare function buildResolvedHandle(ref: string, refStability: RefStability, targetKind: TargetKind): ResolvedHandle;
/**
 * Constructs a {@link DiscoveryItem} from an id, handle, and domain payload.
 */
export declare function buildDiscoveryItem<TDomain>(id: string, handle: ResolvedHandle, domain: TDomain): DiscoveryItem<TDomain>;
/**
 * Constructs a {@link DiscoveryResult} with invariant enforcement.
 *
 * @throws {Error} if `page.returned !== items.length`
 */
export declare function buildDiscoveryResult<TItem, TMeta = undefined>(params: {
    evaluatedRevision: string;
    total: number;
    items: TItem[];
    page: PageInfo;
    meta?: TMeta;
}): DiscoveryResult<TItem, TMeta>;
/**
 * Derives an apply-ready target from a discovery item, suitable for passing to
 * `mutations.apply` step `where` clauses.
 */
export declare function toApplyTarget(item: DiscoveryItem<unknown>, evaluatedRevision: string): {
    where: {
        by: 'ref';
        ref: string;
    };
    expectedRevision: string;
};
//# sourceMappingURL=discovery.d.ts.map