design: define crypto hashing and security contract

[vycdev2]

Summary

Define the stable Phase K hashing API, security guarantees, and source/runtime boundary before expanding or extracting Jett's Rust-backed crypto implementation.

Source documentation

• docs/progress.md — Phase K, crypto
• docs/design.md — Hashing and encoding
• docs/design.md — Standard Library / Core Modules
• docs/architecture.md — Compiler Intrinsics vs Standard Library
• docs/architecture.md — Phase K: Full Standard Library

Current state

crypto.sha256(string) and crypto.md5(string) are hardcoded checker signatures and interpreter dispatches that return lowercase hexadecimal strings. Their digest implementations live in Rust, there is no compiler-shipped stdlib/crypto.jett, and focused known-vector fixtures cover only the current string API.

The design also lists SHA-512 and HMAC, but neither has a selected signature, implementation, or test contract. The docs do not define accepted input/output representations, HMAC key handling, MD5's legacy/non-security status, password-hashing guidance, secret-taint behavior, capability/purity rules, dependency policy, or how future backends preserve the hashing boundary. The architecture currently describes crypto.sha256 as an ordinary .jett function even though the implementation is compiler-owned.

Scope

This issue includes:

• selecting the initial supported hashing/MAC surface and explicitly classifying MD5, SHA-256, SHA-512, and HMAC;
• defining input and output types, encoding/casing, determinism, errors, compatibility guarantees, and HMAC key/message ordering;
• documenting cryptographic security claims and non-claims, including safe password-hashing guidance;
• defining secret-input/taint behavior and the interaction with constant-time secret comparison without absorbing that separate boundary;
• deciding which operations remain runtime kernels and which declarations or compositional wrappers belong in compiler-shipped .jett source;
• recording the future HIR/MIR/native-backend handoff and dependency-ordered implementation/test slices.

This issue does not implement algorithms or stdlib extraction, add encryption/signatures/key generation/password KDFs, redesign randomness, or create a general cryptography framework.

Acceptance criteria

• A design artifact selects the initial crypto API and explicitly classifies MD5, SHA-256, SHA-512, and HMAC.
• Input/output types, encoding/casing, HMAC argument order, errors, determinism, and compatibility behavior are specified.
• Security claims, password-hashing non-claims, secret-taint behavior, and capability/purity rules are explicit.
• The permanent runtime-kernel versus source-defined stdlib boundary and future-backend requirements are recorded.
• Focused known-vector, type/error, secret-input, and policy-regression tests are identified for implementation slices.
• docs/design.md, docs/architecture.md, and docs/progress.md are aligned with the selected policy.

Dependencies / open questions

Coordinate compiler-shipped module origin and import spelling with #3. Coordinate secret comparison semantics with #33 and PR #66 without absorbing their constant-time comparison scope. Future HIR/MIR/native lowering should preserve the selected contract through #20 and #22, but those stages are not prerequisites for the interpreter-facing design decision. Randomness and entropy remain under #67.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.