import { z } from 'zod';
import { GitRangeModeSchema } from '../../git/types.js';
import type { GitFileStatus, GitRange, GitRangeMode } from '../../git/types.js';
import type { EntityChangeFlags, EntityChangeType, EntityDiagnostic, EntityIndexMode, EntityKind, LineageMatchReason } from './types.js';
import type { OccTestReason } from '../tests.js';
import type { ParserEvidenceSummary } from '../types.js';
import type { ReadCodeSourceResult } from '../source.js';
import type { TokenizerName } from '../../tokens.js';
import type { EntityEvidenceGapSummary } from './evidence.js';
import type { SourceInlineBlock, SourceInlineRange } from '../source-inline.js';
import type { TokenBudgetRefusal } from '../narrowing.js';
/**
 * The public entity-intelligence contract.
 *
 * Inputs are Zod schemas because they arrive from a CLI parser or an MCP client
 * and must be validated at the boundary. Results are plain types: OCC
 * constructs them itself, so a schema there would only re-check its own work.
 */
export declare const OccEntityQuerySchema: z.ZodObject<{
    name: z.ZodString;
    relativePath: z.ZodOptional<z.ZodString>;
    kind: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
        function: "function";
        file: "file";
        enum: "enum";
        type: "type";
        module: "module";
        class: "class";
        interface: "interface";
        variable: "variable";
        parameter: "parameter";
        method: "method";
        other: "other";
    }>, z.ZodEnum<{
        object: "object";
        array: "array";
        "array-item": "array-item";
        property: "property";
        section: "section";
        table: "table";
        "array-table": "array-table";
        heading: "heading";
        row: "row";
        document: "document";
    }>, z.ZodEnum<{
        test: "test";
        test_suite: "test_suite";
    }>]>>;
    ref: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
export type OccEntityQuery = z.infer<typeof OccEntityQuerySchema>;
export interface OccEntityRef {
    lineageId: string;
    /** Present when the entity exists in the current index; absent at a past ref. */
    nodeId?: string;
    name: string;
    qualifiedName?: string;
    kind: EntityKind;
    relativePath: string;
    startLine: number;
    endLine: number;
    signature?: string;
    containerName?: string;
    isExported: boolean;
    isTest: boolean;
    /** Why the entity was classified as a test, when it was. */
    testReasons?: OccTestReason[];
    /**
     * True when the lineage id was synthesized for something git has never seen —
     * an uncommitted or untracked entity. Such an id is stable within a working
     * tree but is not history, and must not be persisted as though it were.
     */
    provisional?: boolean;
    /**
     * True when the id was synthesized because the *index* is degraded, not
     * because the entity is new.
     *
     * A bound-exhausted index has no lineage for entities it never reached, and
     * those are indistinguishable from genuinely new ones by lineage alone. The
     * two must not share a flag: reporting a committed entity as `provisional`
     * turns a resource limit into a false claim about the working tree.
     */
    indeterminate?: boolean;
}
/**
 * A durable lineage handle as an *input*.
 *
 * The version prefix is part of the pattern so a handle minted under a future
 * `ENTITY_LINEAGE_ID_VERSION` still parses here and can be refused with a
 * precise `lineage-version-mismatch` instead of a generic validation error —
 * staleness is detectable from the string alone, and the resolver must get the
 * chance to say so.
 */
