/**
 * ADR-PIPELINE-093 — Phase Dependency Gate.
 *
 * Shared helper that verifies a phase's required inputs exist, are non-stub,
 * and meet a minimum size before the phase coordinator runs. On a miss the
 * gate invokes the ADR-091 primary executor (`runPrimaryPhaseExecution`)
 * once per missing upstream phase (capped by `maxRetriesPerInput`, default 1)
 * and re-checks.
 *
 * The gate is side-effect-minimal: it only reads `runDir`, logs to stderr
 * with the `[GATE]` prefix, and forwards Ruflo invocations to the injected
 * executor. Mapping of required-input → owning upstream phase is static
 * (`INPUT_OWNER_MAP`) and colocated with the dependency table
 * (`PHASE_DEPENDENCIES`).
 */
import { runPrimaryPhaseExecution as runPrimaryPhaseExecutionImpl, checkRufloAvailable as checkRufloAvailableImpl, type Phase1Dossier, type RufloExecutionContext } from '../ruflo-phase-executor.js';
/** Phase ids accepted by the dependency gate. */
export type PhaseId = 'phase2' | 'phase3-sparc' | 'phase4-adrs-ddd' | 'phase5a-prompts' | 'phase5b-scaffold';
/** A single required-input clause. Either a single file or an "any-of" set. */
export interface RequiredInput {
    readonly kind: 'file' | 'any-of';
    /** Paths relative to runDir. Supports trailing `/*` for glob (ADR-093). */
    readonly paths: ReadonlyArray<string>;
    /** Minimum file size in bytes. Defaults to 100 per ADR-093 Rule 2. */
    readonly minBytes?: number;
}
/** Per-phase static dependency declaration. */
export interface PhaseDependency {
    readonly phaseId: PhaseId;
    readonly required: ReadonlyArray<RequiredInput>;
    /** Path patterns relative to runDir; informational only (not gated). */
    readonly optional: ReadonlyArray<string>;
}
/** Gate invocation result. */
export interface GateResult {
    readonly ok: boolean;
    /** Paths that failed the initial check. */
    readonly missing: ReadonlyArray<string>;
    /** Upstream phase ids whose Ruflo primary executor was invoked. */
    readonly ruflo_invoked: ReadonlyArray<string>;
    /** Paths still failing after the retry pass. Empty when `ok` is true. */
    readonly stillMissing: ReadonlyArray<string>;
}
/** Gate options. `runPrimaryPhaseExecution` is injectable for unit tests. */
export interface GateOptions {
    readonly runDir: string;
    readonly dossier: Phase1Dossier;
    readonly context: RufloExecutionContext;
    /** Max Ruflo invocations per missing input per run. Defaults to 1 (ADR-093 Rule 2). */
    readonly maxRetriesPerInput?: number;
    /** Injectable for tests. Defaults to the real `runPrimaryPhaseExecution`. */
    readonly runPrimaryPhaseExecution?: typeof runPrimaryPhaseExecutionImpl;
    /** Injectable for tests. Defaults to the real `checkRufloAvailable`. */
    readonly checkRufloAvailable?: typeof checkRufloAvailableImpl;
}
/** Entry describing a phase that could not run because inputs were unreachable. */
export interface BlockedPhase {
    readonly phase: PhaseId;
    readonly missing: ReadonlyArray<string>;
}
/**
 * ADR-PIPELINE-094 Decision 5 — per-input check entry in `gate-decision-log.json`.
 * Captures both the logical path declared in `PHASE_DEPENDENCIES` and the
 * physical path the gate actually inspected (after `resolvePhasePath`). The
 * pair is the smoking gun for path-resolution defects like the originating
 * `4ed715bf` cascade.
 */
export interface CheckedInput {
    /** Path as declared in PHASE_DEPENDENCIES (logical/relative). */
    readonly logical_path: string;
    /** Absolute path the gate inspected on disk. */
    readonly resolved_path: string;
    readonly exists: boolean;
    readonly size_bytes: number;
    readonly is_error_stub: boolean;
    readonly satisfies: boolean;
}
/**
 * ADR-PIPELINE-094 Decision 5 — Ruflo-invocation entry in
 * `gate-decision-log.json`. Mirrors the executor's tier and reason fields
 * so downstream RCA tools can read provenance without parsing log lines.
 */
export interface RufloInvocationLog {
    readonly phase: PhaseId;
    readonly tier: string;
    readonly reason: string;
}
/**
 * ADR-PIPELINE-094 Decision 5 — machine-readable per-phase gate decision.
 * Written to `<runDir>/<phaseDirname>/gate-decision-log.json` for every
 * gate invocation. Replaces text-only `[GATE]` log lines as the source of
 * truth for the `agentics-status` MCP tool and post-run RCA.
 */
