/**
 * AutonomySpectrumEnforcer -- Controlled autonomy Level 0-4 gate.
 *
 * Implements the SAE-inspired controlled autonomy spectrum for AI agents.
 * Operators set the autonomy level; agents cannot self-elevate.
 *
 * Levels:
 *   Level 0 -- Manual:      Every action requires human pre-approval.
 *   Level 1 -- Assisted:    Read-only actions execute; mutating actions queue.
 *   Level 2 -- Conditional: Mutating actions in pre-approved class execute;
 *                            others queue.
 *   Level 3 -- Bounded:     Mutating actions within blast-radius limits execute;
 *                            over-limit or undeclared scope queues or denies.
 *   Level 4 -- Autonomous:  All actions execute except explicitly gated classes.
 *
 * Critical invariants:
 *   - No self-elevation: only OPERATOR_ADMIN (ADMIN role) can call setLevel.
 *   - Strict packs (HIPAA, GDPR, PCI DSS, HMDA, DORA) cap at Level 3 without
 *     explicit attestation. Level 4 + strict pack without attestation throws.
 *   - Pack binding is mandatory on all writes.
 *   - Every level change emits AUTONOMY_LEVEL_CHANGED at severity ERROR.
 *   - Self-elevation attempts emit AUTONOMY_SELF_ELEVATION_ATTEMPT at severity ERROR.
 *
 * Declaration-based limitation (honest documentation):
 *   The blast-radius (L3) and action-class (L2) gates trust the agent's
 *   declaration. An agent can lie about its blast radius or class. The
 *   compensating control is audit recording: the declared value is written
 *   to the audit chain so forensic analysis can detect post-hoc discrepancies.
 *   Additionally:
 *   - blastRadius.systemsTouched === 0 on a mutating action emits
 *     BLAST_RADIUS_DECLARED_ZERO (warning) because zero is suspicious.
 *   - Class-frequency tracking emits CLASS_BURST_THRESHOLD_EXCEEDED when an
 *     agent uses a high-trust class more than classBurstThreshold times in
 *     a single cycle (default: 10).
 *
 * BUILD_PLAN_V3_FULL_LIFECYCLE.md line 266: "Controlled autonomy spectrum
 * enforcement (Level 0 through 4, no self-elevation) -- partial; need
 * Level enforcement gate".
 *
 * Compliance bindings:
 *   HIPAA 164.308(a)(3): Workforce authorization and supervision
 *   SOC 2 CC6.1: Logical access restrictions
 *   GDPR Art. 22: Automated decision-making controls
 *   DORA Art. 16: ICT risk management -- automation limits
 *   PCI DSS Req 7: Restrict access by need-to-know
 *
 * @connexum/ai-governance P3-T1
 */
