/**
 * Output schema fingerprint utility.
 *
 * Provides stable SHA-256 fingerprints derived from the sorted key set of a
 * tool result object. The same output mode / input class always produces the
 * same fingerprint because the hash is computed from the sorted key names, not
 * from the values, making it a schema-level identity rather than a content hash.
 *
 * Integration pattern:
 *   1. After a mode-specific result is produced, call `appendSchemaFingerprint`.
 *   2. The `_meta.outputSchemaFingerprint` field is appended to the result object.
 *   3. When the fingerprint gate is off (tools.outputSchemaFingerprints) the result object is returned unchanged.
 */
import type { FeatureFlagManager } from '../../runtime/feature-flags/index.js';
export interface SchemaFingerprintOptions {
    readonly featureFlags?: Pick<FeatureFlagManager, 'isEnabled'> | null | undefined;
}
/**
 * Checks the runtime capability gates explicitly supplied by the composition root.
 */
export declare function isSchemaFingerprintEnabled(options?: SchemaFingerprintOptions): boolean;
/**
 * Canonical schema shape IDs per tool and output mode.
 *
 * The shape ID is the stable, human-readable identifier for what the schema
 * looks like before the hash is computed. It encodes the tool name and mode
 * so that diagnostics can group / filter by shape without needing to know the
 * full fingerprint.
 */
export declare const SCHEMA_SHAPE_IDS: Record<string, string>;
/**
 * Returns the canonical shape ID for a given tool and mode combination.
 * Falls back to `<tool>.<mode>.v1` for unknown combinations.
 */
export declare function getSchemaShapeId(tool: string, mode: string): string;
/**
 * Compute a stable SHA-256 fingerprint from the sorted top-level key names of
 * a result object.
 *
 * The hash input is the JSON-serialised sorted key array, e.g.:
 *   `["count","files"]` → sha256 → hex string
 *
 * Because the hash is over keys only (not values), the same schema shape
 * always produces the same fingerprint regardless of runtime content.
 *
 * Uses the Web Crypto API (available in Bun via globalThis.crypto).
 */
export declare function computeSchemaFingerprint(result: Record<string, unknown>): Promise<string>;
/**
 * Synchronous variant using the synchronous `crypto.subtle.digestSync` API
 * available in Bun. Falls back to a deterministic key-sort string when the
 * sync API is not available (e.g. in Node.js test environments without
 * polyfilling).
 *
 * This is the preferred variant for tool `execute()` paths where async is
 * already available, but a sync escape hatch is provided for contexts where
 * adding `await` is impractical.
 */
export declare function computeSchemaFingerprintSync(result: Record<string, unknown>): string;
/**
 * Schema fingerprint metadata appended to tool results.
 */
export interface SchemaFingerprintMeta {
    /** Canonical shape ID (human-readable, e.g. `find.files.v1`). */
    schemaShapeId: string;
    /** SHA-256 hex (64 chars) in Bun; FNV-1a hex (8 chars) in non-Bun environments. */
    outputSchemaFingerprint: string;
}
/**
 * Append `_meta.outputSchemaFingerprint` to a result object when the feature
 * flag is enabled. Returns the original object unchanged when the flag is
 * disabled.
 *
 * @param result   The mode result object (plain, not yet JSON-stringified).
 * @param tool     Tool name: `'find'`, `'analyze'`, or `'inspect'`.
 * @param mode     The active output mode string (e.g. `'files'`, `'impact'`).
 * @returns        The augmented (or original) result object.
 */
export declare function appendSchemaFingerprint(result: Record<string, unknown>, tool: string, mode: string, options?: SchemaFingerprintOptions): Record<string, unknown>;
//# sourceMappingURL=schema-fingerprint.d.ts.map