export interface GateDecisionLog {
    readonly phaseId: PhaseId;
    readonly trace_id: string;
    readonly timestamp: string;
    readonly checked_inputs: ReadonlyArray<CheckedInput>;
    readonly ruflo_invoked: ReadonlyArray<RufloInvocationLog>;
    readonly verdict: 'ok' | 'blocked';
    readonly still_missing: ReadonlyArray<string>;
    readonly decision_ms: number;
}
/**
 * ADR-PIPELINE-094 Decision 5 — maps gate `PhaseId` to the per-phase output
 * directory under `runDir`. Used to write `gate-decision-log.json` to the
 * canonical location the auto-chain coordinator writes its other artifacts
 * to. Phase 5a/5b compose into the parent `phase5/` tree but get their own
 * subdir so the log file does not collide.
 */
export declare const PHASE_DIRNAME: Readonly<Record<PhaseId, string>>;
/** Per-phase required/optional inputs, hard-coded from the ADR DAG table. */
export declare const PHASE_DEPENDENCIES: Readonly<Record<PhaseId, PhaseDependency>>;
/**
 * Maps a required-input path (relative to runDir) onto the upstream phase
 * that produces it. Used by the gate to decide which phase's Ruflo primary
 * executor to invoke when an input is missing. Keyed by path prefix; the
 * longest matching prefix wins.
 */
export declare const INPUT_OWNER_MAP: Readonly<Record<string, PhaseId>>;
/**
 * Returns `false` iff the content is a JSON error-stub sentinel — a JSON
 * object whose only top-level keys are `error` and/or `message`. Non-JSON
 * content always returns `true`. Empty strings also return `true`
 * (size-gating is the caller's job; the stub check is purely about shape).
 */
export declare function isNotErrorStub(content: string): boolean;
/**
 * Inspects per-phase gate results and returns a BlockedPhase entry for
 * every phase whose gate failed and still has missing inputs after retry.
 * Used by auto-chain to populate `status.json.blocked_phases`.
 */
export declare function determineBlockedPhases(results: ReadonlyArray<{
    phaseId: PhaseId;
    gateResult: GateResult;
}>): ReadonlyArray<BlockedPhase>;
/**
 * Verifies `phaseId`'s declared required inputs on disk. On a miss, invokes
 * the ADR-091 primary executor for each owning upstream phase (capped at
 * `maxRetriesPerInput`) and re-checks. Returns a `GateResult` describing the
 * outcome. Never throws.
 */
export declare function gatePhaseInputs(phaseId: PhaseId, opts: GateOptions): Promise<GateResult>;
/**
 * Resolves a logical phase path (as declared in `PHASE_DEPENDENCIES`) to one
 * or more absolute candidate paths under `runDir`, in priority order.
 *
 * Phase 1 writes its outputs flat to `<runDir>/<file>` (see
 * `swarm-orchestrator.ts:1831,2222,2229,2249,2252`), but the gate's
 * dependency table refers to them with a `phase1/` prefix for dependency-DAG
 * clarity. Pre-094 the gate joined the relative path to `runDir` literally
 * and looked at `<runDir>/phase1/<file>`, which never exists in production —
 * the false-negative cascade documented in the originating run.
 *
 * Resolution rules:
 *   - `phase1/X` → first try `<runDir>/X` (production, flat layout); if the
 *     caller's existence check fails there, fall through to
 *     `<runDir>/phase1/X` (test fixtures and any future subdir layout).
 *   - All other prefixes resolve unchanged: `<runDir>/<relPath>`.
 *
 * Returns at least one candidate. Callers iterate in order and accept the
 * first candidate that satisfies their predicate.
 *
 * Exported for unit tests and for any future code that needs to resolve a
 * declared dependency path to its physical location. This is the SINGLE place
 * the logical→physical mapping lives.
 */
export declare function resolvePhasePath(runDir: string, relPath: string): string[];
/**
 * Writes `<runDir>/<phaseDirname>/gate-decision-log.json` for the given
 * decision. Best-effort: never throws; on filesystem error, logs to stderr
 * and returns. The text `[GATE]` log lines continue alongside this for
 * human readability — the JSON is the machine-readable surface.
 *
 * Exported for unit tests. Production callers go through `gatePhaseInputs`
 * which invokes this internally after computing its verdict.
 */
export declare function writeGateDecisionLog(runDir: string, log: GateDecisionLog): void;
//# sourceMappingURL=phase-dependency-gate.d.ts.map