export declare const OccEntityLineageHandleSchema: z.ZodObject<{
    lineageId: z.ZodString;
    ref: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
export type OccEntityLineageHandle = z.infer<typeof OccEntityLineageHandleSchema>;
export declare const OccEntityErrorCodeSchema: z.ZodEnum<{
    "not-a-repo": "not-a-repo";
    "git-failed": "git-failed";
    aborted: "aborted";
    "invalid-ref": "invalid-ref";
    "invalid-input": "invalid-input";
    "invalid-path": "invalid-path";
    "path-escape": "path-escape";
    "unsupported-language": "unsupported-language";
    "budget-exceeded": "budget-exceeded";
}>;
export type OccEntityErrorCode = z.infer<typeof OccEntityErrorCodeSchema>;
/** A miss and an ambiguity are ordinary values here, never exceptions. */
type OccEntityErrorOutcome = {
    status: 'error';
    query?: OccEntityQuery;
    code: OccEntityErrorCode;
    message: string;
} & ({
    refused?: undefined;
} | TokenBudgetRefusal);
export type OccEntityOutcome<TPayload> = ({
    status: 'resolved';
    query: OccEntityQuery;
} & TPayload) | {
    status: 'not_found';
    query: OccEntityQuery;
    candidates: OccEntityRef[];
    message: string;
} | {
    status: 'ambiguous';
    query: OccEntityQuery;
    candidates: OccEntityRef[];
    message: string;
} | OccEntityErrorOutcome;
export declare const OccEntitySearchOptionsSchema: z.ZodObject<{
    limit: z.ZodOptional<z.ZodNumber>;
    kind: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
        function: "function";
        file: "file";
        enum: "enum";
        type: "type";
        module: "module";
        class: "class";
        interface: "interface";
        variable: "variable";
        parameter: "parameter";
        method: "method";
        other: "other";
    }>, z.ZodEnum<{
        object: "object";
        array: "array";
        "array-item": "array-item";
        property: "property";
        section: "section";
        table: "table";
        "array-table": "array-table";
        heading: "heading";
        row: "row";
        document: "document";
    }>, z.ZodEnum<{
        test: "test";
        test_suite: "test_suite";
    }>]>>;
    relativePath: z.ZodOptional<z.ZodString>;
    formats: z.ZodOptional<z.ZodBoolean>;
    includeTests: z.ZodOptional<z.ZodBoolean>;
    fuzzy: z.ZodOptional<z.ZodBoolean>;
}, z.core.$strip>;
export type OccEntitySearchOptions = z.infer<typeof OccEntitySearchOptionsSchema>;
/** Measured search envelope; the legacy `search()` array remains available. */
export interface OccEntitySearchResult {
    entities: OccEntityRef[];
    /** Matches observed before applying the display limit. */
    totalMatches: number;
    limit: number;
    /** True only when matching entities were omitted by `limit`. */
    truncated: boolean;
    honesty: {
        freshness: {
            fresh: boolean;
            reasons: OccEntityFreshness['reasons'];
            workingTreeMeasured: boolean;
        };
        truncation: {
            /** Index bounds or this result's display limit omitted evidence. */
            truncated: boolean;
            reasons: EntityDiagnostic[];
            omitted: number;
        };
        coverage: {
            entitiesConsidered: number;
            entitiesMatched: number;
            entitiesReturned: number;
        };
        ambiguityCount: number;
        evidenceGaps: EntityEvidenceGapSummary;
    };
}
export interface OccEntitySourceOptions {
    tokenizer?: TokenizerName;
    signal?: AbortSignal;
}
/** The standard evidence footer attached to targeted source reads. */
export interface OccEntitySourceHonesty {
    freshness: {
        fresh: boolean;
        reasons: OccEntityFreshness['reasons'];
        workingTreeMeasured: boolean;
    };
    truncation: {
        truncated: boolean;
        reasons: EntityDiagnostic[];
        omitted: number;
    };
    coverage: {
        indexNodesConsidered: number;
        candidatesMatched: number;
        sourceRead: boolean;
    };
    ambiguityCount: number;
    evidenceGaps: EntityEvidenceGapSummary;
}
type SourceReadWithHonesty<T extends ReadCodeSourceResult> = T extends {
    status: 'resolved';
} ? T & {
    tokens: number;
    tokenizer: TokenizerName;
    honesty: OccEntitySourceHonesty;
} : T & {
    honesty: OccEntitySourceHonesty;
};
/** One verbatim symbol read, or the existing typed miss/ambiguity/error arms. */
export type OccEntitySourceResult = SourceReadWithHonesty<ReadCodeSourceResult>;
export declare const OccEntityDiffOptionsSchema: z.ZodObject<{
    base: z.ZodOptional<z.ZodString>;
    head: z.ZodOptional<z.ZodString>;
    staged: z.ZodOptional<z.ZodBoolean>;
    relativePath: z.ZodOptional<z.ZodString>;
    maxEntities: z.ZodOptional<z.ZodNumber>;
    rangeMode: z.ZodOptional<z.ZodEnum<{
        exact: "exact";
        "merge-base": "merge-base";
    }>>;
    formats: z.ZodOptional<z.ZodBoolean>;
}, z.core.$strip>;
export type OccEntityDiffOptions = z.infer<typeof OccEntityDiffOptionsSchema>;
/** Programmatic-only controls that are deliberately absent from the wire schema. */
export interface OccEntityDiffRuntimeOptions extends OccEntityDiffOptions {
    signal?: AbortSignal;
    /** Attach reverse-test and module-seam verification obligations to the diff. */
    obligations?: boolean;
}
export interface OccEntityChange {
    /** `modified_cosmetic` is decodable legacy-only; current producers do not emit it. */
    changeType: EntityChangeType;
    /** True, false, or null when no comparable evidence existed on both sides. */
    structuralChange: boolean | null;
    lineageId?: string;
    confidence: number;
    matchReason: LineageMatchReason;
    previous?: OccEntityRef;
    current?: OccEntityRef;
    flags: EntityChangeFlags;
}
export type OccEntityDiffSemanticVerdict = 'logic-change' | 'semantic-no-op' | 'unknown';
export type OccEntityEvidenceCoverage = 'complete' | 'partial' | 'unavailable';
/**
 * The legacy semantic claim OCC can prove from the entity records emitted with
 * one diff.
 *
 * This is deliberately not a whole-file or whole-diff no-op proof. In
 * particular, a `semantic-no-op` here says only that the emitted entity
 * records and their hashes contain no proved structural change. Consumers
 * that need a no-change gate must use `OccWholeDiffSemanticSummary`.
 */
