Skip to content

docs: define random capability contract - #92

Open
vycdev2 wants to merge 1 commit into
vycdev:mainfrom
vycdev2:docs/define-random-contract
Open

docs: define random capability contract#92
vycdev2 wants to merge 1 commit into
vycdev:mainfrom
vycdev2:docs/define-random-contract

Conversation

@vycdev2

@vycdev2 vycdev2 commented Aug 9, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • select explicit view Random signatures for the five existing random operations
  • define unbiased ranges, deterministic provider injection, cancellation, ownership, and non-cryptographic security policy
  • record the source-owned public stdlib and private runtime-kernel boundary across the design, architecture, and progress docs

Verification

  • cargo fmt --check — passed
  • cargo build — passed
  • cargo test -q — passed (workspace suite, including all 432 driver fixtures)
  • git diff --check — passed
  • relative Markdown link check for the five changed files — passed (39 links checked)

Risk

  • Medium: documentation-only, but it proposes a future breaking migration from ambient random calls to explicit capability parameters and makes cancellation/provider policy concrete.

Closes #67

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

vycdev commented Aug 10, 2026

Copy link
Copy Markdown
Owner

The shuffle source/runtime split currently gives contradictory cancellation semantics. Lines 168–177 define each public random operation as one atomic capability checkpoint with no later cancellation checks, but lines 139–141 and 306–320 put Fisher–Yates in ordinary .jett source and have it call a capability-taking bounded RNG kernel once per swap. Under the stated general capability rule, each kernel call is another checkpoint, so shuffle cannot simultaneously be source-composed and one atomic capability operation.

Please choose and specify one implementable boundary: a single runtime shuffle kernel; a trusted nested no-checkpoint primitive/scope; or per-draw cancellation with explicit generator/output state semantics.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

design: define random capability and entropy contract

2 participants