I-Ching Vir Architecture, Hexagram Model and Component Engine Boundaries

Abstract

This paper describes I-Ching Vir from raw lines to structured results: core domain, casting, transformations, schools, Liuyao, Yingqi, scoring, NLP/NLG and history storage. A source manifest dated 23 October 2026 separates inspected implementation statements from conventions and computed checks. The document surveys an implementation; it does not establish predictive validity.

1 Scope

I-Ching is the enclosing engine. Liuyao and Yingqi are component engines; shared NLP/NLG represents one branch of the system. This architecture complements QP-SYS-001 and the casting paper QP-SYS-003. Inspected source is the primary evidence ^[1]. File structure and calls are source statements; bit formulas are conventions and derivations; test outputs are computed results. Traditional meanings are interpretations. Software consistency does not demonstrate successful event prediction.

2 Architecture and data flow

2.1 Responsibilities

Core defines lines, trigrams, hexagrams and moving lines. Data supplies trigram, King Wen, stem-branch, Najia and textual lookup material. Casting produces six raw line values. Transformations derive changed, nuclear, opposite and reversed hexagrams. School modules read core state to assemble school-specific facts. Presentation collects these into responses, animations and result documents.

NLP creates a QueryContext; scoring consumes it with a DivinationContext; NLG chooses a response using evidence and answer eligibility. Yingqi consumes hexagram and calendar context to generate and rank timing candidates. Neither language processing nor timing generation replaces the six-line casting operation.

Request → input validation → casting method / manual lines
        → six lines → primary, changed, nuclear + school facts
        → QueryContext + scoring + Yingqi + NLG
        → response / result_document → snapshot / history

This is a responsibility diagram. Actual side-effect order is documented in section 6 and must not be inferred from its arrows.

2.2 Deployment boundaries

The author-worktree entrypoint server.vri uses InterVir routes and middleware. Process inspection identifies a native I-Ching binary, a separate Node gateway and a separate Python engine. “Implemented in Vir” therefore does not describe every service, tool or historical dataset.

The manifest distinguishes the deployed library tree from the author worktree. The deployed libraries have source checksums, whereas the entrypoint was available only in the author worktree during this inspection. An independent rebuild linking the complete source set to the running binary was not performed. A binary checksum identifies an artifact; it does not establish build provenance ^[1].

3 Line and hexagram model

3.1 Values and orientation

Lines run bottom to top: position 1 is the bottom line and position 6 the top. For raw values {6,7,8,9}, the yang bit is the remainder modulo 2. Values 6 and 9 move; 7 and 8 remain static. The encoding convention is:

$$B=\sum_{i=1}^{6}b_i2^{i-1}. \tag{1}$$

The lower three bits form the lower trigram, the upper three the upper trigram. Bit code B ranges from 0 to 63, while the King Wen number ranges from 1 to 64 and requires a lookup. B+1 MUST NOT be substituted for that lookup.

3.2 Transformations

With moving-line mask M, changed state is equivalently $B'=B\oplus M$. Opposite state is $B_{opp}=B\oplus63$. Reversal reverses the six line positions. Nuclear state takes lines 2,3,4 for its lower trigram and 3,4,5 for its upper trigram. These operations are implemented by changed, opposite, inverse and nuclear ^[1].

Synthetic lines [6,7,8,9,6,9] yield B=42, M=57, changed bit code 19 and nuclear bit code 21. These are bit codes, not King Wen numbers or private readings.

4 Liuyao and Yingqi components

4.1 Liuyao school facts

schools/liuyao/resolver.vri assembles Najia, palace and subject/object positions from hexagram state. Six-relative, calendar and moving-line information feeds later interpretation and scoring. School-specific derivation reads the cast; it does not choose a new cast.

4.2 Yingqi timing

The inspected Yingqi code implements Liuyao timing with ruleset zengshan_core_v1; it is not a Nine Palace Flying Stars component. The pipeline collects triggers using lines, use-god and calendar conditions, then constructs branch candidates, a time horizon and top-k output ^[1].

For n>0 triggers on one branch, yingqi_branch_effective_score selects the largest trigger score and adds 3 for each additional trigger:

$$s_{branch}=\max_j(s_j)+3(n-1). \tag{2}$$

Nonpositive top-k falls back to 3. yingqi_confidence_from_score labels scores at least 54 high and scores at least 48 medium. These labels express implementation thresholds, not event probabilities. Calendar conversion also depends on horizon and base-branch conventions.

5 Scoring and NLP/NLG

Scoring combines hexagram, domain, moving lines, subject/object, Liuyao, Meihua, timing, relations and void-state factors. Weights are implementation policy; this paper provides no empirical calibration turning scores into probabilities.

The response path in cr_build_cast_response_json_with_qc evaluates scores, constructs Yingqi timing and invokes the NLG matrix. Eligibility selects direct or insufficient-context response branches. QP-SYS-001 documents the 64-dimensional vectors, prototypes and language evaluation ^[2]. NLP vectors are not casting entropy; QP-SYS-003 describes that boundary.

6 Controller, storage and failures

castHandler distinguishes coins, yarrow, meihua and manual input. handleDivinationFlow builds hexagrams, attempts a database write if its store is ready, appends a history index, resolves QueryContext, builds the response, calls snapshot storage and responds with HTTP 200.

This does not establish an atomic transaction across the database, index and snapshot. dbSaved concerns the database path and does not certify every side effect. A reading identifier alone does not establish history authorization; access-control assurance requires a separate review.

Coin and yarrow branches generate all six lines before entering the processing/storage flow. Entropy exceptions are caught and mapped to HTTP 500. This is a source-boundary observation, not a new production fault-injection result ^[1].

7 Verification and limitations

The supplement contains three synthetic vectors and a verifier enumerating 4096 (B,M) pairs for the changed-state involution. It also checks opposite and reversal involutions over all 64 bit states. These are independent algebraic checks, not executions of the production binary ^[3].

A native CSPRNG test compilation attempted with workspace virc 2026.2.20 failed semantic analysis; it is not reported as a passing native test. Algebraic checks do not cover HTTP transport, authorization, astronomical calendars or traditional efficacy. Older architecture notes describe Xorshift and runtime details that cannot stand in for the inspected casting path.

8 Conclusion

I-Ching Vir contains core, casting, transformations, schools, Liuyao, Yingqi, scoring, NLP/NLG, responses and persistence. An architecture account must preserve these boundaries, expose side-effect order and distinguish inspected sources from executed binaries. QP-SYS-002 and QP-SYS-003 provide the system and casting coverage missing from the language-focused QP-SYS-001.

Bibliography

• ^[1] Inspected source manifest and checksums, 23 October 2026.
• ^[3] Synthetic vectors, verifier and verification record distributed with this paper.
• ^[2] QP-SYS-001, NLP/NLG in I-Ching Vir.