import type { LanguageModel } from 'ai';
import { type RunManifest, type RunCaseEntry } from './run-paths.js';
export interface RunAnalyseOptions {
    /**
     * Path to the source under analysis. The runner does NOT copy this into
     * outputDir/input/ — that's the caller's responsibility (the harness has
     * its own corpus-shape conventions; CLI commands will copy explicitly).
     */
    sourceDir: string;
    /**
     * Where to write the structured run output (input/, facts/, prompts/,
     * llm-output/, specs/, project/).
     */
    outputDir: string;
    /** Pre-extracted facts file injected as the prompt preamble. */
    factsPath?: string;
    /** Auto-extract facts via `runPrepass` before calling the analyse prompt. */
    autoFacts?: boolean;
    /**
     * Attach to a pre-existing STANDARD gitnexus index (read-only, global
     * registry) instead of building an isolated one — threaded to runPrepass →
     * GitNexus backend. The CLI handler sets this when the source already has an
     * index and isn't a batch/pre-staged run. Default false (isolate).
     */
    attach?: boolean;
    /** Restrict extracted facts to these top-level subdirs (`--scope`); threaded
     *  to runPrepass as a facts-layer filter (works even when attaching). */
    scope?: string[];
    /** Run the rule-driven quality-verify after the draft pass (`--verify`):
     *  enables ALL analyse-verify verifiers (surgical per-action re-fire). Replaces
     *  the retired monolithic verify-analyse LLM re-pass. A subset can be selected
     *  without this flag via `SPECVERSE_ANALYSE_VERIFY_ENABLE`. */
    verify?: boolean;
    /**
     * Run the Quint 5b deterministic gate after verify-analyse — generates
     * a per-spec Quint module from the spec's lifecycles + behavior pre-
     * conditions and runs `quint typecheck` against it. Skips cleanly when
     * the quint CLI isn't on PATH. See TODO #31 + the design plan at
     * `docs/plans/2026-04-30-DETERMINISTIC-VERIFICATION-GATES.md`.
     */
    verifyBehavior?: boolean;
    /**
     * When true, a Quint typecheck failure aborts the workflow rather than
     * emitting a warning. Default false (the gate is informational unless
     * caller opts into strict mode). Implies `verifyBehavior: true`.
     */
    strictBehavior?: boolean;
    /** Materialize project/ via `spv init` + `spv realize all`. */
    realize?: boolean;
    /** Pre-resolved LanguageModel (for cross-call session caching). */
    model?: LanguageModel;
    /**
     * Externally-managed claude-cli session ID — passed through to resolveModel
     * when `model` is not provided. Lets harness orchestrators share session
     * state across N spawn'd `spv ai analyse` invocations (~75% token saving).
     */
    sessionId?: string;
    /** Per-call timeout. Default 15 min. */
    timeoutMs?: number;
    /** Identity fields recorded in manifest. */
    prompt?: string;
    providerId?: string;
    modelId?: string;
    experimentRunId?: string;
    caseName?: string;
    /** Loose case meta for the manifest (kind: 'analyse' is fixed). */
    caseMeta?: RunCaseEntry;
    /**
     * Use the skeleton-emitter + per-action micro-calls pipeline instead of
     * the legacy single giant analyse call. See plan:
     * specverse-self/docs/plans/2026-05-04-ANALYSE-VIA-FAITHFUL-SKELETON-AND-MICROCALLS.md
     *
     * Default: TRUE when prepassFacts are available (i.e. autoFacts was set).
     *          FALSE otherwise (legacy single-call). Explicit values override.
     *
     * Rationale (engines 6.77+): the skeleton-emit + micro-call path has been
     * the only sane option since engines 6.27, but the engines API kept the
     * field as opt-in. self 5.18.1 retired the CLI --microcalls/--no-microcalls
     * flag intending to hardcode this true at the CLI handler, but the dist
     * regression in self 5.19.1 surfaced that an opt-in API default is
     * fragile across the CLI ↔ engines boundary. Flipping the engines-level
     * default to "true when prerequisites are met" makes the integration
     * defensive: any caller that supplies autoFacts now gets the right path
     * even if their CLI wrapper forgot to set useMicrocalls explicitly.
     *
     * When effectively true:
     *   - runPrepass produces facts (unchanged)
     *   - emitFaithfulSkeleton turns facts into a faithful skeleton
     *   - runActionMicrocalls fires parallel LLM calls per action stub
     *   - assembleFinalSpec merges skeleton + filled bodies into main.specly
     *   - skeleton.specly + skeleton-provenance.json + microcall-decisions.json
     *     sidecars written alongside existing artifacts
     *
     * Explicit `useMicrocalls: false` always selects the legacy single-call
     * branch — preserved for backward compatibility and explicit opt-out.
     *
     * Explicit `useMicrocalls: true` without prepassFacts throws — the
     * skeleton emitter has no input to consume.
     */
    useMicrocalls?: boolean;
    /** Concurrency cap for per-action micro-calls (default 10). */
    microcallConcurrency?: number;
    /**
     * When false (engines 6.29.0+), skip the LLM-heavy behaviours phase
     * and emit a faithful-skeleton spec with placeholder action bodies.
     * The output is still a valid SpecVerse spec — bodies show
     * `description: "(behaviours pending — run spv ai behaviours)"` and
     * `steps: []`. Defaults to `true` for backward compatibility with
     * existing callers; the `spv ai analyse` CLI command flips this to
     * `false` per the analyse/behaviours split (TODO: see plan
     * 2026-05-06-ANALYSE-BEHAVIOURS-SPLIT.md).
     *
     * Use case: iterate on the prepass + skeleton + manifest + deployment
     * emission without paying for LLM time on bodies. Then run
     * `spv ai behaviours <analysed-spec>` (or call `runBehaviours`)
     * to fill bodies once the structure is confirmed correct.
     */
    withBehaviours?: boolean;
}
export interface RunAnalyseResult {
    outputDir: string;
    draftSpecPath: string;
    /** Canonical spec path = outputDir/specs/main.specly. Always present. */
    finalSpecPath: string;
    /** Stage that produced the canonical spec ("draft" if no verify). */
    finalStage: 'draft' | 'verified';
    validateFinal: {
        ok: boolean;
        errors: string;
    };
    realize: {
        ok: boolean;
        error?: string;
    } | null;
    draftDurationMs: number;
    verifyDurationMs: number;
    wallTimeMs: number;
    manifest: RunManifest;
    draftRetried: boolean;
    validateAfterDraftOk: boolean;
}
/**
 * Execute the full analyse pipeline against a source directory and write
 * the structured run output. Returns paths + status; caller composes
 * scoring / README finalization separately.
 */
export declare function runAnalyse(opts: RunAnalyseOptions): Promise<RunAnalyseResult>;
//# sourceMappingURL=analyse-runner.d.ts.map