I-Ching Vir Casting Algorithms, CSPRNG and Yarrow Probability Model

Abstract

This paper describes coin and yarrow casting in the inspected I-Ching Vir library: fresh OS entropy for each draw, a question-derived SHA-256 personalization mask, rejection sampling and three transformations per line. Exact enumeration derives probabilities from the implemented split intervals. Meihua and manual lines are separate methods. The supplement distinguishes independent mathematical verification from native tests that could not be compiled in this run.

1 Scope and sources

The scope is cast/prng.vri, cast/entropy, cast/coins and cast/yarrow, identified by checksums dated 23 October 2026 ^[1]. QP-SYS-002 places casting within the enclosing I-Ching Engine. Casting is shared functionality, not an NLP subsystem or an exclusive Liuyao component.

These are software-model statements. Line probabilities do not demonstrate predictive validity, and hashing a question does not establish a causal relationship with the outcome. No private question history is distributed.

2 Separate question paths

2.1 Entropy personalization

For nonempty text, castQuestionMask hashes UTF-8 bytes with SHA-256, reads the first eight digest bytes as big-endian and clears the sign bit. Empty text has mask zero by convention. The inspected function does not normalize Unicode, so different byte representations may have different masks.

CastRng.state holds a 63-bit mask, not evolving PRNG state. Every castRngNext invokes the OS provider. crypto_entropy_u63_checked requests bytes(8), assembles an integer and keeps 63 nonnegative bits. Each new OS word is personalized by XOR:

$$u_i=(w_i\oplus m)\mathbin{&}(2^{63}-1). \tag{1}$$

For a fixed mask, XOR is a bijection and preserves uniformity if the OS input is uniform. The mask adds no entropy. It is not a signature, collision-resistant identifier or authentication hash. A 63-bit truncation does not retain the full collision-resistance properties of the SHA-256 digest.

2.2 Language processing

NLP independently creates QueryContext for scoring and NLG, as described in QP-SYS-001. It does not supply random coin or yarrow draws. Repeating a question does not replay a cast because new OS output is still acquired. Legacy Xorshift and DJB2 helpers remain for compatibility/testing and MUST NOT be used to characterize the current CastRng path ^[1].

3 Range sampling without modulo bias

For an inclusive integer interval [a,b], let $s=b-a+1>1$ and $U=2^{63}-1$. The code sets:

$$L=\lfloor U/s\rfloor s. \tag{2}$$

Draw a fresh u. Reject it if $u\ge L$, obtaining fresh entropy for every retry. Otherwise return $a+(u\bmod s)$. Each residue has the same number of representatives in [0,L), proving uniform range output under a uniform provider.

Using U instead of $2^{63}$ avoids an unrepresentable signed upper bound. For some spans it rejects additional values compared with the optimal cutoff; this affects efficiency, not uniformity. Span at most 1 returns a immediately. This is existing behavior, not general validation of reversed or overflowing bounds. Valid casting callers use small known ranges.

Provider failure throws error 601. The author-worktree controller maps casting exceptions to HTTP 500 before entering the result-processing/storage flow. There is no time- or question-seeded fallback. Zero is a valid random output, not failure.

4 Three coins

cast_one_coin_rng draws a uniform bit and maps it to 2 or 3. cast_coin_line_rng adds three such draws. Under independent uniform draws:

$$P(6,7,8,9)=(1,3,3,1)/8. \tag{3}$$

Six lines require 18 accepted draws; rejection may increase entropy reads. Values 6 and 9 are moving yin and yang, while 7 and 8 are static yang and yin. Lines are generated bottom to top. Animation presents an already computed cast; it does not provide extra entropy.

5 Yarrow: three transformations per line

5.1 Transition

Each line begins with 49 stalks. Choose left pile l; the initial right pile is N-l, from which one stalk is removed. The counted right pile is N-l-1. For positive x define $r(x)=1+((x-1)\bmod4)$:

