/**
 * Operation resolution — the single truthful value every plan-family command
 * terminates with.
 *
 * One `OperationResolution` is produced at every termination path of a
 * plan-family invocation (preview, blocked, cancelled, applied, partial,
 * failed, interrupted). The operation outcome is a pure derivation over the
 * unit terminal multiset and the operation-level events the value carries, and
 * the exit code is a pure mapping from that outcome. Every channel — machine
 * document, human render, telemetry — projects this value; none re-derives its
 * own account of what happened.
 *
 * @experimental This API is unstable and may change without notice.
 */
import type * as Option from "effect/Option";
import * as Schema from "effect/Schema";
import { type AppError, type AppErrorCode } from "../app-error/index.js";
import type { ReleaseAgeOperationEvidence } from "../registry/index.js";
import type { SuggestedAction } from "../cli-runtime/suggested-action.js";
import type { BlockingClass, ConfiguredAgentOutcome, ExecutedPlan, Job, JobStepArtifact, OperationPrecondition, OperationPresentation, PlanRiskCondition, RegistryLifecycleEvidence } from "./plan.js";
/**
 * Canonical unit states. `planned` and `ready` are pre-terminal and appear only
 * in preview-mode and not-executed resolutions; the rest are terminal.
 * Warnings annotate a state and are never a state of their own.
 */
export declare const UnitStateSchema: Schema.Literals<readonly ["planned", "ready", "committed", "unchanged", "failed", "rolled-back", "blocked", "skipped", "cancelled", "interrupted"]>;
export type UnitState = typeof UnitStateSchema.Type;
/** Lifecycle phase in which an operation event (blocking, waiting) occurred. */
export declare const OperationPhaseSchema: Schema.Literals<readonly ["planning", "preview", "confirmation", "validation", "apply", "restoration"]>;
export type OperationPhase = typeof OperationPhaseSchema.Type;
/** Canonical operation terminal outcomes. */
export declare const OperationOutcomeSchema: Schema.Literals<readonly ["previewed", "applied", "no-op", "partial", "failed", "blocked", "cancelled", "interrupted"]>;
export type OperationOutcome = typeof OperationOutcomeSchema.Type;
/** Atomicity class that a closure declares and that an execution applies. */
export declare const AtomicityClassSchema: Schema.Literals<readonly ["closure-atomic", "non-rollbackable"]>;
export type AtomicityClass = typeof AtomicityClassSchema.Type;
/** Post-termination disposition of one unit's durable effects. */
export declare const UnitDispositionSchema: Schema.Literals<readonly ["restored", "retained", "untouched", "unknown"]>;
export type UnitDisposition = typeof UnitDispositionSchema.Type;
/**
 * A typed blocking condition: what class of condition prevented work, which
 * subject it blocked, in which phase it was determined, and — where one exists
 * — the machine-readable escape that resolves it.
 */
export interface OperationBlock {
    readonly class: BlockingClass;
    readonly subject: string;
    readonly phase: OperationPhase;
    readonly detail: string;
    /**
     * Cause class carried for blocking classes whose exit is not pinned by the
     * class alone (`precondition-unmet`, `external-blocked`).
     */
    readonly causeCode?: AppErrorCode;
    /** Machine-readable reference to what blocked the subject. */
    readonly reference?: string;
    readonly escape?: SuggestedAction;
}
export interface ResolvedUnit<Output = never> {
    /** Stable identity: the planned step key where one exists, else the label. */
    readonly id: string;
    readonly label: string;
    readonly state: UnitState;
    /** Present on units of a failed or interrupted closure. */
    readonly disposition?: UnitDisposition;
    /** Present exactly when `state` is `blocked`. */
    readonly blocking?: OperationBlock;
    readonly message?: string;
    /** Annotations on the state, never a state of their own. */
    readonly warnings?: ReadonlyArray<string>;
    readonly error?: AppError;
    readonly artifact?: JobStepArtifact;
    readonly agentOutcomes?: ReadonlyArray<ConfiguredAgentOutcome>;
    readonly registryLifecycle?: RegistryLifecycleEvidence;
    readonly links?: {
        readonly html: string;
    };
    readonly output?: Output;
}
export interface OperationInterruption {
    readonly signal: "SIGINT" | "SIGTERM";
    /**
     * Durable-state disposition of attempted work at the stopping point:
     * `restored` when the closure rolled it back, `retained` when settled
     * commits stand, `unknown` when a started unit's settlement was not
     * observed, and `none` when nothing was attempted.
     */
    readonly disposition: "restored" | "retained" | "unknown" | "none";
}
/** One observed durable change or restoration. */
export interface OperationFootprintEntry {
    readonly path: string;
    readonly change: "created" | "modified" | "removed" | "restored";
}
/**
 * Machine-readable recovery content accompanying a `failed`, `partial`, or
 * `interrupted` outcome: what durable state was retained rather than restored
 * and what action resolves it. It never blocks a later invocation — the next
 * mutation converges from the current workspace state.
 */
