Configuration reference

September 7 direction reconciliation: the product name is UOR-R4 Geometric Language Model. Read the canonical plan, current artifact/results, capability assessment and project map first. This document retains technical and dated experiment/reference material; earlier “active/next” sequences do not supersede those pointers. Native bounded inference and contextual/copy attention exist; general prose, general reasoning and frontier capability remain unqualified. Offline Rust training matmul is allowed; final serving has no matrix products or transformer backbone. No new model result was run for this documentation update.

For the current Rust model, use the CLI options and examples in the native geometric workflow. The explicit r4 geometric command family configures preparation, training, evaluation, generation and the local service; model context and operator settings travel with the artifact. The canonical plan owns architecture and budget policy, while current-state.md owns implementation status. Native options do not wait for a historical stage or later Rust port.

Retained compiler and reference configuration

The inventory below covers existing compiler/runtime and measurement lanes across earlier architectural eras. TLESS_*, R4G1_*, teacher and release variables apply to their named paths. Defaults for plain ask/chat, source tokenizers and older HTTP engines do not select the r4 geometric model. These references preserve compatibility and reproducibility; they do not reintroduce a Python model dependency or change the current project goal.

The listed environment variables give their defaults and owning modules. Where a listed CLI flag and variable both exist, the flag wins.

Legacy override contract. The capacity and sampling helpers (capacity_override_usize / capacity_override_f64) share one rule: unset is κ-neutral — behaviour is bit-identical to not setting it. Set-but-invalid, or zero, panics. A knob that silently did nothing would be indistinguishable from a knob that does not work, and both failures are invisible. Underscore separators are accepted (R4_GATE_C_SAMPLE=10_000).

Paths and inputs

Tokenizer adapter selection

Registered source tokenizers are selected by CLI/API fields, not environment variables. CLI commands that accept --source also accept the atomic pair --tokenizer-family FAMILY --tokenizer-version N. Both flags must be present or absent. When absent, discovery succeeds only when the source directory has one unambiguous supported definition; a directory containing both tokenizer.json and spiece.model requires the explicit pair. Unknown pairs and any attempt to combine a registered adapter with legacy --checkpoint input fail closed.

For raw SentencePiece sources, use family sentencepiece-unigram. Version 2 is the current, reference-correct adapter; automatic discovery of one unambiguous spiece.model selects it. Version 1 remains registered only as the immutable published behavior whose unknown id decodes to the literal model surface <unk>. N is part of the semantic identity, not a compatibility range: consumers do not substitute a newer or older version. Both versions read the pinned 32,000-piece spiece.model; neither applies the T5 Hugging Face wrapper's 100 sentinel tokens or EOS-appending post-processor.

The host adapter performs text normalization and encoding. The deployed tagged tokenizer.bin is decode-only and carries the complete adapter binding (family, version, source-model CID, and policy digest). Serving requires a matching host encoder for prompt text. Missing/mismatched identity, unavailable encode, invalid token ids, and decode failures are errors; an explicitly tagged tokenizer does not fall back to a legacy tokenizer. SentencePiece observation records have no original-source byte anchors because normalization and unknown collapse do not preserve a total input-offset map.

Determinism and teacher math

These are κ-relevant: changing them can change artifact bytes.

Thread counts

Cover induction and compiler capacity

All follow the override contract above.

Trap. R4_COVER_CAPACITY_REF_N defaults near the 500k fixture's train count, so the scaled-k0 arm passes degenerately on any ~500k corpus. Use the @ref50k arms when that matters.

Gate C scoring

Certification

