design: define UUID generation and entropy contract

[vycdev2]

Summary

Define the stable UUID generation, entropy/capability, representation, and source/runtime contract for Jett before uuid.new becomes a production-facing standard-library API.

Source documentation

• docs/progress.md — Phase K, uuid
• docs/design.md — Standard Library and Rule Set 16 capability policy
• docs/architecture.md — Phase K: Full Standard Library

Current state

The checker hardcodes uuid.new() returns string with no capability argument and does not classify it as impure. The interpreter draws 16 bytes from Rust rand::thread_rng(), sets RFC 4122/UUID v4 version and variant bits, and returns a lowercase hyphenated 36-character string. There is no stdlib/uuid.jett despite the interpreter comment naming one.

The only fixture coverage calls uuid.new() from code evaluated by a verify block and checks the string length. It does not pin version/variant bits, canonical text form, uniqueness/error behavior, entropy quality, or deterministic testability. The design also names a future validate.UUID refinement, but does not define how generated and validated UUID representations relate.

This is a hidden nondeterministic effect under the current purity rule. Issue #67 owns the general random.* capability and entropy contract but explicitly excludes UUID generation, so UUID needs a coordinated, bounded decision rather than silently inheriting an accidental API.

Scope

Includes:

• choose the canonical UUID generation API, including whether uuid.new remains a v4 compatibility spelling or becomes an explicit versioned operation;
• choose how generation obtains entropy (Random, a derived generator, a dedicated system source, or another explicit boundary) while preserving the no-hidden-effects rule;
• define supported version/variant, canonical string representation, error behavior, and security/unpredictability claims;
• define purity, verify, comptime, cancellation, deterministic testing, and future native-runtime behavior;
• define interoperability with the planned validate.UUID refinement without implementing the full validation module;
• identify the permanent runtime entropy kernel, any source-defined .jett wrapper, and dependency-ordered implementation/tests.

Explicitly excludes:

• implementing a new UUID API before the contract is selected;
• redesigning the general random module owned by design: define random capability and entropy contract #67;
• adding namespace/import machinery owned by design: define module imports and trusted stdlib origins #3;
• implementing HIR, MIR, native code generation, or the full validate module.

Acceptance criteria

• A design artifact selects one canonical capability-visible UUID generation API and explains how it preserves the no-hidden-effects guarantee.
• Supported UUID versions/variants, canonical representation, validation interoperability, and security claims are explicit.
• Purity, verify, comptime, cancellation, deterministic testing, and future-backend behavior are defined.
• The permanent runtime-kernel versus source-defined stdlib boundary is recorded.
• Focused conformance tests are identified, including version/variant bits, text form, effect rejection, and deterministic testability.
• docs/design.md, docs/architecture.md, and docs/progress.md are aligned with the selected policy.
• The Phase K uuid progress entry remains in place and reflects the issue status.

Dependencies / open questions

Coordinate the entropy and seeded-testing model with #67 and compiler-shipped module origin/import spelling with #3. The interpreter-facing policy can be selected before #20 and #22 implement future HIR/MIR/native lowering.

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