design: define random capability and entropy contract

[vycdev2]

Summary

Define the stable capability, entropy, determinism, and source/runtime boundary for Jett's random standard-library module before expanding or self-hosting it.

The language design says random-number generation is an explicit side effect granted through the built-in Random capability, but the current five random.* builtins have capability-free signatures and are treated as pure by the checker. A design decision is needed before changing those signatures or choosing which operations remain runtime kernels.

Source documentation

• docs/progress.md — Phase K, random
• docs/design.md — Rule Set 16: Capability-Based I/O
• docs/architecture.md — Phase 6: Type Checking

Current state

The checker hardcodes these signatures without a Random argument:

• random.int64(int64, int64) returns int64
• random.float64() returns float64
• random.bool() returns bool
• random.choice[T](list[T]) returns optional[T]
• random.shuffle[T](list[T]) returns list[T]

They are absent from the checker’s impure-builtin set. The interpreter dispatches every call through Rust rand::thread_rng(); there is no caller-visible entropy source, seed/state model, deterministic test path, or documented cryptographic guarantee. choice returns none for an empty list, int64 uses a half-open range and rejects lo >= hi, and shuffle clones before shuffling. No focused random fixtures currently pin these contracts.

This conflicts with Rule Set 16, which names Random as the capability for random-number generation and states that a function without a capability parameter cannot use randomness.

Scope

Includes:

• choose the canonical way random operations receive or borrow Random, including how main obtains it;
• decide whether deterministic/seeded generators are values derived from the capability, a separate API, or intentionally unsupported;
• define whether any API is cryptographically secure and prevent accidental security claims for non-cryptographic generation;
• define purity, verify, comptime, cancellation, and future native-runtime behavior;
• pin range, empty-input, ownership, generic, and ordering guarantees for the five existing operations;
• identify the minimal permanent runtime entropy/generator kernels and any compositional helpers that can later move to compiler-shipped .jett source;
• produce dependency-ordered implementation and regression-test slices.

Explicitly excludes:

• implementing a new RNG before the contract is selected;
• adding probability distributions, weighted choice, UUID generation, crypto key generation, or a general simulation library;
• changing unrelated capability APIs;
• HIR, MIR, native code generation, or platform entropy implementations beyond documenting their required handoff.

Acceptance criteria

• A design artifact selects one canonical capability-visible random API and explains how it preserves Rule Set 16’s no-hidden-side-effects guarantee.
• Seeded/deterministic behavior and cryptographic-security claims are explicitly included or excluded.
• The five current operations have documented range, empty-input, ownership, generic, and error contracts.
• verify, comptime, cancellation, and future backend behavior are defined well enough to test without relying on chance.
• The permanent runtime-kernel versus source-defined stdlib boundary is recorded.
• Focused implementation slices and regression tests are identified, including pure-context/capability rejection and deterministic testability.
• 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. Future HIR/MIR/native lowering should preserve the selected effect boundary, but the interpreter-facing API decision should not require #20 or #22 to land first.

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