export interface OccEntityDiffSemanticSummary {
    /** Optional for 0.17.1 source compatibility; present in 0.17.2 results. */
    scope?: 'entity-records';
    verdict: OccEntityDiffSemanticVerdict;
    coverage: OccEntityEvidenceCoverage;
    counts: {
        logic: number;
        cosmetic: number;
        unknown: number;
    };
    evidenceGaps: {
        truncated: boolean;
        omitted: number;
        unknownStructuralChanges: number;
        diagnostics: EntityDiagnostic[];
    };
}
/**
 * Decoder for current and persisted whole-diff proof receipts. V1 is unsafe
 * for positive semantic-no-op decisions; V1-V3 remain decodable so consumers
 * can reject or migrate them explicitly instead of losing their provenance.
 */
export declare const OccWholeDiffProofSchema: z.ZodEnum<{
    "whole-file-cst-v1": "whole-file-cst-v1";
    "whole-file-cst-v2": "whole-file-cst-v2";
    "whole-file-cst-v3": "whole-file-cst-v3";
    "whole-file-cst-v4": "whole-file-cst-v4";
}>;
export type OccWholeDiffProof = z.infer<typeof OccWholeDiffProofSchema>;
export type OccWholeDiffSemanticVerdict = 'logic-change'
/** File-level proof that only admitted trivia changed. Aggregates use `semantic-no-op`. */
 | 'cosmetic-change'
/** Current for an exhaustive empty or all-cosmetic whole-diff summary; file rows retain this as a legacy arm. */
 | 'semantic-no-op' | 'unknown';
/** Why one raw changed-file ledger row received its verdict. */
export type OccWholeDiffFileBasis = 
/** V4 emits this only after the separate trivia policy proves the grammar safe. */
'whitespace-only' | 'whitespace-significance-unverified' | 'nontrivia-syntax-change' | 'path-topology-change' | 'comment-only-change' | 'directive-comment-present' | 'byte-order-mark-change' | 'unsupported-language' | 'grammar-unavailable' | 'parse-error' | 'binary' | 'blob-unavailable' | 'resource-bound' | 'working-tree-read-failed' | 'index-unmerged' | 'index-visibility-hidden' | 'concurrent-mutation' | 'untracked-not-in-scope' | 'unknown-status' | 'invalid-encoding';
export interface OccWholeDiffFileEvidence {
    relativePath: string;
    previousPath?: string;
    status: GitFileStatus;
    /** File-level `semantic-no-op` is decodable legacy-only; V4 emits `cosmetic-change` for admitted trivia. */
    verdict: OccWholeDiffSemanticVerdict;
    coverage: OccEntityEvidenceCoverage;
    basis: OccWholeDiffFileBasis;
    grammar?: string;
    /** Expected SHA-256 of the checked-in grammar WASM used by V3/V4. */
    grammarDigest?: string;
    /** Digest of the grammar/comment-node manifest used by V3/V4. */
    grammarManifestDigest?: string;
    /** Digest of the separate V4 trivia-classification policy. */
    triviaPolicyDigest?: string;
    oldMode?: string;
    newMode?: string;
}
export type OccWholeDiffGitComparison = 'merge-base-to-head' | 'base-to-head' | 'head-to-index' | 'head-to-worktree';
export type OccWholeDiffGitLayer = 'committed' | 'index' | 'worktree';
/**
 * Receipt for the exact resolved Git scope covered by a whole-diff proof.
 *
 * The range carries physical object ids after resolution. `includedLayers`
 * makes a worktree or index claim explicit, while `untracked` prevents the
 * summary from being mistaken for a workspace-wide assertion.
 */
