/**
 * One cross-runtime boundary for owned external effects. It centralizes correlation, lifecycle
 * evidence, cancellation, durable transition ordering, and token-only observation without relying
 * on Node-only async-local state.
 */
import { type EffectLifecycleObserver, type EffectLifecycleStage, type EffectTraceParent } from "./effect-lifecycle.js";
import { type EffectMetadata } from "./ledger.js";
export interface EffectScopeEvidence {
    readonly began: boolean;
    readonly committed: boolean;
    readonly ambiguous: boolean;
}
export interface OwnedEffectContext extends EffectMetadata {
    readonly effectId: string;
    readonly capability: string;
    readonly stage: Exclude<EffectLifecycleStage, "admission" | "reconciliation">;
    readonly signal: AbortSignal;
    readonly attempt?: number;
}
export interface OwnedEffectTransitions<T> {
    intent?(context: OwnedEffectContext): void | PromiseLike<void>;
    executing?(context: OwnedEffectContext): void | PromiseLike<void>;
    committed?(context: OwnedEffectContext, result: T): void | PromiseLike<void>;
    failed?(context: OwnedEffectContext, input: {
        readonly began: boolean;
        readonly errorCode: string;
        readonly error: unknown;
    }): void | PromiseLike<void>;
}
export interface OwnedEffectRunOptions<T> extends EffectMetadata {
    readonly effectId?: string;
    readonly capability: string;
    readonly stage?: Exclude<EffectLifecycleStage, "admission" | "reconciliation">;
    readonly signal?: AbortSignal;
    readonly attempt?: number;
    readonly trace?: EffectTraceParent;
    /** Per-run observers, combined with the scope's observers. */
    readonly observers?: readonly EffectLifecycleObserver[];
    /** Optional admission boundary executed before the effect is marked as begun. */
    readonly admit?: (context: OwnedEffectContext) => void | PromiseLike<void>;
    readonly transitions?: OwnedEffectTransitions<T>;
    readonly errorCode?: string | ((error: unknown, began: boolean) => string);
    /** Classify a caught execution failure when the caller can prove it is terminal. */
    readonly failurePhase?: (error: unknown, began: boolean) => "failed" | "ambiguous";
}
export interface EffectScopeOptions {
    readonly observers?: readonly EffectLifecycleObserver[];
    readonly signal?: AbortSignal;
    readonly effectId?: () => string;
}
export interface EffectEvidenceScope {
    evidence(): EffectScopeEvidence;
    /** Legacy/manual effects cannot prove a terminal outcome and therefore become ambiguous. */
    markBegan(): void;
    /** Pair a prior manual `markBegan()` with a proven commit. */
    markCommitted(): void;
    /** Preserve uncertainty when a caller loses the terminal outcome. */
    markAmbiguous(): void;
    /** Settle one begun effect as a proven terminal failure without claiming it committed. */
    markFailed(): void;
    /**
     * Declare that the enclosing request may release its idempotency reservation if it returns a
     * server error before any owned effect begins.
     */
    markSafeToRetry(): void;
    /** True only while the retry declaration remains backed by evidence that no effect began. */
    safeToRetry(): boolean;
}
export interface EffectScope extends EffectEvidenceScope {
    run<T>(options: OwnedEffectRunOptions<T>, execute: (context: OwnedEffectContext) => T | PromiseLike<T>): Promise<T>;
}
/** Lightweight aggregate evidence shared by request idempotency and full owned-effect runners. */
export declare function createEffectEvidenceScope(): EffectEvidenceScope;
export declare function createEffectScope(options?: EffectScopeOptions, evidenceScope?: EffectEvidenceScope): EffectScope;
//# sourceMappingURL=effect-scope.d.ts.map