/**
 * FSM Journey Layer — Phase 4: Behavioral Control Plane
 *
 * Implements state machine–based workflow authorization. Agents can only act
 * in their designated states, and tools can only be called when the current
 * workflow state permits it.
 *
 * @module fsm-journey
 */
/** Named workflow states. Extend by passing custom string literals. */
export type WorkflowStateName = string;
/** Built-in canonical workflow states for common agent pipelines. */
export declare const WORKFLOW_STATES: {
    readonly INTAKE: "INTAKE";
    readonly VALIDATE: "VALIDATE";
    readonly RESEARCH: "RESEARCH";
    readonly PLAN: "PLAN";
    readonly EXECUTE: "EXECUTE";
    readonly REVIEW: "REVIEW";
    readonly DELIVER: "DELIVER";
    readonly COMPLETE: "COMPLETE";
    readonly ERROR: "ERROR";
    /** Coverage Gate refinement loop — orchestrator is re-evaluating completeness. */
    readonly EVALUATING: "EVALUATING";
};
/** A single state definition in the FSM. */
export interface WorkflowStateDefinition {
    /** Unique state name */
    name: WorkflowStateName;
    /** Human-readable description */
    description?: string;
    /** Agents authorised to perform actions in this state. '*' means any. */
    authorizedAgents: string[];
    /** Tools authorised in this state, keyed by agentId ('*' = any agent). */
    authorizedTools?: Record<string, string[]>;
    /** Maximum time (ms) the FSM may remain in this state before it's a violation. */
    timeoutMs?: number;
}
/** A named transition between two states triggered by an event. */
export interface StateTransition {
    from: WorkflowStateName;
    event: string;
    to: WorkflowStateName;
    /** If set, only this agent (or '*') may fire this transition. */
    allowedBy?: string;
}
/** Describes what happened when a state transition was attempted. */
export interface TransitionResult {
    success: boolean;
    previousState: WorkflowStateName;
    currentState: WorkflowStateName;
    reason?: string;
}
/** Result from an inline compliance check. */
export interface ComplianceCheckResult {
    allowed: boolean;
    reason?: string;
    currentState: WorkflowStateName;
    agentId: string;
    tool?: string;
}
/** Options passed to JourneyFSM constructor. */
export interface JourneyFSMOptions {
    states: WorkflowStateDefinition[];
    transitions: StateTransition[];
    initialState: WorkflowStateName;
    /** Called whenever a transition fires (success or failure). */
    onTransition?: (result: TransitionResult, agentId: string) => void;
    /** Called whenever a compliance violation is blocked. */
    onViolation?: (check: ComplianceCheckResult) => void;
}
/**
 * Standalone tool authorization matrix.
 *
 * Maps `agentId -> state -> allowedTools[]`.
 * The FSM embeds one automatically, but you can also use this independently.
 *
 * @example
 * ```typescript
 * const matrix = new ToolAuthorizationMatrix();
 * matrix.allow('data_analyst', 'RESEARCH', ['search_web', 'query_db']);
 * matrix.allow('*', 'REVIEW', ['read_blackboard']);
 * matrix.isAllowed('data_analyst', 'RESEARCH', 'query_db'); // true
 * ```
 */
export declare class ToolAuthorizationMatrix {
    private rules;
    /**
     * Grant an agent permission to use a list of tools in a given state.
     * Use `'*'` for agentId or toolNames to mean "all".
     */
    allow(agentId: string, state: WorkflowStateName, tools: string[]): void;
    /** Revoke a specific tool permission. */
    revoke(agentId: string, state: WorkflowStateName, tool: string): void;
    /**
     * Check if an agent is allowed to use a tool in a given state.
     * Checks exact agentId first, then falls back to '*' wildcard.
     */
    isAllowed(agentId: string, state: WorkflowStateName, tool: string): boolean;
    private _check;
    /** Dump current rules for debugging/audit. */
    dump(): Record<string, Record<string, string[]>>;
}
/**
 * Finite-state machine for workflow authorization.
 *
 * Governs which agents can act (and with which tools) based on the current
 * workflow state. Integrates an inline `ComplianceMiddleware` and a
 * `ToolAuthorizationMatrix`.
 *
 * @example
 * ```typescript
 * import { JourneyFSM, WORKFLOW_STATES } from 'network-ai';
 *
 * const fsm = new JourneyFSM({
 *   states: [
 *     { name: 'INTAKE',   authorizedAgents: ['orchestrator'],  authorizedTools: { orchestrator: ['read_intake'] } },
 *     { name: 'RESEARCH', authorizedAgents: ['data_analyst'],  authorizedTools: { data_analyst: ['query_db', 'search_web'] } },
 *     { name: 'DELIVER',  authorizedAgents: ['orchestrator'],  authorizedTools: { '*': ['write_blackboard'] } },
 *   ],
 *   transitions: [
 *     { from: 'INTAKE',   event: 'start_research', to: 'RESEARCH', allowedBy: 'orchestrator' },
 *     { from: 'RESEARCH', event: 'research_done',  to: 'DELIVER',  allowedBy: '*' },
 *   ],
 *   initialState: 'INTAKE',
 * });
 *
 * fsm.transition('start_research', 'orchestrator'); // moves to RESEARCH
 * fsm.canAgentAct('data_analyst'); // true — we're now in RESEARCH
 * ```
 */