export declare class EmptyPackBindingError extends Error {
    constructor(operation: string);
}
export declare class Level4RequiresAttestationForStrictPackError extends Error {
    readonly orgId: string;
    readonly agentId: string;
    readonly packBinding: string[];
    readonly strictPacks: string[];
    constructor(opts: {
        orgId: string;
        agentId: string;
        packBinding: string[];
        strictPacks: string[];
    });
}
export declare class SelfElevationAttemptError extends Error {
    constructor(agentId: string, requestedLevel: AutonomyLevel);
}
export declare class InvalidAutonomyLevelError extends Error {
    constructor(level: unknown);
}
export declare class MissingApproverIdentityError extends Error {
    constructor();
}
export declare class MissingReasonError extends Error {
    constructor();
}
export declare class UnauthorizedOperatorError extends Error {
    readonly approverIdentity: string;
    constructor(approverIdentity: string, detail: string);
}
export type AutonomyLevel = 0 | 1 | 2 | 3 | 4;
export type GuardDecision = 'execute' | 'approval-required' | 'denied';
export interface BlastRadius {
    /** Number of distinct systems touched. */
    systemsTouched: number;
    /** Financial impact in US cents. */
    financialImpactCents?: number;
    /** Number of users affected. */
    usersAffected?: number;
}
export interface BlastRadiusLimits {
    maxSystemsTouched: number;
    maxFinancialImpactCents?: number;
    maxUsersAffected?: number;
}
export interface GuardAction {
    /** Human-readable action identifier (e.g., 'read-patient-record', 'send-email'). */
    kind: string;
    /** True if this action changes persistent state. */
    mutates: boolean;
    /**
     * Action class for Level 2 pre-approval matching and Level 4 gating.
     * Examples: 'customer-email-template', 'production-write'.
     */
    class?: string;
    /**
     * Declared blast radius. REQUIRED for mutating actions at Level 3.
     * Declaration-based: the gate trusts the declaration and records it.
     * A zero systemsTouched value emits a BLAST_RADIUS_DECLARED_ZERO warning.
     */
    blastRadius?: BlastRadius;
}
export interface GuardResult {
    decision: GuardDecision;
    reason: string;
    /** Approval request ID when decision is 'approval-required'. */
    approvalRequestId?: string;
}
export type AutonomyEventKind = 'AUTONOMY_LEVEL_CHANGED' | 'AUTONOMY_SELF_ELEVATION_ATTEMPT' | 'AUTONOMY_ACTION_GUARDED' | 'BLAST_RADIUS_DECLARED_ZERO' | 'CLASS_BURST_THRESHOLD_EXCEEDED';
export interface AutonomyAuditEvent {
    type: AutonomyEventKind;
    severity: 'INFO' | 'WARN' | 'ERROR';
    orgId: string;
    agentId: string;
    timestamp: string;
    prevStateHash?: string;
    currentStateHash?: string;
    data: Record<string, unknown>;
}
export type AutonomyAuditSink = (event: AutonomyAuditEvent) => void;
export interface AutonomySpectrumConfig {
    /**
     * Directory for OperatorRoles persistence. The enforcer uses OperatorRoles
     * to verify approverIdentity has ADMIN role.
     */
    operatorsDir: string;
    /**
     * Sink for audit events. All level changes and gate decisions are emitted.
     * Defaults to no-op if not provided (unit-test friendly).
     */
    auditSink?: AutonomyAuditSink;
    /**
     * How many times an agent may invoke the same class in one cycle before
     * CLASS_BURST_THRESHOLD_EXCEEDED is emitted. Default: 10.
     * Per PT-AUTONOMY-3 compensating control spec.
     */
    classBurstThreshold?: number;
    /**
     * Optional inline operator registry for testing: map of identity string to role.
     * When provided, the OperatorRoles file-based system is bypassed and this map
     * is consulted instead. ONLY for unit tests -- do not use in production.
     */
    _testOperatorMap?: Map<string, 'ADMIN' | 'OPERATOR' | 'VIEWER'>;
}
export declare class AutonomySpectrumEnforcer {
    private operatorRoles;
    private auditSink;
    private classBurstThreshold;
    private testOperatorMap;
    /** State per (orgId, agentId) key. */
    private state;
    /** Running SHA-256 chain for audit continuity. */
    private chainHead;
    constructor(config: AutonomySpectrumConfig);
    /**
     * Set the autonomy level for an (orgId, agentId) pair.
     *
     * Throws:
     *   - EmptyPackBindingError if packBinding is empty.
     *   - MissingReasonError if reason is empty.
     *   - MissingApproverIdentityError if approverIdentity is empty.
     *   - UnauthorizedOperatorError if approverIdentity does not have ADMIN role.
     *   - SelfElevationAttemptError if the approverIdentity is the agent itself
     *     (detected via 'agent:' prefix convention).
     *   - InvalidAutonomyLevelError if level is not 0-4.
     *   - Level4RequiresAttestationForStrictPackError if level is 4 and any
     *     strict pack is in packBinding without adequate attestation reason.
     */
    setLevel(orgId: string, agentId: string, level: AutonomyLevel, reason: string, approverIdentity: string, packBinding: string[]): void;
    /**
     * Get the current autonomy level for an (orgId, agentId) pair.
     * Returns Level 1 (Assisted) if never explicitly set -- safe default.
     */
    getLevel(orgId: string, agentId: string): AutonomyLevel;
    /**
     * Pre-execution gate. Returns a decision on whether the action may execute.
     *
     * Decision logic:
     *   Level 0: always 'approval-required'.
     *   Level 1: read-only -> execute; mutating -> approval-required.
     *   Level 2: read-only -> execute; mutating in-class -> execute; else approval-required.
     *   Level 3: as L2, plus mutating out-of-class within blast limits -> execute;
     *             over-limit -> approval-required; missing blastRadius -> denied.
     *   Level 4: execute unless action.class in requireApprovalEvenAtLevel4 list.
     *
     * Always routes 'approval-required' to the internal overflow tracker
     * (ApprovalQueue integration point via the returned approvalRequestId).
     */
    guardAction(orgId: string, agentId: string, action: GuardAction, packBinding: string[]): GuardResult;
    /**
     * Register pre-approved action classes for Level 2 execution.
     * Only ADMIN operators can configure this.
     */
    configurePreApprovedClasses(orgId: string, agentId: string, classes: string[], approverIdentity: string, packBinding: string[]): void;
    /**
     * Configure blast-radius limits for Level 3 execution.
     * Only ADMIN operators can configure this.
     */
    configureBlastRadius(orgId: string, agentId: string, limits: BlastRadiusLimits, approverIdentity: string, packBinding: string[]): void;
    /**
     * Configure which action classes still require approval at Level 4.
     * The default set (production-write, external-pr-comms, financial-transaction)
     * is pre-loaded per instance; this method merges additional classes.
     */
    addRequiredApprovalClassesAtLevel4(orgId: string, agentId: string, classes: string[], approverIdentity: string, packBinding: string[]): void;
    /**
     * Reset class frequency counters. Call at the start of each cycle.
     * This is a lightweight operation -- agents manage their own cycle boundaries.
     */
    resetCycleCounters(orgId: string, agentId: string): void;
    private stateKey;
    private getAgentState;
    private genesisHash;
    private emitEvent;
    private makeApprovalRequired;
    private blastRadiusExceedsLimits;
    /**
     * Verify that approverIdentity has ADMIN role.
     *
     * Self-elevation via 'agent:' prefix is already caught before this method
     * is called in setLevel(). This method handles the RBAC check.
     *
     * Two modes:
     *   1. _testOperatorMap: used in unit tests -- a plain Map<identity, role>.
     *   2. OperatorRoles file store: used in production.
     *
     * The identity string is the operator's name (as registered in OperatorRoles).
     * In production: operators register via OperatorRoles.createOperator(),
     * and their name is the approverIdentity string.
     */
    private verifyOperatorIdentity;
}
/**
 * verifyOperatorIdentity -- standalone helper for callers that do not
 * instantiate a full AutonomySpectrumEnforcer.
 *
 * Used by test scaffolding and integration code that needs a quick RBAC check
 * before delegating to the enforcer.
 */
export declare function verifyOperatorIdentity(approverIdentity: string, operatorsDir: string): {
    authorized: boolean;
    reason: string;
};
//# sourceMappingURL=autonomy-spectrum.d.ts.map