/**
 * CapabilityChangeDetector -- Hash-based capability change detection with
 * auto-suspension and versioned attestation history.
 *
 * Implements BUILD_PLAN_V3_FULL_LIFECYCLE.md lines 285-289 (Tier 3
 * self-learning governance):
 *   Line 285: Agent capability change detection.
 *   Line 286: Automatic suspension on undocumented capability change.
 *   Line 287: Approval queue entry for documented capability changes,
 *             requiring re-attestation workflow.
 *   Line 288: Versioned audit of agent capability over time.
 *   Line 289: Refusal-to-operate mode if capability evolution is configured
 *             without the attestation workflow enabled.
 *
 * Three-state model:
 *   verified           -- current hash matches latest registered version.
 *   pending-attestation -- hash changed; attestation workflow ENABLED;
 *                          agent runs at Level 0 until operator resolves.
 *   suspended          -- hash changed; attestation workflow NOT enabled
 *                          (or operator denied); agent refuses all calls.
 *
 * Refusal-to-operate (line 289):
 *   Strict packs (HIPAA, GDPR, PCI DSS, HMDA, DORA) require the
 *   attestation workflow to be enabled when capability-evolution-allowed
 *   is set. Without it, every runtime invocation throws
 *   CapabilityEvolutionWithoutAttestationWorkflowError.
 *
 * Capability hash inputs (canonicalized, sorted):
 *   orgId + agentId + toolset (sorted) + permissions (sorted) +
 *   webAccessTier + hookProfile + autonomyLevel + packBindings (sorted).
 *
 * Audit chain: every event includes prevSha for SHA-256 chaining.
 * History integrity: each version entry references the SHA of the prior
 * entry; tampering breaks the chain and emits CAPABILITY_HISTORY_TAMPERED.
 *
 * Pen-tests shipped:
 *   PT-CAPABILITY-1: hash-collision attack (orgId+agentId scoping).
 *   PT-CAPABILITY-2: history-tampering via chain verification.
 *   PT-CAPABILITY-3: workflow-state forgery from agent runtime context.
 *
 * Compliance bindings:
 *   HIPAA 164.308(a)(3): Workforce authorization and supervision
 *   HIPAA 164.312(c)(1): Integrity controls
 *   SOC 2 CC6.1: Logical access restrictions
 *   SOC 2 CC7.2: System monitoring for tampering
 *   GDPR Art. 22: Automated decision-making controls
 *   DORA Art. 16: ICT risk management -- automation limits
 *   EU AI Act Art. 12: Record-keeping requirements
 *   ISO 27001 A.9.2.3: Management of privileged access
 *   ISO 42001 A.9.1: AI system monitoring
 *   NIST 800-53 AU-12: Audit record generation
 *
 * @connexum/ai-governance P3-T3
 */
export declare const STRICT_PACK_IDS: Set<string>;
export declare class EmptyPackBindingError extends Error {
    readonly operation: string;
    constructor(operation: string);
}
export declare class AgentCapabilitySuspendedError extends Error {
    readonly orgId: string;
    readonly agentId: string;
    readonly suspendedReason: string;
    constructor(opts: {
        orgId: string;
        agentId: string;
        suspendedReason: string;
    });
}
export declare class CapabilityEvolutionWithoutAttestationWorkflowError extends Error {
    readonly orgId: string;
    readonly agentId: string;
    readonly strictPacks: string[];
    constructor(opts: {
        orgId: string;
        agentId: string;
        strictPacks: string[];
    });
}
export declare class CapabilityAttestationPermissionError extends Error {
    readonly identity: string;
    constructor(identity: string, detail: string);
}
export declare class CapabilityHistoryTamperedError extends Error {
    readonly orgId: string;
    readonly agentId: string;
    readonly brokenAtVersion: number;
    constructor(opts: {
        orgId: string;
        agentId: string;
        brokenAtVersion: number;
    });
}
/**
 * The canonical capability descriptor that is hashed to detect changes.
 * Read-only: the detector NEVER modifies the bundle. It only reads and hashes.
 *
 * Fields included in the SHA-256 hash (sorted within each array):
 *   orgId, agentId, toolset, permissions, webAccessTier,
 *   hookProfile, autonomyLevel, packBindings.
 */