export interface OccWholeDiffGitScope {
    range: GitRange;
    comparison: OccWholeDiffGitComparison;
    includedLayers: OccWholeDiffGitLayer[];
    relativePath?: string;
    implicit: boolean;
    /** Captured tree object for an index generation, when that layer is included. */
    indexTreeOid?: string;
    untracked: 'not-applicable' | 'excluded-none-observed' | 'excluded-present';
}
export interface OccWholeDiffSemanticSummary {
    scope: 'whole-diff';
    proof: OccWholeDiffProof;
    /** Present on V3/V4 receipts; absent on persisted V1/V2 receipts. */
    grammarManifestDigest?: string;
    /** Present on V4 receipts; absent on persisted V1-V3 receipts. */
    triviaPolicyDigest?: string;
    verdict: OccWholeDiffSemanticVerdict;
    coverage: OccEntityEvidenceCoverage;
    counts: {
        logic: number;
        noOp: number;
        unknown: number;
        /** Optional only so persisted V1-V3 receipts remain assignable. V4 always emits it. */
        cosmetic?: number;
        /** V4 subset of `cosmetic`; absent on legacy receipts. */
        whitespaceOnly?: number;
        /** V4 subset of `cosmetic`; absent on legacy receipts. */
        commentOnly?: number;
    };
    files: OccWholeDiffFileEvidence[];
    evidenceGaps: {
        unclassifiedFiles: Array<{
            relativePath: string;
            basis: OccWholeDiffFileBasis;
        }>;
        diagnostics: EntityDiagnostic[];
    };
    /** Absent only when a call failed before a Git range could be resolved. */
    gitScope?: OccWholeDiffGitScope;
}
export type OccWholeDiffContent = string | Uint8Array;
/** One exhaustive raw-diff ledger row supplied to the whole-file classifier. */
export interface OccWholeDiffFileClassifierInput {
    relativePath: string;
    previousPath?: string;
    status: GitFileStatus;
    oldMode?: string;
    newMode?: string;
    oldContent?: OccWholeDiffContent;
    newContent?: OccWholeDiffContent;
    /** Override extension-based grammar resolution with an already-pinned grammar. */
    grammar?: string;
    /** A fact learned while acquiring the row that prevents a CST proof. */
    unavailableBasis?: OccWholeDiffFileBasis;
    /** A raw Git binary fact; the complete buffers are still checked for NULs. */
    binary?: boolean;
    maxBytes?: number;
    maxLines?: number;
}
export interface OccWholeDiffClassifierInput {
    /** `error` represents a call-level failure, not a per-file evidence gap. */
    status?: 'resolved' | 'error';
    gitScope?: OccWholeDiffGitScope;
    files: readonly OccWholeDiffFileClassifierInput[];
    diagnostics?: readonly EntityDiagnostic[];
    /** Scope gaps that are not raw diff rows and therefore do not affect counts. */
    unclassifiedFiles?: readonly {
        relativePath: string;
        basis: OccWholeDiffFileBasis;
    }[];
}
export type OccWholeDiffClassifier = (input: OccWholeDiffClassifierInput) => Promise<OccWholeDiffSemanticSummary>;
export interface OccEntityObligationGap {
    /** Durable entity lineage id, or a provisional id for an uncommitted entity. */
    entityId: string;
    qualifiedName: string;
    /**
     * Closest test reached by the reverse BFS.
     *
     * A gap is emitted only when the complete traversal reaches no test, so this
     * is currently `null`. Keeping the annotation explicit makes absence
     * machine-readable without inventing a placeholder test.
     */
    nearestTestedAncestor: string | null;
}
export type OccEntityObligationSkippedChangeReason = 'logic-classification-unknown' | 'current-graph-join-missing' | 'impact-partial';
export interface OccEntityObligationSkippedChange {
    qualifiedName: string;
    relativePath: string;
    reason: OccEntityObligationSkippedChangeReason;
}
export interface OccEntityDiffObligations {
    gaps: OccEntityObligationGap[];
    seamCrossings: string[];
    split: {
        logic: number;
        cosmetic: number;
    };
    /** Optional only so persisted pre-0.19 results remain assignable. New producers always emit it. */
    coverage?: 'complete' | 'partial';
    /** Bounded detail plus the unbounded total, so truncation is mechanically visible. */
    evidenceGaps?: {
        skippedChanges: OccEntityObligationSkippedChange[];
        count: number;
    };
}
export interface OccEntityDiffResult {
    status: 'resolved' | 'error';
    code?: OccEntityErrorCode;
    message?: string;
    range?: {
        base: string;
        head: string;
        kind: string;
    };
    changedFiles: string[];
    changes: OccEntityChange[];
    truncated: boolean;
    omitted: number;
    diagnostics: EntityDiagnostic[];
    /** Always present: absence of a proved logic change is not necessarily a proved no-op. */
    semantic: OccEntityDiffSemanticSummary;
    /**
     * Authoritative whole-diff proof. Optional at the TypeScript boundary for
     * 0.17.1 source compatibility; present at runtime for successful 0.17.3
     * entity diffs when the matching health feature is advertised.
     */
    wholeDiffSemantic?: OccWholeDiffSemanticSummary;
    /** Present only when the caller explicitly requests obligation analysis. */
    obligations?: OccEntityDiffObligations;
}
export declare const OccEntityImpactScopeSchema: z.ZodEnum<{
    all: "all";
    tests: "tests";
    deps: "deps";
    dependents: "dependents";
}>;
export type OccEntityImpactScope = z.infer<typeof OccEntityImpactScopeSchema>;
export declare const OccEntityImpactOptionsSchema: z.ZodObject<{
    scope: z.ZodOptional<z.ZodEnum<{
        all: "all";
        tests: "tests";
        deps: "deps";
        dependents: "dependents";
    }>>;
    depth: z.ZodOptional<z.ZodNumber>;
    maxEntities: z.ZodOptional<z.ZodNumber>;
    inlineContext: z.ZodOptional<z.ZodNumber>;
}, z.core.$strip>;
export type OccEntityImpactOptions = z.infer<typeof OccEntityImpactOptionsSchema>;
export type OccEntityTestFramework = 'vitest' | 'jest' | 'mocha' | 'node:test' | 'pytest';
/**
 * A command that is runnable as
 * `execFile(command.executable, command.args, { cwd: command.cwd })`.
 *
 * The executable and cwd are absolute. Arguments are already separated, so a
 * host must not add shell parsing or quoting.
 */
