/**
 * The project code graph — every `crew.repo` member of one project in ONE wicked-estate database.
 *
 * # What changed to make this possible
 *
 * One estate database used to hold exactly one repo. SymbolIds embed the repo-relative path, so two
 * repos that both contain `src/index.ts` mint identical file rows AND identical symbol ids: the
 * second index overwrote the first and said nothing. `wicked-estate index <path> --repo <label>`
 * (wicked-estate#117) namespaces every path as `<label>/…`, so N repos co-exist, each queryable,
 * with a guard that refuses — before a row is written — any index that would overwrite another
 * repo's content.
 *
 * # THE LIMIT
 *
 * CO-LOCATION IS NOT LINKAGE. estate resolves edges within a labelled repo's own nodes, exactly as
 * if each repo sat in its own database. `studio → wicked-crew-api-types → crew` does not traverse.
 * What this module federates is per-repo results into one answer with the repo named on every hit —
 * which is genuinely useful ("who calls `record`, anywhere in this project") and is NOT a cross-repo
 * dependency trace. Every response carries `linkage: 'co-located'` and {@link CO_LOCATION_NOTE} so a
 * consumer cannot mistake one for the other.
 *
 * # Why the estate binary is capability-PROBED before anything is indexed
 *
 * `wicked-estate 0.14.4` — the version installed on this machine while this was written — accepts
 * `--repo`, IGNORES it, and exits 0. Indexing three repos through it produces a database holding
 * only the third, with no error anywhere and results that look perfectly healthy. That is the exact
 * silent-loss failure the labelling work exists to end, reachable by nothing worse than a stale
 * binary on PATH. So the flag's support is established from the binary that will actually run,
 * before the first index (help text), and confirmed from the database afterwards (the labelled repo
 * registry `stats` prints) — a claim, then evidence.
 *
 * # Honest degradation
 *
 * Every path out of here names its cause. A project with no repo members, one whose graph was never
 * built, one whose member repo the registry no longer knows, an addon too old to publish
 * `code_graph_db`, and a CURRENT engine that resolved no repo-graph root at all
 * (`CodeGraphRootUnresolvableError` → the routes' 503; wicked-core#406) are five different
 * situations with five different remedies; collapsing them into an empty result set is the failure
 * estate's own R3 rule exists to prevent, and it is the failure FINDING-069 actually shipped.
 */
import type { CoreAdapter } from '../core/adapter.js';
import type { ProjectBlastRadius, ProjectGraphAction, ProjectGraphHit, ProjectGraphRefreshResult, ProjectGraphRepoCount, ProjectGraphSearch, ProjectGraphStatus } from '../core/types.js';
/** The sentence every project-graph response carries. Stated on the wire, not just in this file. */
export declare const CO_LOCATION_NOTE: string;
/**
 * The second sentence `/graph/search` carries, and only it.
 *
 * `matches: []` from an exact-name resolver against a healthy graph is the empty-result-that-reads-
 * as-an-answer this whole surface is built to refuse: a caller who typed half a name is told
 * "nothing in this project", which is false. estate's `resolve` has no substring mode (the header
 * on {@link projectSymbolSearch} argues why a `nodes --json` dump is not the answer), so the
 * matching RULE goes on the wire instead of a matching mode that does not exist.
 */
export declare const EXACT_NAME_NOTE: string;
/** `wicked-estate`, overridable exactly as `WICKED_CORE_EXE` overrides `wicked-core` in routes.ts.
 *  Exported (DES-L8 PR-8D) so the repo-graph route's `stats` spawn rides the same override the
 *  project-graph refresh and its test stub already use — one spelling of which binary answers. */
export declare function estateExe(env?: NodeJS.ProcessEnv): string;
/**
 * The whole-graph counts from `wicked-estate stats --db` stdout (`nodes=N edges=M files=F …`, the
 * first line estate prints — `main.rs`'s `stats` summary). `undefined` when the line does not parse
 * (an older/newer estate, an error message): the caller leaves `CodeGraphData.totals` ABSENT.
 * Shared by the repo-graph route (routes.ts) and the chat-scope liveness check (crew#642).
 */
export declare function parseEstateTotals(stdout: string): {
    nodes: number;
    edges: number;
    files: number;
} | undefined;
/**
 * Does the `wicked-estate` that will actually run support `--repo`?
 *
 * A version comparison would be the obvious probe and the wrong one: it asks a string on disk
 * instead of the binary on PATH, and a locally built or vendored estate can carry any version it
 * likes. The usage banner is printed by the same binary that would do the indexing.
 */
