/**
 * ToolContract — Behavioral Contract Materialization
 *
 * Unifies the declarative surface (tool names, schemas, tags) with
 * the behavioral contract (Presenter egress schema, system rules,
 * cognitive guardrails, middleware chain, state-sync policies) into
 * a single, serializable, diffable, hashable artifact.
 *
 * **Key insight**: MCP Fusion's Presenter is not just a response
 * formatter — it's a declarative behavioral specification. The Zod
 * schema, system rules, agent limits, and affordances are all
 * explicit, serializable contracts. By materializing them into a
 * `ToolContract`, we create a fingerprint that changes when behavior
 * changes — even if the MCP tool declaration stays identical.
 *
 * **Zero developer effort**: The contract materializes from what the
 * developer has already declared. No annotations, no config, no
 * ceremony — just `materializeContract(builder)`.
 *
 * Pure-function module: no state, no side effects.
 *
 * @module
 */
import { type ToolBuilder } from '../core/types.js';
/**
 * Complete behavioral contract for a single tool.
 *
 * Captures both the MCP-visible surface (schema, description) and
 * the behavioral internals (Presenter egress, rules, guardrails,
 * middleware, state-sync, concurrency).
 */
export interface ToolContract {
    /** Declarative surface visible via MCP `tools/list` */
    readonly surface: ToolSurface;
    /** Behavioral contract extracted from runtime primitives */
    readonly behavior: ToolBehavior;
    /** Token economics profile for cognitive overload detection */
    readonly tokenEconomics: TokenEconomicsProfile;
    /** Handler entitlements from static analysis */
    readonly entitlements: HandlerEntitlements;
}
/** Declarative surface — what `tools/list` exposes */
export interface ToolSurface {
    /** Tool name */
    readonly name: string;
    /** Tool description */
    readonly description: string | undefined;
    /** Tags for selective exposure */
    readonly tags: readonly string[];
    /** Per-action contracts */
    readonly actions: Record<string, ActionContract>;
    /** SHA-256 of canonical JSON Schema */
    readonly inputSchemaDigest: string;
}
/** Per-action behavioral contract */
export interface ActionContract {
    /** Human-readable description */
    readonly description: string | undefined;
    /** Whether this action is destructive */
    readonly destructive: boolean;
    /** Whether this action is idempotent */
    readonly idempotent: boolean;
    /** Whether this action is read-only */
    readonly readOnly: boolean;
    /** Required field names */
    readonly requiredFields: readonly string[];
    /** Presenter name (if MVA pattern is used) */
    readonly presenterName: string | undefined;
    /** SHA-256 of action-level input schema */
    readonly inputSchemaDigest: string;
    /** Whether the action has per-action middleware */
    readonly hasMiddleware: boolean;
}
/** Behavioral contract — internal runtime guarantees */
export interface ToolBehavior {
    /** SHA-256 of Presenter's Zod schema shape (field names + types) */
    readonly egressSchemaDigest: string | null;
    /**
     * Fingerprint of system rules configuration.
     * Static rules: SHA-256 of sorted rule strings.
     * Dynamic rules: `"dynamic:<function-hash>"`.
     */
    readonly systemRulesFingerprint: string;
    /** Cognitive guardrail configuration */
    readonly cognitiveGuardrails: CognitiveGuardrailsContract;
    /** Middleware chain identity */
    readonly middlewareChain: readonly string[];
    /** State sync policy fingerprint */
    readonly stateSyncFingerprint: string | null;
    /** Concurrency configuration fingerprint */
    readonly concurrencyFingerprint: string | null;
    /** Affordance topology — tool names from suggestActions */
    readonly affordanceTopology: readonly string[];
    /** Embedded child Presenter names */
    readonly embeddedPresenters: readonly string[];
}
/** Cognitive guardrails configuration snapshot */
export interface CognitiveGuardrailsContract {
    /** Maximum items before truncation (from Presenter) */
    readonly agentLimitMax: number | null;
    /** Maximum egress payload bytes (from builder) */
    readonly egressMaxBytes: number | null;
}
/**
 * Token economics profile for cognitive overload detection.
 *
 * Captures the expected token density of a tool's responses
 * to detect context inflation that would evict system rules
 * from the LLM's working memory.
 */
export interface TokenEconomicsProfile {
    /** Estimated tokens per field in the egress schema */
    readonly schemaFieldCount: number;
    /** Whether collections may be unbounded (no agentLimit) */
    readonly unboundedCollection: boolean;
    /** Estimated base token overhead (rules + UI + affordances) */
    readonly baseOverheadTokens: number;
    /** Risk level based on configuration */
    readonly inflationRisk: 'low' | 'medium' | 'high' | 'critical';
}
/**
 * Handler entitlements derived from static analysis.
 *
 * Tracks I/O capabilities that the handler accesses, forming
 * a security contract. If a read-only tool suddenly imports
 * `fs.writeFileSync`, the entitlement contract breaks.
 */
export interface HandlerEntitlements {
    /** Whether any handler references filesystem APIs */
    readonly filesystem: boolean;
    /** Whether any handler references network/fetch APIs */
    readonly network: boolean;
    /** Whether any handler references child_process/exec APIs */
    readonly subprocess: boolean;
    /** Whether any handler references crypto/signing APIs */
    readonly crypto: boolean;
    /** Whether any handler uses dynamic code evaluation (eval, Function, vm) */
    readonly codeEvaluation: boolean;
    /** Raw entitlement identifiers for granular diff */
    readonly raw: readonly string[];
}
/**
 * Materialize a `ToolContract` from a builder's public API.
 *
 * Extracts all behavioral metadata from the builder's introspection
 * methods without accessing any private internals. This guarantees
 * compatibility with any `ToolBuilder` implementation.
 *
 * @param builder - A registered tool builder
 * @returns A fully materialized `ToolContract`
 */
export declare function materializeContract<TContext>(builder: ToolBuilder<TContext>): Promise<ToolContract>;
/**
 * Compile contracts for all tools in a registry.
 *
 * @param builders - Iterable of all registered tool builders
 * @returns Record mapping tool names to their materialized contracts
 */
export declare function compileContracts<TContext>(builders: Iterable<ToolBuilder<TContext>>): Promise<Record<string, ToolContract>>;
export { sha256, canonicalize } from './canonicalize.js';
//# sourceMappingURL=ToolContract.d.ts.map