export interface OccEntityTestCommand {
    executable: string;
    args: string[];
    cwd: string;
}
/** A runnable identity for a test block returned by `impact --scope tests`. */
export interface OccEntityTestSelector {
    /** Repository-relative path. */
    file: string;
    /** The literal title of the selected test or suite. */
    title: string;
    /** Outer-to-inner literal suite titles. */
    suites: string[];
    /** The runner's full title, with suites and title joined by spaces. */
    fullTitle: string;
    framework?: OccEntityTestFramework;
    command?: OccEntityTestCommand;
}
export interface OccEntityImpactEntry {
    entity: OccEntityRef;
    /** Hops from the target; 1 is direct. */
    distance: number;
    /** The edge kinds that connected it. */
    via: string[];
    /** Present for affected tests, even when no runner can be identified safely. */
    selector?: OccEntityTestSelector;
    inlineContext?: SourceInlineBlock;
}
export interface OccEntityImpactPayload {
    entity: OccEntityRef;
    inlineContext?: SourceInlineBlock;
    scope: OccEntityImpactScope;
    dependencies: OccEntityImpactEntry[];
    dependents: OccEntityImpactEntry[];
    transitive: OccEntityImpactEntry[];
    tests: OccEntityImpactEntry[];
    truncated: boolean;
    omitted: number;
    /** `partial` when edges, bounds, or traversed parser call/exact-span evidence are incomplete. */
    coverage: 'full' | 'partial';
    /** Resolved edges whose opposite endpoint was absent from the node or live-entity index. */
    unreachableEdges: number;
    diagnostics: EntityDiagnostic[];
}
export type OccEntityImpactResult = OccEntityOutcome<OccEntityImpactPayload>;
export declare const OccEntityBlameOptionsSchema: z.ZodObject<{
    relativePath: z.ZodString;
    ref: z.ZodOptional<z.ZodString>;
    walkBack: z.ZodOptional<z.ZodBoolean>;
}, z.core.$strip>;
export type OccEntityBlameOptions = z.infer<typeof OccEntityBlameOptionsSchema>;
/** Programmatic-only controls that are deliberately absent from the wire schema. */
export interface OccEntityBlameRuntimeOptions extends OccEntityBlameOptions {
    signal?: AbortSignal;
}
export declare const OccEntityBlameStateSchema: z.ZodEnum<{
    "shallow-history": "shallow-history";
    committed: "committed";
    "working-tree-modified": "working-tree-modified";
    uncommitted: "uncommitted";
    untracked: "untracked";
    "no-history": "no-history";
    "outside-window": "outside-window";
}>;
export type OccEntityBlameState = z.infer<typeof OccEntityBlameStateSchema>;
export interface OccEntityBlameEntry {
    entity: OccEntityRef;
    state: OccEntityBlameState;
    /** Absent whenever attribution is unavailable; never invented. */
    commit?: string;
    author?: string;
    authorEmail?: string;
    date?: string;
    subject?: string;
    /** The change type of the last semantic change, when there was one. */
    changeType?: EntityChangeType;
    matchReason?: LineageMatchReason;
    confidence?: number;
}
export interface OccEntityBlamePayload {
    relativePath: string;
    entries: OccEntityBlameEntry[];
    diagnostics: EntityDiagnostic[];
}
export type OccEntityBlameResult = ({
    status: 'resolved';
} & OccEntityBlamePayload) | {
    status: 'not_found';
    relativePath: string;
    message: string;
} | {
    status: 'error';
    code: OccEntityErrorCode;
    message: string;
};
export declare const ENTITY_HISTORY_DEFAULT_LIMIT = 20;
export declare const ENTITY_HISTORY_MAX_LIMIT = 100;
export declare const OccEntityHistoryOptionsSchema: z.ZodObject<{
    limit: z.ZodOptional<z.ZodNumber>;
    ref: z.ZodOptional<z.ZodString>;
    walkBack: z.ZodOptional<z.ZodBoolean>;
}, z.core.$strip>;
export type OccEntityHistoryOptions = z.infer<typeof OccEntityHistoryOptionsSchema>;
/** Programmatic-only controls that are deliberately absent from the wire schema. */
export interface OccEntityHistoryRuntimeOptions extends OccEntityHistoryOptions {
    signal?: AbortSignal;
}
export interface OccEntityHistoryEntry {
    lineageId: string;
    commit: string;
    author: string;
    authorEmail: string;
    date: string;
    subject: string;
    changeType: EntityChangeType;
    structuralChange: boolean | null;
    matchReason: LineageMatchReason;
    confidence: number;
    previousName?: string;
    previousPath?: string;
    currentName?: string;
    currentPath?: string;
    flags: EntityChangeFlags;
}
export interface OccEntityHistoryPayload {
    entity: OccEntityRef;
    entries: OccEntityHistoryEntry[];
    truncated: boolean;
    omitted: number;
    diagnostics: EntityDiagnostic[];
}
export type OccEntityHistoryResult = OccEntityOutcome<OccEntityHistoryPayload>;
export declare const ENTITY_CONTEXT_DEFAULT_BUDGET = 8000;
export declare const OccEntityContextRoleSchema: z.ZodEnum<{
    target: "target";
    direct_dependency: "direct_dependency";
    transitive_dependency: "transitive_dependency";
    direct_dependent: "direct_dependent";
    transitive_dependent: "transitive_dependent";
}>;
export type OccEntityContextRole = z.infer<typeof OccEntityContextRoleSchema>;
export declare const OccEntityContextDirectionSchema: z.ZodEnum<{
    deps: "deps";
    dependents: "dependents";
}>;
export type OccEntityContextDirection = z.infer<typeof OccEntityContextDirectionSchema>;
export declare const OccEntityContextOptionsSchema: z.ZodObject<{
    tokenBudget: z.ZodOptional<z.ZodNumber>;
    hops: z.ZodOptional<z.ZodNumber>;
    tokenizer: z.ZodOptional<z.ZodString>;
    include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
        deps: "deps";
        dependents: "dependents";
    }>>>;
    inlineContext: z.ZodOptional<z.ZodNumber>;
}, z.core.$strip>;
export type OccEntityContextOptions = z.infer<typeof OccEntityContextOptionsSchema>;
/** Programmatic-only controls that are deliberately absent from the wire schema. */
export interface OccEntityContextRuntimeOptions extends OccEntityContextOptions {
    signal?: AbortSignal;
    /** Internal wire format whose complete rendering is charged to the budget. */
    budgetFormat?: 'text' | 'json';
    /** Internal echo used to price the resolved JSON outcome exactly. */
    budgetQuery?: OccEntityQuery;
    /** Whether the priced JSON wire representation is indented. */
    budgetPretty?: boolean;
}
/** The batch accepts the same traversal, tokenizer, budget, and cancellation controls. */
export type OccEntityContextManyOptions = OccEntityContextRuntimeOptions;
export interface OccEntityContextEntry {
    entity: OccEntityRef;
    role: OccEntityContextRole;
    distance: number;
    tokens: number;
    source: string;
    truncated: boolean;
    /** Range represented by `source` when surrounding lines were requested. */
    inlineContext?: SourceInlineRange;
}
export type OccEntityReferenceClosure = 'closed' | 'open' | 'unknown';
export type OccEntityReferenceClosureReason = 'targets-omitted' | 'unresolved-edges' | 'unreachable-edges' | 'graph-node-unavailable' | 'regex-fallback' | 'truncated-entity';
/** One bounded handle explaining an open or unknown reference-closure verdict. */
export interface OccEntityContextUnresolvedHandle {
    kind: 'omitted-target' | 'unreachable-target' | 'unresolved-edge' | 'ambiguous-edge';
    edgeType: 'calls' | 'imports' | 'uses';
    name: string;
    nodeId?: string;
    relativePath?: string;
}
export interface OccEntityContextPayload {
    entity: OccEntityRef;
    entries: OccEntityContextEntry[];
    tokenBudget: number;
    tokensUsed: number;
    tokenizer: string;
    truncated: boolean;
    /** How many entities were left out, grouped by the role they would have had. */
    omitted: Record<OccEntityContextRole, number>;
    /** Reference closure over resolved 1-hop edges under the pinned index. */
    referenceClosure: OccEntityReferenceClosure;
    /** Fixed mechanical reasons behind an open or unknown verdict; empty only for closed. */
    referenceClosureReasons: OccEntityReferenceClosureReason[];
    edgesResolved: number;
    edgesUnresolved: number;
    /** Unique reachable targets referenced by emitted entities but not emitted whole. */
    targetsOmitted: number;
    /** W1.4 endpoint accounting: resolved edges absent from the node/live-entity join. */
    unreachableEdges: number;
    /** Bounded handles for omitted, unresolved, ambiguous, or unreachable references. */
    unresolvedHandles: OccEntityContextUnresolvedHandle[];
    /** Additional handles hidden by the public bound. */
    unresolvedHandlesOmitted: number;
    /** Includes bounded parser-evidence diagnostics when the reached graph is degraded. */
    diagnostics: EntityDiagnostic[];
}
export type OccEntityContextResult = OccEntityOutcome<OccEntityContextPayload>;
export interface OccEntityContextManyRelation {
    /** Index into the input query array. Duplicate queries deliberately keep separate indexes. */
    targetIndex: number;
    role: OccEntityContextRole;
    distance: number;
}
export interface OccEntityContextManyEntry {
    entity: OccEntityRef;
    tokens: number;
    source: string;
    inlineContext?: SourceInlineRange;
    /** Every requested target that reaches this deduplicated body. */
    relations: OccEntityContextManyRelation[];
}
export interface OccEntityContextManyOmission {
    entity: OccEntityRef;
    reason: 'budget' | 'source-unavailable';
    relations: OccEntityContextManyRelation[];
}
export type OccEntityContextManyTarget = {
    status: 'resolved';
    query: OccEntityQuery;
    entity: OccEntityRef;
    /** False when the root resolved but its whole body did not fit or could not be read. */
    included: boolean;
} | {
    status: 'not_found';
    query: OccEntityQuery;
    candidates: OccEntityRef[];
    message: string;
} | {
    status: 'ambiguous';
    query: OccEntityQuery;
    candidates: OccEntityRef[];
    message: string;
} | {
    status: 'error';
    query: OccEntityQuery;
    code: OccEntityErrorCode;
    message: string;
};
export interface OccEntityContextManyPayload {
    status: 'resolved';
    targets: OccEntityContextManyTarget[];
    entries: OccEntityContextManyEntry[];
    tokenBudget: number;
    tokensUsed: number;
    tokenizer: string;
    truncated: boolean;
    omissions: OccEntityContextManyOmission[];
    diagnostics: EntityDiagnostic[];
}
export interface OccEntityContextManyError {
    status: 'error';
    code: OccEntityErrorCode;
    message: string;
}
export type OccEntityContextManyResult = OccEntityContextManyPayload | OccEntityContextManyError;
/** Additive summary of the per-file parser evidence carried by the code index. */
export type OccCodeIndexParserEvidenceStatus = ParserEvidenceSummary;
/**
 * Whether the index behind this session is complete, and why not.
 *
 * Separate from `stats()`, which counts work done. This answers the only
 * question a caller can act on: may I read an empty or unattributed result as
 * a fact about the repository, or as a fact about OCC's bounds?
 */