export interface CapabilityBundleInput {
    /** Sorted list of tool IDs granted to the agent. */
    toolset: string[];
    /** Sorted list of permission identifiers. */
    permissions: string[];
    /** Web access tier: 'NONE' | 'SEARCH_ONLY' | 'READ_ONLY' | 'FULL'. */
    webAccessTier: string;
    /** Hook profile identifier (from PR #21 hook-profile-selector). */
    hookProfile: string;
    /** Autonomy level 0-4 (from PR #24 autonomy-spectrum). */
    autonomyLevel: number;
    /** Sorted list of active compliance pack IDs. */
    packBindings: string[];
    /**
     * When true, the agent is configured to allow capability evolution.
     * Strict-pack agents with this flag must also have the attestation workflow
     * enabled; otherwise the line-289 refusal-to-operate mode kicks in.
     */
    capabilityEvolutionAllowed?: boolean;
}
export type CapabilityEventType = 'CAPABILITY_VERSION_REGISTERED' | 'CAPABILITY_CHANGE_PENDING_ATTESTATION' | 'CAPABILITY_CHANGE_AUTO_SUSPENDED' | 'CAPABILITY_ATTESTATION_WORKFLOW_ENABLED' | 'CAPABILITY_ATTESTATION_APPROVED' | 'CAPABILITY_ATTESTATION_DENIED' | 'CAPABILITY_HISTORY_TAMPERED';
export type AuditSeverity = 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL';
export interface CapabilityAuditEvent {
    type: CapabilityEventType;
    severity: AuditSeverity;
    orgId: string;
    agentId: string;
    packBinding: string[];
    timestamp: string;
    prevSha?: string;
    [key: string]: unknown;
}
export interface CapabilityVersionEntry {
    /** Version number (1-based, monotonically increasing). */
    version: number;
    /** SHA-256 hash of the canonicalized bundle. */
    hash: string;
    /** SHA-256 hash of the prior entry (genesis sentinel for version 1). */
    prevEntryHash: string;
    /** ISO timestamp of registration. */
    registeredAt: string;
    /** Identity of the operator who registered this version. */
    attesterIdentity: string;
    /** Documented reason for this capability version. */
    attestationReason: string;
    /** Snapshot of the bundle at registration time. */
    bundleSnapshot: CapabilityBundleInput;
}
export type CapabilityCheckStatus = 'verified' | 'pending-attestation' | 'suspended';
export interface CapabilityCheckResult {
    status: CapabilityCheckStatus;
    currentHash: string;
    latestRegisteredHash?: string;
    /** Set when status is 'pending-attestation'. */
    approvalQueueId?: string;
}
export declare class CapabilityChangeDetector {
    /** State per `${orgId}::${agentId}` */
    private readonly agentStates;
    /** SHA-256 chain state for audit events (simple in-memory chain). */
    private lastSha;
    /** Audit event callback. */
    private readonly onAudit;
    /**
     * Optional injected permission checker.
     * Signature mirrors OperatorRoles.checkPermission.
     */
    private readonly checkPermission;
    constructor(opts?: {
        /**
         * Callback invoked for every audit event.
         * Wire to AuditIntegrity.append() in production.
         * Must not throw (errors are swallowed internally).
         */
        onAudit?: (event: CapabilityAuditEvent) => void;
        /**
         * Optional permission checker.
         * If provided, called for operator-only operations to verify admin role.
         * Mirrors OperatorRoles.checkPermission signature.
         */
        checkPermission?: (operatorId: string, action: string) => {
            allowed: boolean;
            reason: string;
        };
    });
    /**
     * Compute a deterministic SHA-256 hash over the capability bundle.
     *
     * The canonical input includes orgId and agentId so that hash values are
     * scoped to a specific agent -- a hash computed for agent A cannot satisfy
     * the registered hash for agent B even if their bundles are identical.
     * This defeats PT-CAPABILITY-1 (cross-agent hash substitution).
     *
     * Hash inputs (in this order):
     *   orgId, agentId, toolset (sorted), permissions (sorted),
     *   webAccessTier, hookProfile, autonomyLevel, packBindings (sorted).
     */
    computeCapabilityHash(orgId: string, agentId: string, bundle: CapabilityBundleInput): string;
    /**
     * Register a new capability version for an agent.
     *
     * Operator-only. Computes the bundle hash, appends a new versioned entry
     * to the agent's history, and emits CAPABILITY_VERSION_REGISTERED at
     * severity ERROR.
     *
     * Even a no-op registration (same hash as the previous version) is recorded.
     * Operators may re-register the same bundle to refresh attestation or to
     * explicitly clear a suspension.
     *
     * This is the ONLY way to clear a suspended agent:
     *   1. Operator calls recordCapabilityVersion with the new bundle.
     *   2. Suspension clears.
     *   3. Pending approval entry (if any) is superseded.
     *
     * @throws EmptyPackBindingError if packBinding is empty.
     * @throws CapabilityAttestationPermissionError if identity is not admin.
     */
    recordCapabilityVersion(orgId: string, agentId: string, bundle: CapabilityBundleInput, attesterIdentity: string, attestationReason: string, packBinding: string[]): CapabilityVersionEntry;
    /**
     * Check whether the current bundle matches the latest registered version.
     *
     * Called at agent startup and on every capability-mutation attempt.
     *
     * Three outcomes:
     *   verified           -- hashes match. Agent operates normally.
     *   pending-attestation -- mismatch + attestation workflow ENABLED.
     *                          Agent runs at Level 0 (degraded) until resolved.
     *   suspended          -- mismatch + attestation workflow NOT enabled.
     *                          Agent must not execute anything.
     *
     * Refusal-to-operate check (line 289):
     *   If the bundle has capabilityEvolutionAllowed: true AND the pack
     *   binding includes a strict pack AND the attestation workflow is NOT
     *   enabled, throws CapabilityEvolutionWithoutAttestationWorkflowError
     *   regardless of whether the hash matches.
     *
     * @throws EmptyPackBindingError if packBinding is empty.
     * @throws CapabilityEvolutionWithoutAttestationWorkflowError (line 289).
     */
    checkCurrentCapability(orgId: string, agentId: string, currentBundle: CapabilityBundleInput, packBinding: string[]): CapabilityCheckResult;
    /**
     * Runtime guard called before any tool invocation, LLM call, or retrieval.
     *
     * Throws AgentCapabilitySuspendedError if the agent is suspended.
     * All cycle gates (PR #12-#15, #18, #20, #23, #25, #27) should call this
     * and short-circuit on throw.
     *
     * @throws EmptyPackBindingError if packBinding is empty.
     * @throws AgentCapabilitySuspendedError if suspended.
     */
    guardPreCall(orgId: string, agentId: string, packBinding: string[]): void;
    /**
     * Return the full capability version history for an agent.
     *
     * The returned array is a shallow copy (immutable from caller perspective).
     * Each entry is frozen.
     *
     * Validates the hash chain before returning; if broken, emits
     * CAPABILITY_HISTORY_TAMPERED and throws CapabilityHistoryTamperedError.
     *
     * @throws EmptyPackBindingError if packBinding is empty.
     * @throws CapabilityHistoryTamperedError if chain is broken.
     */
    getVersionHistory(orgId: string, agentId: string, packBinding: string[]): ReadonlyArray<Readonly<CapabilityVersionEntry>>;
    /**
     * Enable the attestation workflow for an agent.
     *
     * When enabled: capability changes route to pending-attestation (degraded
     * Level 0) rather than immediate suspension. An operator must approve or
     * deny via respondToAttestation().
     *
     * Operator-only. Emits CAPABILITY_ATTESTATION_WORKFLOW_ENABLED at severity ERROR.
     *
     * @throws EmptyPackBindingError if packBinding is empty.
     * @throws CapabilityAttestationPermissionError if identity is not admin.
     */
    enableAttestationWorkflow(orgId: string, agentId: string, approverIdentity: string, packBinding: string[]): void;
    /**
     * Resolve a pending capability change attestation.
     *
     * approve: registers the new bundle as a new version; clears suspended/pending
     *   state; emits CAPABILITY_ATTESTATION_APPROVED at severity ERROR.
     * deny: agent stays suspended; emits CAPABILITY_ATTESTATION_DENIED at
     *   severity ERROR. Operator must later register an older or corrected bundle.
     *
     * @throws EmptyPackBindingError if packBinding is empty.
     * @throws CapabilityAttestationPermissionError if identity is not admin.
     */
    respondToAttestation(approvalId: string, approverIdentity: string, decision: 'approve' | 'deny', signedAttestation: string, packBinding: string[], 
    /**
     * When decision is 'approve', the caller must supply the new bundle
     * and the orgId/agentId so it can be registered as a new version.
     */
    approveContext?: {
        orgId: string;
        agentId: string;
        newBundle: CapabilityBundleInput;
    }): void;
    private stateKey;
    private parseStateKey;
    private getOrCreateState;
    /**
     * Compute a stable hash over a CapabilityVersionEntry for chain integrity.
     * Excludes prevEntryHash itself to avoid circularity.
     */
    private hashVersionEntry;
    /**
     * Validate the hash chain of a history array.
     * Emits CAPABILITY_HISTORY_TAMPERED and throws if the chain is broken.
     */
    private validateHistoryChain;
    /**
     * Assert pack binding is non-empty.
     */
    private assertNonEmptyPackBinding;
    /**
     * Assert that the caller is an operator (not agent runtime).
     *
     * Rejects identities with 'agent:' prefix (PT-CAPABILITY-3).
     * Verifies governance.configure permission via the injected checker if provided.
     */
    private assertOperatorIdentity;
    /**
     * Create an immutable snapshot of a bundle.
     */
    private snapshotBundle;
    /**
     * Emit an audit event with SHA-256 chaining.
     */
    private emit;
    /** Expose genesis hash for test introspection. */
    static get historyGenesisHash(): string;
}
//# sourceMappingURL=capability-change-detector.d.ts.map