export declare class JourneyFSM {
    private currentState;
    private stateMap;
    private transitions;
    private options;
    private stateEnteredAt;
    private history;
    /** Embedded tool authorization matrix (populated from state definitions). */
    readonly toolMatrix: ToolAuthorizationMatrix;
    constructor(options: JourneyFSMOptions);
    /** Current workflow state name. */
    get state(): WorkflowStateName;
    /** Full definition of the current state. */
    get stateDefinition(): WorkflowStateDefinition;
    /** How long (ms) the FSM has been in the current state. */
    get timeInCurrentState(): number;
    /** Whether the current state has timed out. */
    get isTimedOut(): boolean;
    /** Full transition history. */
    get transitionHistory(): ReadonlyArray<{
        state: WorkflowStateName;
        enteredAt: number;
        exitedAt?: number;
        triggeredBy?: string;
    }>;
    /**
     * Check if an agent is authorized to perform any action in the current state.
     */
    canAgentAct(agentId: string): boolean;
    /**
     * Check if an agent is authorized to use a specific tool in the current state.
     * Checks both the tool matrix AND agent authorization.
     */
    canAgentUseTool(agentId: string, tool: string): boolean;
    /**
     * Inline compliance check — call this BEFORE executing any agent action.
     * Returns `{ allowed: true }` or `{ allowed: false, reason }`.
     */
    checkCompliance(agentId: string, tool?: string): ComplianceCheckResult;
    /**
     * Fire a named event to transition the FSM to the next state.
     * Returns a `TransitionResult` describing what happened.
     */
    transition(event: string, agentId: string): TransitionResult;
    /**
     * Returns all events available from the current state.
     */
    availableEvents(): string[];
    /**
     * Returns which agents are authorized in a given state (defaults to current).
     */
    getAuthorizedAgents(stateName?: WorkflowStateName): string[];
    /**
     * Reset the FSM to its initial state.
     */
    reset(): void;
}
/**
 * Wraps an async action and blocks its execution if the FSM denies it.
 *
 * @example
 * ```typescript
 * const middleware = new ComplianceMiddleware(fsm);
 *
 * const result = await middleware.enforce('data_analyst', 'query_db', async () => {
 *   return await db.query('SELECT * FROM invoices');
 * });
 * ```
 */
export declare class ComplianceMiddleware {
    private fsm;
    constructor(fsm: JourneyFSM);
    /**
     * Enforce compliance before running `action`.
     * Throws if not authorized; returns the action's result if allowed.
     */
    enforce<T>(agentId: string, tool: string, action: () => Promise<T>): Promise<T>;
    /**
     * Synchronous version — use when the action is not async.
     */
    enforceSync<T>(agentId: string, tool: string, action: () => T): T;
}
/** Thrown when ComplianceMiddleware blocks an action. */
export declare class ComplianceViolationError extends Error {
    readonly check: ComplianceCheckResult;
    constructor(message: string, check: ComplianceCheckResult);
}
/**
 * Build a standard delivery pipeline FSM with sensible defaults.
 * States: INTAKE → VALIDATE → RESEARCH → PLAN → EXECUTE → REVIEW → DELIVER → COMPLETE
 *
 * @example
 * ```typescript
 * const fsm = createDeliveryPipelineFSM({
 *   orchestratorId: 'orchestrator',
 *   researchAgentId: 'data_analyst',
 *   executorId: 'code_writer',
 * });
 * ```
 */
export declare function createDeliveryPipelineFSM(options: {
    orchestratorId?: string;
    researchAgentId?: string;
    executorId?: string;
    reviewerId?: string;
    onTransition?: JourneyFSMOptions['onTransition'];
    onViolation?: JourneyFSMOptions['onViolation'];
}): JourneyFSM;
//# sourceMappingURL=fsm-journey.d.ts.map