export declare function estateSupportsMultiRepo(env?: NodeJS.ProcessEnv): Promise<boolean>;
/**
 * The evidence check failed: the binary took `--repo` and dropped it.
 *
 * A distinct type because it is NOT a per-repo failure and must not be collected as one. It is the
 * same fact the capability probe establishes — this binary cannot co-locate — discovered one step
 * later, and the only safe response is the probe's: stop, before the next repo's index overwrites
 * the rows just written. Recording it in `failed` and continuing runs a full index per member, each
 * clobbering the last, while the message on every entry claims the opposite.
 */
export declare class EstateDroppedRepoLabelError extends Error {
    constructor(message: string);
}
/**
 * Thrown when the running addon predates `code_graph_db` on the repo record. Mapped to 501: this is
 * a capability gap in the engine, not a bad request.
 *
 * WHY this surface gates on a field it does not itself use. The project graph lives in crew's own
 * state directory and is built from `root_path`, so it could be built against any addon. But
 * `code_graph_db` is the engine's statement that it can vouch for where a repo's graph lives, and
 * `/repos/:id/graph` HARD-THROWS without it (repoPaths.ts, deliberately — a local re-derivation is
 * what FINDING-069 was). Quietly serving a project graph on a daemon whose per-repo graph surface
 * cannot answer would leave two graph endpoints disagreeing about whether this repo has a graph at
 * all, and the operator's real problem — a stale addon — unmentioned.
 */
export declare class ProjectGraphEngineTooOldError extends Error {
    readonly cause: string;
    constructor(cause: string);
}
/** Read the project graph's standing without touching it. */
export declare function projectGraphStatus(adapter: CoreAdapter, projectId: string, env?: NodeJS.ProcessEnv): Promise<ProjectGraphStatus>;
/** What a refresh was asked to do, and where it may say things. Both optional, both additive. */
export interface RefreshOptions {
    /**
     * Bypass the clean-HEAD skip for every member repo AND pass `--force` to `wicked-estate index`.
     * The migration path: after a wicked-estate upgrade, an UNCHANGED repo never re-indexes under
     * the plain rules, so its rows keep the old binary's id scheme and unresolved accounting until
     * its HEAD happens to move. Costs a full rebuild — the same bound as the project's first build.
     */
    force?: boolean;
    /** Receives one line per index run that wrote to stderr (estate's migration notice, warnings). */
    log?: (msg: string) => void;
}
export declare function refreshProjectGraph(adapter: CoreAdapter, projectId: string, env?: NodeJS.ProcessEnv, opts?: RefreshOptions): Promise<ProjectGraphRefreshResult>;
/**
 * Passed to the engine as `LaunchOptions.projectGraph`. `repoLabel` names this run's repo inside
 * the co-located graph so the engine can confirm the graph actually holds it; a repo-less run
 * carries no label because it has no own repo to confirm.
 */
export interface ProjectGraphBinding {
    dbPath: string;
    repoLabel?: string;
}
/**
 * What a launch decided about the project graph, and why. The `reason` is carried on BOTH outcomes
 * because "you got the project graph" and "you got the repo graph instead, because X" are equally
 * worth saying, and the operator asking "why can't this run see the sibling repo" needs the second
 * one to have been recorded somewhere.
 */
export interface ProjectGraphBindingDecision {
    /** The binding to hand the engine; `null` ⇒ the run keeps whatever graph it would have had. */
    binding: ProjectGraphBinding | null;
    /** One sentence: what the run got, and what would change it. */
    reason: string;
    /** The UI action that would change a `binding: null` outcome, when one would (F-2R2-008):
     *  `projects.graph.refresh` = build/refresh the project graph from the project page. */
    action?: ProjectGraphAction;
}
/**
 * WHO is asking for the binding — a governed run or a chat. The two degrade to different things
 * (a chat has no worktree and no "own repo", it keeps reading the scoped roots directly), and
 * F-2R2-008 recorded a 9-repo project chat being told "this repo-less run gets no code graph".
 */
