/**
 * Multi-agent Claim composition — recursive-AND (∧) operator.
 *
 * Implements checkpoint 4 of sprint-576:agentic-privacy-impl (ORQ-2):
 * - `composeAgents(agents)` produces a recursive-AND ShieldedClaim over n≥2 agents.
 * - n=2: flat pairwise ∧ (no recursion needed).
 * - n≥3: left-fold recursive ∧ placeholder — future STARK aggregation via Stwo.
 *
 * Scenario: identity → credit-score → loan-approval (3 agents)
 *   1. Agent A: verifies identity (Glacis nullifier → pseudonym claim)
 *   2. Agent B: verifies credit (pseudonym + bank data → credit-score claim)
 *   3. Agent C: approves loan (credit-score claim → loan-approval claim)
 *   Composition: C_final = ((C_A ∧ C_B) ∧ C_C)
 *
 * References:
 *   - docs/research/03-agentic-privacy.md §3 (Scenario 3: Multi-Agent Composition)
 *   - docs/research/09-orq-recursive-starks.md §3 (recursive ∧ deferred to Phase 2)
 *   - vauban-privacy-protocol/sdk/typescript/src/composition.ts (compose operator pattern)
 *
 * @module privacy/composition
 */
import { type DelegationClaim } from "./delegation.js";
/**
 * A claim produced by a single agent in a multi-agent workflow.
 *
 * Each `AgentClaim` carries its agent's nullifier (the cryptographic identity
 * of the agent in the HDNT hierarchy) and a role label describing its position
 * in the workflow (e.g. "identity", "credit-score", "loan-approval").
 *
 * The `delegationChain` is optional: when present, it anchors the agent's
 * claim to a parent claim via the Claim Algebra → operator.
 */
export interface AgentClaim {
    /** Agent's nullifier (felt252 BigInt). Output of `deriveAgentNullifier`. */
    agentNullifier: bigint;
    /** Role label for this agent in the workflow. Used for domain separation. */
    role: string;
    /** Arbitrary claim payload (predicate, evidence, etc.). */
    payload: Record<string, unknown>;
    /**
     * Optional delegation chain anchoring this claim to a parent.
     * When set, the composition will verify the delegation is still valid.
     */
    delegationChain?: DelegationClaim;
}
/**
 * The composition mode used for a given invocation of `composeAgents`.
 *
 * - `"flat"`: pairwise ∧ for n=2. Proofs are independent (checkpoint 3 style).
 * - `"recursive"`: left-fold recursive ∧ for n≥3. Phase 2 will replace the
 *   placeholder with actual Stwo STARK aggregation.
 */
export type CompositionMode = "flat" | "recursive";
/**
 * A ShieldedClaim produced by `composeAgents`.
 *
 * The `composedNullifier` is the binding commitment over all participating
 * agents' nullifiers — it changes if any agent is swapped out.
 *
 * The `transcriptDigest` binds the claim to the composition's public inputs
 * (ordered agent roles + composition mode) for external proof anchoring.
 */
export interface ShieldedClaim {
    /**
     * Poseidon-derived commitment over all agent nullifiers in order.
     * Different orderings → different composedNullifier (order matters).
     */
    composedNullifier: bigint;
    /** Merged payload from all agent claims (first agent wins on key conflicts). */
    payload: Record<string, unknown>;
    /** Agent roles in composition order. */
    roles: string[];
    /** Mode used ("flat" for n=2, "recursive" for n≥3). */
    mode: CompositionMode;
    /**
     * Transcript digest: Poseidon(composedNullifier, rolesFelt, LABEL_TRANSCRIPT).
     * Binds the ShieldedClaim to its public inputs for proof anchoring (ORQ-5).
     */
    transcriptDigest: bigint;
    /**
     * Delegation witnesses for any claims that had a `delegationChain`.
     * Keyed by role label. Empty if no delegations were present.
     */
    delegationWitnesses: Map<string, DelegationClaim>;
    /** Number of agents composed. */
    n: number;
}
/**
 * Error thrown by `composeAgents` on invalid input or constraint violation.
 */
export declare class CompositionError extends Error {
    readonly kind: "EmptyComposition" | "ExpiredDelegation" | "SingleAgent";
    constructor(kind: "EmptyComposition" | "ExpiredDelegation" | "SingleAgent", message?: string);
}
/**
 * Compose n≥2 AgentClaims into a single recursive-AND ShieldedClaim.
 *
 * Algorithm:
 *   - n=2: flat pairwise ∧ (Poseidon(a, b, LABEL_AND)).
 *   - n≥3: left-fold recursive ∧ (Poseidon accumulator with LABEL_RECURSIVE).
 *
 * If any agent claim carries a `delegationChain`, its validity is checked
 * (expiry). Expired delegations cause an `ExpiredDelegation` error.
 *
 * The `transcriptDigest` binds the result to the ordered list of roles and
 * the composedNullifier for external proof anchoring.
 *
 * Example (identity → credit-score → loan-approval, n=3):
 * ```ts
 * const result = composeAgents([identityClaim, creditClaim, loanClaim]);
 * // result.mode === "recursive"
 * // result.n === 3
 * // result.roles === ["identity", "credit-score", "loan-approval"]
 * ```
 *
 * @param agents - Ordered list of AgentClaims (at least 2).
 * @returns ShieldedClaim with composedNullifier, transcriptDigest, and merged payload.
 * @throws {CompositionError} EmptyComposition if agents is empty.
 * @throws {CompositionError} SingleAgent if only 1 agent is provided.
 * @throws {CompositionError} ExpiredDelegation if any delegation chain has expired.
 */
export declare function composeAgents(agents: AgentClaim[]): ShieldedClaim;
/**
 * Build an AgentClaim with an attached DelegationClaim.
 *
 * Convenience factory that calls `buildDelegationClaim` from `delegation.ts`
 * and wires the result into an `AgentClaim.delegationChain`.
 *
 * @param agentNullifier     - Derived nullifier of this agent.
 * @param role               - Workflow role label.
 * @param payload            - Claim payload.
 * @param parentClaimDigest  - Parent claim digest bytes (from the authorizing claim).
 * @param scope              - Delegation scope (allowed actions + expiry).
 * @returns AgentClaim with populated delegationChain.
 */
export declare function buildAgentClaimWithDelegation(agentNullifier: bigint, role: string, payload: Record<string, unknown>, parentClaimDigest: number[], scope: {
    allowedActions: string[];
    expiry: number;
}): AgentClaim;
//# sourceMappingURL=composition.d.ts.map