$$A=1+r(l)+r(N-l-1),\qquad N'=N-A. \tag{4}$$

yarrow_one_bian_full_rng records piles, remainders, removed stalks and remaining stalks. Three successive transformations yield line value $v=N_3/4$; six lines require 18 transformations. The first removes 5 or 9, subsequent steps remove 4 or 8, and the final count is 24,28,32 or 36.

5.2 Implemented split intervals

The inspected main path does not sample every integer from 1 through N-2. It uses these inclusive intervals, each with length divisible by four:

• Step 1, N=49: 12..35, containing 24 splits.
• Step 2, N=44: 12..31; N=40: 10..29, each containing 20 splits.
• Step 3, N=40: 10..29; N=36: 10..25; N=32: 8..23.

These intervals balance residues modulo four. Step one removes 5 with probability 3/4 or 9 with probability 1/4. The next two steps remove 4 or 8 with equal probability. Therefore:

$$P(6,7,8,9)=(1,5,7,3)/16. \tag{5}$$

This is the exact probability distribution of the implemented interval model under independent uniform draws. It is not a claim about physical hand splitting. Older notes describe full-range splitting 1..N-2 and approximate probabilities 5.17%, 28.87%, 44.84%, 21.12%; that is a different model and does not describe these inspected intervals.

5.3 Comparison with coins

Yarrow assigns probability 1/16 to moving yin 6 and 3/16 to moving yang 9. Coins assign 1/8 to each. Both models have moving-line probability 1/4, but their moving types and static outcomes differ. Equal output support {6,7,8,9} does not make the methods interchangeable.

6 Meihua, manual input and transformations

Time-based Meihua obtains calendar SDK context: year branch, lunar month/day and hour branch under its calendar conventions. Remainders modulo 8 and 6 select trigrams and a moving line; zero maps to 8 or 6. The method is deterministic given its calendar inputs and is not a CSPRNG draw. Number-based Meihua helpers exist in the library; that alone does not establish HTTP exposure of every variant.

The controller requires six integer values in 6..9 for manual input. Manual values represent caller-supplied results and do not certify any external randomness. Core then constructs primary, changed and nuclear hexagrams before school, Yingqi and NLP/NLG interpretation, as detailed in QP-SYS-002.

7 Vectors and reproducibility

The supplement includes SHA-256 masks for ASCII, UTF-8 and 56/64-byte padding boundaries, range cases and yarrow examples. Its rational-arithmetic verifier enumerates the full finite split tree and confirms (1,5,7,3)/16, and all eight coin combinations confirm (1,3,3,1)/8 ^[2]. XOR permutation and rejection are also checked over a reduced 8-bit domain; sections 2–3 provide the general reasoning.

Vectors use public synthetic text only. The script never calls the production casting API, needs no private corpus and creates no user history. Mathematical checks do not directly test OS CSPRNG quality.

8 Verification limits

test_cast_csprng.vri contains counting, failure and rejection providers, but an attempted compilation with virc 2026.2.20 failed semantic analysis. Only Python verifier results and inspected source are reported as successful evidence. Author-worktree HTTP fault-injection tests were not rerun for this publication.

Source hashes do not establish a reproducible production build. Secure entropy depends on OS and runtime behavior; distribution checks do not prove cryptographic security. Line probabilities and Yingqi/scoring confidence labels are not probabilities of predictive success.

9 Conclusion

Coin and yarrow paths acquire fresh entropy per draw and use rejection sampling. The question supplies a personalization mask, not a Xorshift seed. The yarrow implementation uses three transformations with balanced split intervals and its own distribution; Meihua and manual lines are different methods. Complete documentation must publish algorithms, assumptions, vectors and the verification boundary together.

Bibliography

• ^[1] Inspected I-Ching Vir casting source manifest and checksums.
• ^[2] Synthetic vectors, rational probability verifier and verification record.