/**
 * Provider-neutral Repository Explorer (P6-05, DESIGN.md §18, §11,
 * PRD FR-081, FR-083–FR-086, FR-088, FR-091; NFR-004, NFR-005, NFR-007).
 *
 * The Explorer is the single non-Adapter consumer of the Repository
 * Capability contract. It owns canonical repository-path handling,
 * deterministic breadth-first traversal, duplicate-directory
 * protection, and local Search/File `--max-chars` projection. It
 * constructs canonical Capability requests, hands them to shared
 * execution, and projects the normalized results.
 *
 * Boundary rules (ARCHITECTURE.md §2, NFR-004):
 *   - Imports ONLY provider-neutral Repository Capability types and
 *     shared `executeRepositoryOperation` / `ExecutionDependencies`,
 *     plus the normalized `ValidationError`.
 *   - Imports NO concrete Provider Adapter, MCP/UTCP client, raw tool
 *     name, or Provider response type. Provider-specific facts (ZRead
 *     grammar, credentials, transports) remain Adapter-internal.
 *   - Owns canonicalization, BFS, and projection; never owns
 *     transport, credentials, Provider selection, or command
 *     presentation.
 *
 * Fixed ordering (DESIGN.md §18):
 *   1. Apply Explorer-level defaults (Search `language`, Tree
 *      `depth`) and canonicalize paths.
 *   2. Validate `repository` (at-least-one-slash), `query`
 *      (non-whitespace), `language`, and `depth`.
 *   3. Construct the canonical Capability request.
 *   4. Delegate to `executeRepositoryOperation`, which runs
 *      `operation.validate`, `operation.cacheIdentity`, the
 *      provider-partitioned cache read, ordered legacy candidates,
 *      retry-wrapped invoke, and the normalized cache write.
 *   5. Apply post-execution `--max-chars` projection (Search/File
 *      only). Tree is never character-limited.
 *
 * `--max-chars` is post-execution projection. It never appears in
 * the canonical request, the cache identity, or the cache itself.
 */
import type { RepositoryCapability, RepositoryFileResult, RepositorySearchResult, RepositoryTreeResult } from "../capabilities/repository.js";
import { type ExecutionDependencies, type RetryPolicy } from "../lib/execution.js";
import { type LadderRule } from "../lib/output-budget.js";
/**
 * The kind of path being canonicalized. Governs root handling and
 * the File-only leading `./` convenience.
 */
export type RepositoryPathKind = "file" | "directory";
/**
 * Canonicalize a repository-relative POSIX path.
 *
 * Rules (DESIGN.md §18, technical plan):
 *   - Backslashes (`\\`) and ASCII control characters (C0 plus DEL,
 *     code points 0–31 and 127) always throw `ValidationError`.
 *   - Whole-string root aliases (`undefined`, `""`, `"/"`, `"."`)
 *     map to root (`""`). For File (`kind: "file"`), root is
 *     invalid and throws.
 *   - File accepts a single leading `./` and any leading `/` as
 *     convenience; both are stripped. Directory does NOT get the
 *     leading `./` convenience (a leading `.` segment is unsafe and
 *     is rejected below); leading `/` is naturally stripped by the
 *     empty-segment collapse.
 *   - Repeated `/` collapses and trailing `/` is removed via the
 *     empty-segment skip.
 *   - Actual `.` or `..` segments at any position throw.
 *   - Percent escapes are never decoded.
 *
 * Returns the canonical repository-relative POSIX path. `""` is the
 * repository root.
 */
export declare function canonicalizeRepositoryPath(input: string | undefined, kind: RepositoryPathKind): string;
/** The repo-search Output Budget ladder (ordered; see ADR-0007 T4). */
export declare const REPO_SEARCH_LADDER: readonly [LadderRule<unknown>, LadderRule<unknown>];
/** The repo-read Output Budget ladder (ordered; see ADR-0007 T4). */
export declare const REPO_READ_LADDER: readonly [LadderRule<unknown>];
/**
 * Request shape accepted by {@link explorerSearch}. `language` is
 * optional; the Explorer applies the `"en"` default before the
 * Capability sees the request. `repository` and `query` preserve
 * their exact case and text.
 */
export interface ExplorerSearchRequest {
    readonly repository: string;
    readonly query: string;
    readonly language?: "en" | "zh";
}
/**
 * Request shape accepted by {@link explorerReadFile}. `path` is
 * canonicalized through the File rules: leading `./` and `/` are
 * stripped, root is rejected, and unsafe segments throw.
 */
export interface ExplorerReadFileRequest {
    readonly repository: string;
    readonly path: string;
}
/**
 * Request shape accepted by {@link explorerTree}. `path` is
 * canonicalized through the Directory/Tree rules:
 * omitted/empty/`/`/`.` map to root, and unsafe segments throw.
 * `depth` defaults to 1.
 */
export interface ExplorerTreeRequest {
    readonly repository: string;
    readonly path?: string;
    readonly depth?: number;
}
/**
 * Options for Search and File. `noCache` and `retryPolicy` are
 * forwarded to `executeRepositoryOperation`. Issue #105: `maxChars` is
 * intentionally absent — the retired per-field projection is deleted and
 * a smuggled value fails loud; the whole-envelope budget runs at the
 * dispatcher seam.
 */
export interface ExplorerOptions {
    readonly noCache?: boolean;
    readonly retryPolicy?: RetryPolicy;
}
/**
 * Options for Tree. Tree is never character-limited; `maxChars` is
 * intentionally absent.
 */
export interface ExplorerTreeOptions {
    readonly noCache?: boolean;
    readonly retryPolicy?: RetryPolicy;
}
/**
 * Provider-neutral Repository Search (DESIGN.md §18, PRD FR-081,
 * FR-083). Applies the `language` default, validates `repository`
 * (at-least-one-slash) and `query` (non-whitespace), constructs the
 * canonical request, delegates to shared execution, and returns the
 * normalized result verbatim (issue #105: the per-field `--max-chars`
 * projection is deleted; the whole-envelope budget runs at the
 * dispatcher seam).
 *
 * Defaults and canonicalization precede `operation.validate` /
 * `operation.cacheIdentity`. The Provider sees the canonical
 * request; the Explorer never widens into Provider-specific fields.
 */
export declare function explorerSearch(capability: RepositoryCapability, request: ExplorerSearchRequest, options: ExplorerOptions, dependencies: ExecutionDependencies): Promise<RepositorySearchResult>;
/**
 * Provider-neutral Repository File read (DESIGN.md §18, PRD FR-086).
 * Canonicalizes the File path (root rejected, leading `./` and `/`
 * stripped, unsafe segments throw), delegates to shared execution,
 * and returns the normalized result verbatim (issue #105: the
 * per-field `--max-chars` content budget is deleted).
 */
export declare function explorerReadFile(capability: RepositoryCapability, request: ExplorerReadFileRequest, options: ExplorerOptions, dependencies: ExecutionDependencies): Promise<RepositoryFileResult>;
/**
 * Provider-neutral Repository Tree (DESIGN.md §18, PRD FR-088).
 * Canonicalizes the starting path (root allowed), projects depth
 * (default 1, finite positive integer), and drives a deterministic
 * breadth-first traversal that preserves Provider sibling order,
 * requests each canonical directory at most once, and never returns
 * partial success. Tree is never character-limited.
 */
export declare function explorerTree(capability: RepositoryCapability, request: ExplorerTreeRequest, options: ExplorerTreeOptions, dependencies: ExecutionDependencies): Promise<RepositoryTreeResult>;
//# sourceMappingURL=repository-explorer.d.ts.map