export interface OccEntityIndexStatus {
    mode: EntityIndexMode;
    /** Public code-index JSON contract, absent only for a legacy caller-supplied index. */
    codeIndexSchemaVersion?: number;
    /** Parser contract used to produce the entity records in this session. */
    parserContract?: {
        parserName: string;
        parserVersion: number;
    };
    /** Per-file parser/checker honesty for the live code graph. */
    parserEvidence?: OccCodeIndexParserEvidenceStatus;
    head?: string;
    commitsIndexed: number;
    eventsRecorded: number;
    lineageCount: number;
    truncated: boolean;
    /** False when any diagnostic belongs to the wide evidence-gap set. */
    evidenceComplete: boolean;
    /** The diagnostics that made it truncated; empty when it is not. */
    reasons: EntityDiagnostic[];
    /** Every diagnostic the index build produced, truncating or not. */
    diagnostics: EntityDiagnostic[];
}
/** Why a session no longer describes the repository in front of it. */
export declare const OccEntityStalenessReasonSchema: z.ZodEnum<{
    "head-moved": "head-moved";
    "working-tree-changed": "working-tree-changed";
}>;
export type OccEntityStalenessReason = z.infer<typeof OccEntityStalenessReasonSchema>;
/**
 * Whether this session still describes the repository, and what moved if not.
 *
 * The point is that asking is cheap. A long-lived host — an MCP server, an
 * editor extension — has to decide before every request whether its answers are
 * still about the current repository, and a check that costs anything like a
 * rebuild would simply not be run. `head` is one `rev-parse`; the working-tree
 * comparison is a stat sweep against the index manifest and can be declined.
 */
