/**
 * Atomic Idempotent Operation Admission
 *
 * Defines the durable operation admission contract for FeltDB.
 * Guarantees: exactly one operation identity per idempotency key,
 * atomic durability, and convergence across concurrent callers.
 */
import type { AuthorityScope } from './authority-scope.js';
/**
 * Input contract for admitting a durable operation
 */
export interface OperationAdmissionInput {
    /** Unique idempotency key supplied by caller */
    idempotencyKey: string;
    /** Operation kind (e.g., "execution", "coordination", "verification") */
    kind: string;
    /** Optional immutable operation fingerprint for conflict detection */
    operationFingerprint?: string;
    /** Caller-supplied metadata */
    metadata?: Record<string, unknown>;
    /** Optional serialized scope on replay; canonical sessions bind it automatically. */
    authorityScope?: AuthorityScope;
}
/**
 * Operation lifecycle status
 */
export type OperationStatus = 'accepted' | 'executing' | 'completed' | 'failed' | 'cancelled';
/**
 * Durable operation record with versioned lifecycle
 */
export interface DurableOperation {
    /** FeltDB-generated operation identity (ULIDv7 or similar) */
    operationId: string;
    /** Caller's idempotency key */
    idempotencyKey: string;
    /** Operation kind (immutable) */
    kind: string;
    /** Current operation status in lifecycle */
    status: OperationStatus;
    /** Version number (increments by 1 on each successful transition) */
    version: number;
    /** Timestamp when operation was admitted */
    createdAt: number;
    /** Timestamp when execution started */
    startedAt?: number;
    /** Timestamp when operation terminal state reached */
    completedAt?: number;
    /** Operation fingerprint for conflict detection */
    operationFingerprint?: string;
    /** Caller metadata */
    metadata?: Record<string, unknown>;
    /** Durable authority partition in which this operation was admitted. */
    authorityScope?: AuthorityScope;
    /** Result/outcome for terminal states */
    resultSnapshot?: unknown;
    /** Error message for failed operations */
    error?: string;
}
/**
 * Result of an operation admission attempt
 */
export interface OperationAdmissionResult {
    /** True if this caller admitted the operation; false if it already existed */
    admitted: boolean;
    /** FeltDB-generated operation identity (same for all callers with same idempotencyKey) */
    operationId: string;
    /** The durable operation record */
    operation: DurableOperation;
}
/**
 * Conflict error when idempotency key is reused with different operation semantics
 */
export interface IdempotencyConflictError {
    code: 'IDEMPOTENCY_CONFLICT';
    idempotencyKey: string;
    existingKind: string;
    requestedKind: string;
    existingFingerprint?: string;
    requestedFingerprint?: string;
    message: string;
}
/**
 * Input for atomic operation lifecycle transition
 */
export interface OperationTransitionInput {
    /** Operation ID to transition */
    operationId: string;
    /** Expected current version (for CAS) */
    expectedVersion: number;
    /** Target status after transition */
    to: OperationStatus;
    /** Result data for terminal states */
    resultSnapshot?: unknown;
    /** Error message for failed operations */
    error?: string;
    /** Metadata for the transition event */
    metadata?: Record<string, unknown>;
    /** Optional serialized scope on replay; canonical sessions bind it automatically. */
    authorityScope?: AuthorityScope;
}
/**
 * Result of a transition attempt
 */
export interface OperationTransitionResult {
    /** True if transition succeeded */
    transitioned: boolean;
    /** Reason for failure (if transitioned = false) */
    reason?: 'VERSION_CONFLICT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
    /** Current operation state (after transition or at rejection) */
    operation: DurableOperation;
}
/**
 * Validates operation admission inputs
 */
export declare function validateOperationAdmissionInput(input: OperationAdmissionInput): {
    valid: boolean;
    error?: string;
};
/**
 * Checks if two operations conflict based on immutable semantics
 */
export declare function operationsConflict(existing: DurableOperation, requested: OperationAdmissionInput): IdempotencyConflictError | null;
/**
 * Generates a stable operation ID
 * In production, use ULIDv7 for sortability and distributed uniqueness
 */
export declare function generateOperationId(): string;
/**
 * Validates that a transition is legal according to the state machine
 */
export declare function isValidTransition(fromStatus: OperationStatus, toStatus: OperationStatus): boolean;
/**
 * Checks if a status is a terminal state
 */
export declare function isTerminalStatus(status: OperationStatus): boolean;
/**
 * Validates transition input
 */
export declare function validateTransitionInput(input: OperationTransitionInput): {
    valid: boolean;
    error?: string;
};
/**
 * Checks if a terminal transition is idempotent
 * (same result data means it's the same transition, not a new one)
 */
export declare function isIdempotentTerminalTransition(existingOp: DurableOperation, requestedResult?: unknown, requestedError?: string): boolean;
//# sourceMappingURL=operation-admission.d.ts.map