export interface OperationRecovery {
    readonly retained: ReadonlyArray<string>;
    /** OS-temporary directory preserving pre-change snapshots, when it survives. */
    readonly snapshotDir?: string;
    readonly actions: ReadonlyArray<SuggestedAction>;
}
export interface OperationAtomicity {
    /** The class the operation's closures declared. */
    readonly declared: AtomicityClass;
    /**
     * The class that actually applied to durable effects: `closure-atomic`
     * when effects were fully restored or never made; `non-rollbackable` when
     * effects were retained, by design or because restoration failed.
     */
    readonly applied: AtomicityClass;
}
export interface OperationResolution<Output = never> {
    readonly _tag: "OperationResolution";
    readonly name: string;
    readonly description: Option.Option<string>;
    readonly mode: "preview" | "apply";
    readonly candidateId?: string;
    readonly atomicity: OperationAtomicity;
    readonly units: ReadonlyArray<ResolvedUnit<Output>>;
    /** The user declined a required confirmation before any mutation. */
    readonly declined?: boolean;
    /** Operation-level typed blocking; nothing was attempted. */
    readonly blocking?: OperationBlock;
    /** Operation-level failure cause, carrying the cause class for the exit. */
    readonly failure?: AppError;
    readonly interruption?: OperationInterruption;
    /** A flag-requested divergence check found divergence on a preview. */
    readonly divergence?: boolean;
    /** Observed durable footprint reported by the mutation layers. */
    readonly footprint?: ReadonlyArray<OperationFootprintEntry>;
    readonly recovery?: OperationRecovery;
    readonly presentation?: OperationPresentation;
    readonly releaseAge?: ReleaseAgeOperationEvidence;
    readonly preconditions?: ReadonlyArray<OperationPrecondition>;
    readonly riskConditions?: ReadonlyArray<PlanRiskCondition>;
    readonly suggestions?: ReadonlyArray<SuggestedAction>;
}
export interface UnitStateCounts {
    readonly total: number;
    readonly planned: number;
    readonly ready: number;
    readonly committed: number;
    readonly unchanged: number;
    readonly failed: number;
    readonly rolledBack: number;
    readonly blocked: number;
    readonly skipped: number;
    readonly cancelled: number;
    readonly interrupted: number;
    /** Annotation count, outside the state partition. */
    readonly warnings: number;
}
export declare const countUnitStates: (units: ReadonlyArray<ResolvedUnit<unknown>>) => UnitStateCounts;
/**
 * The operation outcome, derived — never decided — from the resolution's
 * operation-level events and its unit terminal multiset:
 *
 * - an external termination request resolves `interrupted`;
 * - a typed blocking condition that prevented execution resolves `blocked`;
 * - a declined confirmation resolves `cancelled`;
 * - preview mode with planned units resolves `previewed`;
 * - an empty preview resolves `no-op`;
 * - otherwise the multiset decides: restored work is `failed` (with its
 *   rollback report), surviving commits plus failures are `partial`, commits
 *   alone are `applied`, and zero state-changing effects are `no-op`.
 */
export declare const deriveOperationOutcome: (resolution: OperationResolution<unknown>) => OperationOutcome;
/**
 * The exit code for a resolution, from one outcome-to-exit mapping:
 * previewed/applied/no-op/cancelled exit 0 (a flag-requested divergence on a
 * preview exits 1); partial exits 1; failed exits by cause class (default 1);
 * blocked exits by blocking class (approval/override 2; stale-candidate,
 * resource-conflict, policy-excluded, dependency-cycle 6; otherwise cause
 * class); interrupted exits 130/143.
 */
export declare const operationExitCode: (resolution: OperationResolution<unknown>, outcome?: OperationOutcome) => number;
/** The machine envelope's `ok`: true exactly for the zero-exit outcome set. */
export declare const operationOk: (resolution: OperationResolution<unknown>, outcome?: OperationOutcome) => boolean;
export declare const unitIdOf: (step: {
    readonly key?: string;
    readonly label: string;
}) => string;
/** Units of a plan that was not executed: planned readiness, typed blocking. */
export declare const plannedUnits: <Requirements, Output>(jobs: ReadonlyArray<Job<Requirements, Output>>) => ReadonlyArray<ResolvedUnit<Output>>;
/**
 * Units of an executed plan. `restored: true` marks the closure-atomic
 * failure path where every committed effect was rolled back.
 */
export declare const executedUnits: <Output>(executed: ExecutedPlan<Output>, options?: {
    readonly restored?: boolean;
}) => ReadonlyArray<ResolvedUnit<Output>>;
/**
 * Stable-identity ordering for machine documents. Code-unit comparison, not
 * locale collation, so the order is identical on every host.
 */
export declare const unitsByStableIdentity: <Output>(units: ReadonlyArray<ResolvedUnit<Output>>) => ReadonlyArray<ResolvedUnit<Output>>;
export interface MakeOperationResolutionArgs<Output> {
    readonly name: string;
    readonly description: Option.Option<string>;
    readonly mode: "preview" | "apply";
    readonly atomicity: OperationAtomicity;
    readonly units: ReadonlyArray<ResolvedUnit<Output>>;
    readonly candidateId?: string | undefined;
    readonly declined?: boolean | undefined;
    readonly blocking?: OperationBlock | undefined;
    readonly failure?: AppError | undefined;
    readonly interruption?: OperationInterruption | undefined;
    readonly divergence?: boolean | undefined;
    readonly footprint?: ReadonlyArray<OperationFootprintEntry> | undefined;
    readonly recovery?: OperationRecovery | undefined;
    readonly presentation?: OperationPresentation | undefined;
    readonly releaseAge?: ReleaseAgeOperationEvidence | undefined;
    readonly preconditions?: ReadonlyArray<OperationPrecondition> | undefined;
    readonly riskConditions?: ReadonlyArray<PlanRiskCondition> | undefined;
    readonly suggestions?: ReadonlyArray<SuggestedAction> | undefined;
}
export declare const makeOperationResolution: <Output = never>(args: MakeOperationResolutionArgs<Output>) => OperationResolution<Output>;
/** The atomicity class a plan declares; local plans default closure-atomic. */
export declare const declaredAtomicity: (plan: {
    readonly executionCapabilities?: {
        readonly rollback: "local-atomic" | "non-rollbackable";
    };
}) => AtomicityClass;
//# sourceMappingURL=operation-resolution.d.ts.map