/**
 * Contract hash primitive — SECURITY-mode 2026-04-20 Option C wiring.
 *
 * Single chokepoint for the three contract hash sites (hashGeometry,
 * computeStateDigest, hashCAELEntry). Exports:
 *   - HashMode: 'fnv1a' (default, fast, non-cryptographic) or 'sha256'
 *              (opt-in via ContractConfig.useCryptographicHash).
 *   - hashBytes(bytes, mode): byte-domain dispatcher. Used by
 *                             hashGeometry and computeStateDigest.
 *   - fnv1aStringLegacy(input): string-domain FNV-1a matching the
 *                               pre-Option-C CAEL chain format
 *                               ('cael-<8hex>'). Preserved for
 *                               back-compat — old traces verify.
 *   - hashStringForCAEL(input, mode): string-domain dispatcher used
 *                                     by hashCAELEntry. Routes to
 *                                     fnv1aStringLegacy or SHA-256.
 *   - hashShapeMatchesMode(hash, mode): format-level consistency check
 *                                       used by Replayer to catch
 *                                       mid-trace mode tampering.
 *
 * Design constraints (from SHA-256 memo §Wiring-commit prerequisites):
 *   Prereq 1 — per-recorder flag scope: no env/global defaults here.
 *   Prereq 2 — all-or-nothing consistency: every contract hash site
 *             calls through this module with the same mode for a
 *             given recorder/replayer.
 *   Prereq 3 — mode self-identification: output formats differ
 *             between modes (FNV-1a = 8 hex chars; SHA-256 = 64 hex
 *             chars), so hashShapeMatchesMode can validate trace
 *             integrity even if payload.hashMode is tampered.
 *
 * See: ai-ecosystem research/2026-04-20_sha256-feature-flag-design.md
 */
export type HashMode = 'fnv1a' | 'sha256';
/**
 * Default hash mode. Option C: FNV-1a by default for performance
 * under the non-adversarial threat model; SHA-256 is opt-in via
 * ContractConfig.useCryptographicHash = true.
 */
export declare const HASH_MODE_DEFAULT: HashMode;
/**
 * FNV-1a hash over bytes. Returns 8 hex chars. Used by hashGeometry
 * and computeStateDigest in FNV-1a mode. Fast, non-cryptographic.
 * Collision-findable under moderate adversarial effort; not safe for
 * adversarial-peer settings (use SHA-256 there).
 */
export declare function fnv1aBytes(bytes: Uint8Array): string;
/**
 * Legacy FNV-1a over a JS string via charCodeAt (UTF-16 code units).
 * Returns 'cael-<8hex>' — the pre-Option-C CAEL hash-chain format.
 * Preserved verbatim so traces recorded under FNV-1a before this
 * change still verify bit-exactly.
 *
 * **Do not use for new code**: this reads charCodeAt which gives
 * UTF-16 code units, not UTF-8 bytes. Different bytes for chars
 * > 0x7f than TextEncoder. Kept only for trace-format back-compat.
 */
export declare function fnv1aStringLegacy(input: string): string;
/**
 * Pure-JS SHA-256 over bytes. Returns 64 hex chars.
 *
 * Implementation: FIPS 180-4 §5.3.3 (initial hash values) + §6.2.2
 * (block processing). Validated against RFC 6234 §B.1-2 test vectors
 * and cross-checked against Node's native `crypto.createHash('sha256')`
 * on 9 random-input sizes (1, 63, 64, 65, 127, 128, 129, 1024, 16384
 * bytes covering single-block, block-boundary, multi-block cases).
 *
 * Synchronous and universal (works in Node ≥ 15 and all modern
 * browsers). Does not require Node's `crypto` module; no dependencies.
 *
 * Performance: ~10× slower than Node native; ~10-20× slower than
 * FNV-1a at bench sizes. Acceptable as opt-in for adversarial-peer
 * settings; not suitable as default (see Option C rationale in memo).
 */
export declare function sha256Bytes(bytes: Uint8Array): string;
/**
 * Byte-domain dispatcher. Returns:
 *   mode='fnv1a'  → 8 hex chars (FNV-1a)
 *   mode='sha256' → 64 hex chars (SHA-256)
 *
 * Used by hashGeometry and computeStateDigest. Every byte-domain
 * contract hash site routes through this — no site may call
 * fnv1aBytes or sha256Bytes directly for a flag-controlled hash.
 */
export declare function hashBytes(bytes: Uint8Array, mode: HashMode): string;
/**
 * String-domain dispatcher for CAEL trace-chain entries. Routes:
 *   mode='fnv1a'  → fnv1aStringLegacy (returns 'cael-<8hex>' —
 *                   preserves pre-Option-C trace format for
 *                   back-compat)
 *   mode='sha256' → UTF-8 encode → sha256Bytes (returns
 *                   'cael-sha-<64hex>' — distinct format makes
 *                   mode self-identifying from the hash shape alone)
 *
 * Why the format diverges between modes: the legacy FNV-1a path uses
 * charCodeAt (UTF-16 code units), which gives different bytes than
 * TextEncoder (UTF-8) for non-ASCII input. SHA-256 is new code and
 * canonicalizes to UTF-8. Mixed-input non-ASCII traces would fail
 * roundtrip if both modes used the same hash over different byte
 * encodings, so we tag them distinctly.
 */
export declare function hashStringForCAEL(input: string, mode: HashMode): string;
/**
 * Format-level consistency check. Given a hash output and a declared
 * mode, returns true iff the hash shape matches what that mode
 * produces. Used by CAELReplayer to catch mid-trace mode tampering
 * (Prereq 3 — an event's hash format must match cael.init.payload.hashMode).
 */
export declare function hashShapeMatchesMode(hash: string, mode: HashMode): boolean;
//# sourceMappingURL=sha256.d.ts.map