export type BindingSubject = 'run' | 'chat';
export interface ResolveBindingOptions {
    /** Default `'run'`. */
    subject?: BindingSubject;
}
/**
 * Decide which code graph a run launched into `projectId` should be bound to.
 *
 * # This never indexes
 *
 * A refresh is `wicked-estate index` per member repo, bounded at ten minutes EACH. Doing that
 * inside a launch would turn "start a run" into an unannounced multi-repo indexing job that blocks
 * the response, and the first thing an operator would learn about it is a request that appears to
 * hang. So a missing or stale graph DEGRADES the run to the per-repo graph and says so; refreshing
 * stays an explicit `POST /projects/:id/graph/refresh`.
 *
 * # Why the run's OWN repo decides it
 *
 * The engine independently verifies whatever it is handed and falls back on its own, so this
 * function cannot make a run unsafe — but it can make one confusing, and it has information the
 * engine does not. `projectGraphStatus` knows a repo was attached after the last refresh, that its
 * registry root moved out from under the label, that its member ref is dangling. Declining HERE,
 * with that cause attached, is the difference between an operator reading "attached since the last
 * refresh — not in the graph yet" and reading the engine's generic "no files under that label".
 *
 * The rule itself is the engine's, restated on this side: bind when the graph holds THIS RUN'S
 * repo. A graph missing some OTHER member is still bound — it is strictly more than the per-repo
 * graph, and the run's own code is described correctly. A graph missing THIS repo is not, because
 * its answers about the worktree the worker is sitting in would all be "nothing found".
 */
export declare function resolveProjectGraphBinding(adapter: CoreAdapter, projectId: string, repoRef: string | undefined, env?: NodeJS.ProcessEnv, opts?: ResolveBindingOptions): Promise<ProjectGraphBindingDecision>;
/**
 * A query can run only against a graph that exists and holds at least one MEMBER repo. Anything
 * else is returned as the status, so the caller gets the cause and the remedy instead of `[]`.
 */
export type Queryable = {
    ok: true;
    dbPath: string;
    status: ProjectGraphStatus;
    labels: Map<string, string>;
} | {
    ok: false;
    status: ProjectGraphStatus;
};
export declare function queryable(adapter: CoreAdapter, projectId: string, env?: NodeJS.ProcessEnv): Promise<Queryable>;
/**
 * estate's raw hit list → attributed hits plus their per-repo counts. THE federation step, and the
 * only place a result acquires its provenance — exported so the attribution rules are testable
 * without a graph on disk, which is what makes the stale-label exclusion below coverable at all.
 */
export declare function attributeHits(raw: unknown, labels: Map<string, string>): {
    hits: ProjectGraphHit[];
    byRepo: ProjectGraphRepoCount[];
};
/**
 * `wicked-estate blast-radius --json`, EVERY page of it (operator ruling "full graph"; estate#279,
 * wicked-estate 0.28.0+). estate pages a wide answer: a page names the rest with `next_cursor`
 * (null on the last page), and `--cursor` returns the next rows of the SAME answer. The pages'
 * `dependents` are joined; every other field is the LAST page's, so once every page is in,
 * `truncated_dependents` says only what the walk itself cut (and `next_cursor` is null). A cursor
 * still unread at the page cap is left on the answer with that page's `truncated_dependents`, so
 * the unread rows read as cut, never as absent. An estate that does not page sends no
 * `next_cursor`: one call, its JSON unchanged. Shared by the repo route and the project route.
 */
export declare function readBlastRadiusPages(exe: string, name: string, dbPath: string, opts: {
    timeout: number;
    cwd?: string;
}): Promise<Record<string, unknown>>;
/** Dependents of a symbol across every member repo, each hit attributed to the repo it is in. */
export declare function projectBlastRadius(q: Extract<Queryable, {
    ok: true;
}>, name: string, env?: NodeJS.ProcessEnv): Promise<ProjectBlastRadius>;
/**
 * Symbol search across every member repo — exact name, which is what estate's `resolve` answers.
 *
 * Not a substring search on purpose: the only estate primitive that would give one is a full
 * `nodes --json` dump filtered daemon-side, whose cost scales with the whole project rather than
 * with the query, and which would need a cap whose truncation is itself a silent wrong answer.
 * `resolve` is the same primitive the repo-scoped surface uses to turn a name into SymbolIds; run
 * against a co-located graph it returns every repo's matches in one call.
 */
export declare function projectSymbolSearch(q: Extract<Queryable, {
    ok: true;
}>, name: string, env?: NodeJS.ProcessEnv): Promise<ProjectGraphSearch>;
//# sourceMappingURL=graph.d.ts.map