/**
 * TransportAgent — SAP Basis-inspired configuration transport layer
 *
 * Manages the safe promotion of configuration artefacts between deployment
 * environments. Enforces the AuthGuardian permission wall, drains in-flight
 * agent pools before promoting, runs an optional canary window, and rolls
 * back on a violation spike.
 *
 * State machine:
 *   pending → draining → promoting → canary → complete
 *                                           ↘ rolled_back
 *                       ↘ failed (auth denied / prerequisite missing / lock conflict)
 *
 * Blackboard keys (written by TransportAgent only):
 *   transport:request:<trId>  — original request (written once by submitRequest)
 *   transport:status:<trId>   — mutable status record (updated each state change)
 *   transport:lock:<toEnv>    — advisory lock preventing concurrent promotions
 *
 * @module TransportAgent
 * @version 1.0.0
 */
import type { LockedBlackboard } from './locked-blackboard';
import type { EnvironmentManager, EnvName, PromotionResult } from './env-manager';
import type { ComplianceMonitor } from './compliance-monitor';
import type { AuthGuardian } from './auth-guardian';
import type { AgentPool } from './strategy-agent';
/** Lifecycle states of a transport request. */
export type TransportStatus = 'pending' | 'draining' | 'promoting' | 'canary' | 'complete' | 'rolled_back' | 'failed';
/**
 * A request to promote configuration artefacts from one environment to another.
 * Submit via {@link TransportAgent.submitRequest}.
 */
export interface TransportRequest {
    /** Source environment name. */
    fromEnv: EnvName;
    /** Destination environment name. */
    toEnv: EnvName;
    /** Human-readable reason for this promotion (logged to audit trail). */
    reason: string;
    /** Operator identity used for confirm/approval gates (e.g. 'ops-lead'). */
    operator?: string;
    /** TR IDs that must be in 'complete' state before this TR can start. */
    prerequisites?: string[];
    /** Canary window in milliseconds. 0 = skip canary phase. Default: 30 000. */
    canaryWindowMs?: number;
    /** Maximum new compliance violations tolerated during canary. Default: 0. */
    canaryMaxViolations?: number;
    /** Percentage of pool slots to re-open during canary (1–100). Default: 20. */
    canaryPercent?: number;
}
/** Live snapshot of a transport request written to the blackboard. */
export interface TransportStatusRecord {
    trId: string;
    status: TransportStatus;
    fromEnv: EnvName;
    toEnv: EnvName;
    reason: string;
    operator?: string;
    submittedAt: string;
    startedAt?: string;
    completedAt?: string;
    /** Backup ID captured before promotion — used for rollback. */
    backupId?: string;
    promotionResult?: PromotionResult;
    /** Number of new compliance violations detected during the canary window. */
    violationsDetected?: number;
    error?: string;
}
/** Options for constructing a {@link TransportAgent}. */
export interface TransportAgentOptions {
    /** Blackboard used as the coordination medium. */
    blackboard: LockedBlackboard;
    /** Environment manager for promote/backup/restore operations. */
    envManager: EnvironmentManager;
    /** AuthGuardian that gates every ENVIRONMENT_PROMOTE request. */
    authGuardian: AuthGuardian;
    /** Agent pools to drain before each promotion. Optional — pass all active pools. */
    pools?: AgentPool[];
    /** ComplianceMonitor for canary violation detection. Optional. */
    complianceMonitor?: ComplianceMonitor;
    /** Agent ID used for blackboard writes. Default: `'basis:transport'`. */
    agentId?: string;
    /** Poll interval in ms for new pending TRs. Default: 5 000. */
    pollIntervalMs?: number;
    /** Maximum ms to wait for in-flight pool agents to finish draining. Default: 60 000. */
    drainTimeoutMs?: number;
    /** Path to append JSON-L audit entries. Default: `data/audit_log.jsonl`. */
    auditLogPath?: string;
}
/**
 * SAP Basis-inspired transport agent for environment promotion.
 *
 * @example
 * ```typescript
 * const agent = new TransportAgent({ blackboard, envManager, authGuardian, pools });
 * agent.start();
 *
 * // From any agent — submit a transport request:
 * const trId = TransportAgent.submitRequest(blackboard, {
 *   fromEnv: 'dev', toEnv: 'st', reason: 'Sprint 42 config', operator: 'dev-lead',
 * });
 * ```
 */
export declare class TransportAgent {
    private readonly _blackboard;
    private readonly _envManager;
    private readonly _authGuardian;
    private readonly _pools;
    private readonly _complianceMonitor;
    private readonly _agentId;
    private readonly _pollIntervalMs;
    private readonly _drainTimeoutMs;
    private readonly _auditLogPath;
    private _pollHandle;
    private _running;
    private _processing;
    constructor(options: TransportAgentOptions);
    /**
     * Start the transport agent's poll loop.
     * Processes pending transport requests at `pollIntervalMs` intervals.
     */
    start(): void;
    /**
     * Stop the poll loop.
     * In-flight transports already in progress will run to completion.
     */
    stop(): void;
    /** Whether the agent is currently running. */
    get isRunning(): boolean;
    /**
     * Manually execute a single transport request by ID (one-shot).
     * Useful for testing and CLI invocation.
     *
     * @param trId - Transport request ID as returned by {@link TransportAgent.submitRequest}.
     * @throws if the TR does not exist on the blackboard.
     */
    execute(trId: string): Promise<TransportStatusRecord>;
    /**
     * Submit a new transport request to the blackboard.
     * Any agent may call this; only {@link TransportAgent} will execute it.
     *
     * @returns The generated transport request ID (`trId`).
     */
    static submitRequest(blackboard: LockedBlackboard, request: TransportRequest): string;
    private _pollOnce;
    private _runTransport;
    /** Pause dispatch on all pools tagged for `env`. Returns the paused pools. */
    private _drainPools;
    /** Resume dispatch on `pools` at `percent` capacity. */
    private _resumePools;
    /**
     * Wait for all actively-running agents in the given pools to finish,
     * up to `_drainTimeoutMs`. Proceeds even if timeout is reached
     * (pools remain paused — only newly spawned agents are blocked).
     */
    private _waitForDrain;
    private _writeAudit;
}
//# sourceMappingURL=transport-agent.d.ts.map