/**
 * Orchestrate Plan Operations
 *
 * orchestratePlan, plan interfaces, and private plan helpers migrated from
 * packages/cleo/src/dispatch/engines/orchestrate-engine.ts.
 *
 * @task T1570
 * @task T889
 */
import type { DatabaseSync as _DatabaseSyncType } from 'node:sqlite';
import type { AgentTier } from '@cleocode/contracts';
import type { OrchestratePlanResult } from '@cleocode/contracts/operations/orchestrate';
import { type EngineResult } from '../engine-result.js';
type _AgentRegistryDbHandle = _DatabaseSyncType;
export type { EngineResult };
/**
 * Input envelope for {@link orchestratePlan}.
 *
 * @task T889 / W3-6
 */
export interface OrchestratePlanInput {
    /** Epic task id whose children make up the plan. */
    epicId: string;
    /** Absolute path to the project root (used to open tasks.db). */
    projectRoot: string;
    /** Preferred agent-resolver tier when a classifier result has a registry row. */
    preferTier?: 0 | 1 | 2;
}
/**
 * Per-worker entry emitted by {@link orchestratePlan}.
 *
 * @task T889 / W3-6
 */
export interface PlanWorkerEntry {
    /** Task id this entry represents. */
    taskId: string;
    /** Human-readable task title (defaults to `taskId` when missing). */
    title: string;
    /** Resolved agent id (falls back to `'cleo-subagent'` when unresolved). */
    persona: string;
    /** Protocol tier (0=worker, 1=lead, 2=orchestrator). */
    tier: 0 | 1 | 2;
    /** Role derived from `orchLevel`. */
    role: 'orchestrator' | 'lead' | 'worker';
    /** Declared file scope for this task. Empty array when no AC.files set. */
    atomicScope: {
        files: string[];
    };
    /** Orchestration level sourced from the resolved agent (0..2). */
    orchLevel: number;
    /** Current task status (pending/active/done/…). */
    status: string;
    /** Ids of tasks this task depends on (sorted for determinism). */
    dependsOn: string[];
}
/**
 * A single wave in the execution plan.
 *
 * @task T889 / W3-6
 */
export interface PlanWave {
    /** 1-indexed wave number. */
    wave: number;
    /** Task id of the designated lead for this wave, or `null` when none. */
    leadTaskId: string | null;
    /** Ordered worker entries for this wave. */
    workers: PlanWorkerEntry[];
}
/**
 * Warning surfaced by {@link orchestratePlan} (e.g. missing agent registry row).
 *
 * @task T889 / W3-6
 */
export interface PlanWarning {
    /** Task id the warning applies to. */
    taskId: string;
    /** Stable warning code (e.g. `'E_AGENT_NOT_FOUND'`). */
    code: string;
    /** Human-readable message. */
    message: string;
}
/**
 * Open a short-lived signaldock db handle for composer lookups.
 *
 * Mirrors the pattern used by {@link orchestratePlan}: we intentionally do
 * NOT cache this handle — the resolver contract owns its own lifecycle and
 * callers must close the returned handle when the batch completes.
 *
 * @returns Open {@link _AgentRegistryDbHandle} bound to the global signaldock.db.
 * @task T932
 */
export declare function openAgentRegistryDbForComposer(): Promise<_AgentRegistryDbHandle>;
/**
 * Map a numeric tier (0|1|2) used by the CLI/domain boundary to the
 * string-typed {@link AgentTier} understood by the resolver.
 *
 * @param tier - Numeric tier from input.
 * @returns Resolver-compatible tier or `undefined` when out of range.
 * @task T889 / W3-6
 */
export declare function numericToAgentTier(tier: 0 | 1 | 2): AgentTier | undefined;
/**
 * Generate a deterministic, machine-readable execution plan for an epic.
 *
 * The plan groups children into waves via the same topological sort used by
 * `orchestrate ready --epic` and `orchestrate waves` (`getEnrichedWaves`),
 * then enriches every task with a classifier agent id, resolved persona,
 * atomic scope (AC.files), and role/tier derived from the resolved agent's
 * `orchLevel`. Each wave exposes a `leadTaskId` (first lead or, failing
 * that, the first orchestrator) to simplify downstream spawn dispatch.
 *
 * Determinism: given identical inputs (task snapshot + epic id), the
 * function returns the same `inputHash`. `generatedAt` is NOT part of the
 * hash so two back-to-back invocations confirm reproducibility by hash
 * equality.
 *
 * Validation: rejects non-epic ids (`type !== 'epic'` AND no children) with
 * `E_VALIDATION`; rejects missing epics with `E_NOT_FOUND`.
 *
 * @param input - {@link OrchestratePlanInput} envelope.
 * @returns Engine result wrapping {@link OrchestratePlanResult}.
 * @task T889 / W3-6
 */
export declare function orchestratePlan(input: OrchestratePlanInput): Promise<EngineResult<OrchestratePlanResult>>;
//# sourceMappingURL=plan.d.ts.map