Normative deployed-quality evaluation (#933)

These knobs drive the teacher-free R4G1Runtime evaluator. Worker partitions are deterministic and reductions are replayed in canonical position order, so changing the worker count changes wall time but not report bytes. Once an evaluation phase launches it writes monotonic progress plus its phase terminal; a missing control, timeout, or absent identity is UNAVAILABLE/skipped and cannot authorize production.

The historical certify-C diagnostic above and this normative command share the two budget variable names but retain distinct defaults: 600 seconds for the non-binding diagnostic, 3,600 seconds for r4 deployed-quality. Explicit CLI flags override their environment variables.

Every invocation against a valid, non-symlink bundle root first creates evidence/deployed_quality_invocation_terminal.jsonl. The create-once JSONL journal is synced after its started row and again after exactly one completed, failed, or best-effort interrupted terminal row, so argument, bundle-discovery, cross-surface, witness, sample-gate, projection, and evaluator failures are all durable. A synced started row without a terminal row means the process was externally interrupted or otherwise unresolved; signals, power loss, and SIGKILL cannot be guaranteed to run cleanup code. An absent, symlinked, or non-directory bundle cannot safely host in-bundle evidence and therefore fails before journal creation. Reusing the same staged bundle is refused rather than overwriting its first invocation.

The invocation journal is local, non-semantic evidence. It is excluded from the generation CID, production admission, and release archives, as are the resource sidecar and terminal transcript described below. Phase progress and phase terminal files under graph/ remain authoritative only after that phase actually launches.

Production admission accepts only a schema-2 release-bundle.json whose component digests and compiler/selector identities reproduce from the loaded graph, teacher artifact, corpus pair, tokenizer, tokenizer adapter, score report, cover report, and deployed-quality report. A sampled report remains research evidence even when all measured rows are favorable.

The release CLI exposes the same contract directly. --mode full cannot bypass the cheap instrument: it first runs the exact 6,000-position prefix of the canonical label-free, story-distributed order on the same bundle/evidence generation. Any structural, reachability, non-futility, planted-control, cross-surface, or witness falsifier emits STOP: and returns without starting the census. PROCEED: launches the census. A typed INCONCLUSIVE: extends the same immutable nested order to 18,000 positions; if that interval still overlaps the gate, it can launch only the census and only when the measured reachable ceiling remains sufficient. Before any census launch, the authorizing stage's measured throughput is scaled to the full population; a projection beyond the configured evaluation budget or one hour refuses launch and requires a revised run contract. No sample report can authorize production admission.

cargo run --release -- deployed-quality \
  --bundle .uor-models/compiled/<model>-staging \
  --compiler-revision <full-40-character-revision> \
  --mode sample --positions 6000 --workers 8

For a canonical run, wrap the command so host identity, effective workers, wall time, peak child RSS, free storage, bundle growth, exit status, and every graph evidence-file size are durable even when the evaluator fails. A create-once JSONL beside the summary samples the complete child process tree's CPU share, RSS, process count, host-memory headroom, and filesystem headroom every five seconds. The wrapped evaluator still streams its phase counters, throughput, and ETA. On the canonical macOS host, /usr/bin/script -e -F preserves that stream in a separate terminal transcript and propagates the child exit status; require a new transcript path before launch just as the wrapper requires a new sidecar. The resource summary, live-sample JSONL, and transcript are explicitly non-semantic and are never admission inputs. The inventory snapshot is captured when the child exits. If the live-sample JSONL is placed inside the bundle it is therefore present in that snapshot; the subsequently written resource summary and the outer transcript's final trailer are not. Both resource paths are append-only: the wrapper refuses to overwrite either one, and it verifies that its --bundle exactly matches the wrapped command's --bundle (evaluation) or --bundle-root (graph emission) before launch. It also records --workers or --jobs as the effective requested worker count. Use --samples-output to select the JSONL path; otherwise it is <output>.samples.jsonl.

test ! -e .uor-models/compiled/<model>-staging/graph/deployed_quality_full.log
/usr/bin/script -q -e -F .uor-models/compiled/<model>-staging/graph/deployed_quality_full.log \
  python3 scripts/run_deployed_quality.py \
  --bundle .uor-models/compiled/<model>-staging \
  --output .uor-models/compiled/<model>-staging/graph/deployed_quality_full_resources.json \
  -- target/release/r4 deployed-quality \
  --bundle .uor-models/compiled/<model>-staging \
  --compiler-revision <full-40-character-revision> \
  --mode full --positions 6000 --workers 8

Measurement harnesses

Teacher-parity controls govern host-side verification only and do not enter artifact identities or deployed serving. S private sequence states must share one immutable weight allocation and advance in one physical exact batch; the one W-thread pool must schedule disjoint output rows without nested oversubscription. Every output row must keep the pinned uor-matmul dot reduction intact; splitting or reassociating the reduction dimension is not permitted. Results return to canonical prompt/position order before metrics are reduced.

The 36 logical teacher-forced positions are executed once in six physical batches with registered widths 8, 8, 8, 7, 4, 1. That transcript retains each canonical lane at its distinct final teacher-forced prompt prefix (lengths 5, 6, 5, 4, 3, 4, 5, 4 for the pinned tokenizer), rather than truncating different prompts to a colliding common prefix. S4 clones the templates, appends the already-computed teacher next token to each logical seed, and times only new causal continuation steps. Exact batches carry the per-lane sequence positions explicitly, so variable histories do not serialize the cohort. There is no duplicate live-teacher prefill and no independent full-model S4 warm-up. Preparation, decode, and one-shot elapsed time remain separate evidence fields.

Before measurement, the harness reserves the bounded model-wide batch buffers, exact input/output transpose buffers, and one exact scratch slot per dedicated worker, then exercises the worker pool/backend with a tiny known product. Its elapsed time, retained capacity, capacity-growth event count, and actual added capacity bytes are recorded as excluded preparation. Measurement counters are reset without discarding those buffers. Every transcript and S4 physical forward must subsequently report zero workspace-growth events and bytes; otherwise the run fails rather than presenting allocation churn as steady-state throughput.

Conditional source, artifact, store, graph, tokenizer, or corpus evidence is reported as AVAILABLE, UNAVAILABLE, FAILED, or NOT_RUN. An absent fixture is never a parity PASS merely because the enclosing test executable returns success. The progress/event/report schema and the launch gate are specified in the #932 run record.

The durable artifact set is:

For uor-r4.exact-multicore-probe/2, probe_deadline_policy means that no new exact forward is admitted after 3,600 seconds; an already-active fixture load or exact forward may finish, then the probe records ABORTED, and elapsed time at or beyond the deadline cannot qualify. The report's required events object binds the sibling file_name, full-byte content_cid, byte_len, record_count, final_record_number, final_event, final_status, final_qualifies_full_run, and non-cyclic report_body_cid. FINAL is synchronized before the report is atomically committed, carries sequence == final_record_number == record_count, and must be the last JSONL record. Admission validates the current sidecar before teacher weights load; missing, truncated, appended, or tampered bytes refuse the run.

Schema /1 bytes describe the superseded fixed-sweep design and remain historical evidence. Schema /2 binds the adaptive candidate set, fastest-exact selection policy, and the complete registered admission shape: 36 transcript logical forwards in batch widths 8, 8, 8, 7, 4, 1; eight continuation tokens across eight lanes; 100 logical forwards in 14 physical shared-weight batches; zero-based maximum sequence position 13; and private-state capacity 14. A smaller operator cap may produce diagnostic evidence but cannot qualify the binding suite. reference_workers names the first measured exact candidate, equal_to_reference binds every candidate's raw trace to it, and the cheap worker-pool/backend prestart is recorded separately and excluded from timed forward rates. CPU and RSS fields are diagnostics: they must be structurally valid and truthful, but a platform-reported UNAVAILABLE value does not by itself refuse exact admission. A later change to field meaning, type, requiredness, units, or artifact partition requires another schema id rather than reinterpreting an existing record.

Served model identity (#655-F)

The canonical served model id on every serving surface (OpenAI /v1 routes, native /api/chat, WS, WASM) is r4. Requests may omit model, send r4, or send the deprecated pre-flip alias uor-r4 (accepted for a compatibility window); responses and /v1/models always report r4, and OpenAI wire ids are r4-prefixed (chatcmpl-r4-…, resp-r4-…, msg-r4-…, system_fingerprint: r4-{mode}). The CLI client subcommand's --model default is r4. Per-bundle logical/physical names are metadata (/uor/v1/status), not the served identity. Engine/tier names (r4g1, …) are unrelated to the model id and unchanged.

Runtime state files

Written under .uor-models/ (or UOR_MODEL_STORE):

Managed source-execution-era resolver (2026-08-15)

-attention-v2 and -attention-v2-dense-v2 are reserved physical-root suffixes; downloaded source basenames ending in either are refused before mutation. Suffix stripping uses longest match. The base and exact-suffix reload names are aliases for one logical model, attach to sources/<logical-name>/, and report the selected physical root plus optional attention/dense records. A missing source is allowed for the #718 decode-only path; a present-invalid source is terminal.

Every managed operation inspects all three roots before choosing one. A malformed/nonregular binding, an unbound populated suffix, a future version, an impossible attention+dense pair, duplicate semantic identities, or an unfinished lower-precedence identity is terminal and byte-preserving. Current startup/reload also requires the canonical corpus pair and graph-cover/cover_report.json to carry the same registry-exact execution pair as the root sidecars. Historical v1 and dense absence remain readable where documented. These checks reconcile metadata. The cover-graph PROV/1 byte section itself landed with #637 phase 3 (PR #738): cover now emits a PROV/1 section unconditionally (a deliberately-empty record when no identity flags are supplied).