export interface OccEntityFreshness {
    fresh: boolean;
    /** The commit the repository is at now; absent in a repository with no commits. */
    head?: string;
    /** The commit the lineage index covers. */
    indexedHead?: string;
    /**
     * Working-tree drift against the code index.
     *
     * Absent when it was not requested, or when the session's code index has no
     * manifest to compare against — a caller-supplied session, or a cacheless
     * one. Absent means unmeasured, never unchanged.
     */
    workingTree?: {
        fresh: boolean;
        added: number;
        modified: number;
        deleted: number;
    };
    reasons: OccEntityStalenessReason[];
}
/** Behavioural counters, for asserting cache and traversal work rather than timing it. */
export interface OccEntityStats {
    blobsParsed: number;
    blobsFromCache: number;
    blobsRead: number;
    gitInvocations: number;
    commitsIndexed: number;
    entitiesExtracted: number;
    lineageCount: number;
    eventCount: number;
    cacheHits: number;
    cacheMisses: number;
    cacheWrites: number;
    /** Bytes deserialized from the persisted index entry — the cost of a warm start. */
    cacheBytesRead: number;
    ambiguitiesRefused: number;
    lineageMatches: number;
    lineageAcceptDeclines: number;
}
export declare const EntityDiagnosticsSchema: z.ZodArray<z.ZodObject<{
    code: z.ZodEnum<{
        "inline-context-stale": "inline-context-stale";
        "parse-failed": "parse-failed";
        "grammar-verification-refused": "grammar-verification-refused";
        "commit-window-truncated": "commit-window-truncated";
        "commit-files-truncated": "commit-files-truncated";
        "blob-missing": "blob-missing";
        "blob-too-large": "blob-too-large";
        "blob-too-many-lines": "blob-too-many-lines";
        "blob-binary": "blob-binary";
        "blob-unsupported": "blob-unsupported";
        "blob-budget-exhausted": "blob-budget-exhausted";
        "entities-truncated": "entities-truncated";
        "entity-budget-exhausted": "entity-budget-exhausted";
        "event-budget-exhausted": "event-budget-exhausted";
        "cross-file-skipped": "cross-file-skipped";
        "similarity-skipped": "similarity-skipped";
        "ambiguity-refused": "ambiguity-refused";
        "lineage-accept-declined": "lineage-accept-declined";
        "evidence-unavailable": "evidence-unavailable";
        "shallow-history": "shallow-history";
        "unborn-repo": "unborn-repo";
        "merge-side-changes-skipped": "merge-side-changes-skipped";
        "index-unmerged": "index-unmerged";
        "index-visibility-hidden": "index-visibility-hidden";
        "cache-rebuilt": "cache-rebuilt";
        "cache-rewound": "cache-rewound";
        "history-rewritten": "history-rewritten";
    }>;
    message: z.ZodString;
    commit: z.ZodOptional<z.ZodString>;
    relativePath: z.ZodOptional<z.ZodString>;
    blobSha: z.ZodOptional<z.ZodString>;
    grammar: z.ZodOptional<z.ZodString>;
    rung: z.ZodOptional<z.ZodEnum<{
        none: "none";
        similarity: "similarity";
        "exact-identity": "exact-identity";
        "git-rename-identity": "git-rename-identity";
        "content-hash": "content-hash";
        "normalized-hash": "normalized-hash";
        "structural-hash": "structural-hash";
        "signature-name": "signature-name";
        "qualified-name": "qualified-name";
    }>>;
    kept: z.ZodOptional<z.ZodNumber>;
    total: z.ZodOptional<z.ZodNumber>;
    limit: z.ZodOptional<z.ZodNumber>;
}, z.core.$strip>>;
export type { EntityDiagnostic };
/**
 * Re-exported because `OccEntityDiffOptions.rangeMode` embeds it.
 *
 * A consumer validating a diff request needs the enum, and reaching past this
 * module into the git layer for one member of a contract stated here would make
 * the entity API only nearly self-describing.
 */
export { GitRangeModeSchema };
export type { GitRangeMode };
