# Renigma: Operational Semantics Local, editable request plans, traceable named-value memory, and reproducible research on representations that preserve the effects of operations. Explore the [public Renigma research exhibit](https://renigma-operational-semantics.zuluyokahama.chatgpt.site) for an interactive context experiment, generative artwork and recorded findings. Website source and publication records are in [website/](website/README.md). The **Scenarios** workspace connects reviewed memory statements with conditional predictions and reported observations. A baseline and one alternative replay independently; a disagreement remains visible across corrections. The contract is in [SCN-001](docs/SCENARIO_SPEC.md), with full intent coverage in the [delivery ledger](docs/INTENT_LEDGER.md) and future [research gates](docs/RESEARCH_GATES.md). The public exhibit uses synthetic examples; it cannot access private local records. Original project code is available under the [PolyForm Noncommercial 1.0.0 license](LICENSE) for personal and other permitted noncommercial uses. Commercial use requires a separate license from the copyright holder. See [NOTICE](NOTICE) for attribution and [the GitHub handoff](docs/GITHUB_HANDOFF.md) for the scope of this public snapshot. The first interpreter uses explicit English grammar. The separate research probe learns four routing settings. The memory study learns a key-to-slot memory map and compares GPU execution, sparse selectors, topology observations and graph diffusion. These are bounded mechanisms, not general language models. External actions described in requests are never executed. ## Start the workbench From this directory in PowerShell: ```powershell .\scripts\bootstrap.ps1 -Training .\scripts\start-workbench.ps1 ``` Setup requires internet access once to install the locked open dependencies. Afterwards, the workbench, mathematical checks, exact routing, and installed CPU trainer operate locally without accounts or remote models. Open `http://127.0.0.1:8765` while the server is running. Ctrl+C in the server terminal stops it. No service or scheduled task is installed. The scripts default to `G:\RenigmaLLM_Artifacts` for the environment and cache, preserving the existing HDD contents. `-ArtifactRoot` selects another available directory. No large files are silently placed on C: if G: disappears. Omit `-Training` for a smaller workbench-only environment; the research trainer then needs a later setup with `-Training`. Example request: > After I approve "draft", Maya summarize "draft". Maya must not email "draft". Inspect each condition and prohibition. Select **Source** to highlight its evidence, then **Edit** to correct a field. Original parser uncertainties remain visible as a record of the input. **Save JSON** preserves source, interpretation, and corrections; **Export text** produces a readable plan. **Show JSON** and **Paste JSON** also work in embedded browsers whose download or file-picker support is limited. Nothing is saved in the background. See [supported grammar](docs/grammar.md), [requirements](docs/SPEC.md), [dimensioned architecture](docs/ARCHITECTURE.md), [memory-stage findings](docs/MEMORY_FINDINGS.md), [continuation findings](docs/CONTINUATION_FINDINGS.md), and [historical first-release findings](docs/FINDINGS.md). This is bounded English: unsupported phrases and ambiguous pronouns require human interpretation. Quoted document names are labels; the app does not read, summarize, email, or delete the referenced files. ## Compare a memory scenario Select **Scenarios**, then **Load color example**. Review the baseline that overwrites green with blue and the alternative that omits the overwrite. Select **Review scenario**, inspect both traces and any excluded wording, then **Adopt reviewed scenario**. Each branch starts from empty memory. Under **What was observed?**, select the baseline's recall prediction and enter green as an illustrative report. **Add to draft for review**, review again and adopt. The comparison records a mismatch without changing the original blue prediction. A later correction keeps the earlier source, prediction and report in revision history. No report, an explicitly absent binding and an observed value remain different states. **Show JSON** and **Save JSON** export only the accepted record. Import validation checks canonical replay and the configured engine; it does not prove a report occurred. A legacy memory import first creates a wrapper for explicit review, retaining its original grammar version. Descriptive assumptions do not execute operations. Capacity errors reject the request; export and start a separate scenario when its bounded history is full. ## Run and reproduce the research ```powershell $renigmaPython = 'G:\RenigmaLLM_Artifacts\environment\Scripts\python.exe' & $renigmaPython -m renigma doctor & $renigmaPython -m pytest -q & $renigmaPython -m renigma math-check & $renigmaPython -m renigma experiment & $renigmaPython -m renigma verify 'G:\RenigmaLLM_Artifacts\runs\' ``` `experiment` runs seeds 0–4 and returns the receipt path. Each seed learns four scalars from generated A/B sequences, exports actual learned gates, then runs a separate integer interpreter. The first milestone is faithful gate recovery; its tiny scale supports no general language or speed-superiority claim. Finite exhaustive verification overlaps the training domain; fixed longer sequences are length holdouts. Original routing-study defaults: CPU, 1,000 updates/seed, 30 minutes/run, two hours/batch, 12 GiB aggregate host RAM, 10 GiB batch files and a 5 GiB free-disk reserve. GPU inventory is reported without claiming execution by that CPU study. The separate GPU study below has its own execution receipts. The CLI permits lowering limits, not raising these ceilings. Resume an incomplete batch with the same configuration: ```powershell & $renigmaPython -m renigma experiment --resume 'G:\RenigmaLLM_Artifacts\runs\' ``` Completed seeds are reused after hash checks. Incomplete seeds restart from their seed; optimizer-state continuation is not implemented. Every attempt remains recorded. Source, configuration or environment changes require a new batch. Interrupted runs never pass. If a power loss leaves `.running.lock`, verify the recorded process is no longer running before removing that one lock file. Do not remove a live batch's lock. Standalone interpretation: ```powershell & $renigmaPython -m renigma interpret --text 'Maya review "notes".' --format text & $renigmaPython -m renigma interpret --file '.\request.txt' --output '.\plan.json' ``` CLI exit status is 0 for success, 1 for handled input/setup errors, and 2 for failed/incomplete research verification or malformed command-line usage. Inspect the receipt status to distinguish failed from incomplete research. ## Evidence and release [Research protocol and theory registry](docs/RESEARCH.md) separate established algebra, testable hypotheses, and historical reports. [Agent task packets](docs/AGENT_TASKS.md) can be used in Codex or Claude Code. The current implementation and review were performed with Codex subagents; Claude Code replication has not been performed. After verification, create an original routing-study ZIP in a new destination: ```powershell & $renigmaPython scripts\package_release.py --run 'G:\RenigmaLLM_Artifacts\runs\' --destination 'G:\RenigmaLLM_Artifacts\release\' ``` The release script requires passing artifacts for the current source, preserves synthetic experiment evidence, and writes SHA-256 checksums. It does not publish anything. Dependency versions are locked in `uv.lock`; [license metadata](docs/DEPENDENCIES.md) and `NOTICE` record provenance. Old HDD research, model weights, and archives were not copied. This original packager uses a fixed ZIP filename inside its destination and can overwrite it; choose a previously unused destination to preserve prior releases. Use the separate memory packager below for the memory study. Original code uses PolyForm Noncommercial 1.0.0. This does not constitute universal IP clearance or a claim of novelty. See `LICENSE` and `NOTICE`. ## Memory and binding: the next leg One supported workflow is: > Remember that "cabinet code" is cedar. Change "cabinet code" to amber. What is "cabinet code"? The Memory panel shows the current binding, actual read answer, overwritten statement, and source of the current value. It handles supported statements using explicit grammar. Unsupported wording remains unresolved. Source edits require a new interpretation review; export/import preserves the source, revision history and replayable trace. Reset clears live bindings. Session vocabulary capacity remains finite and is shown in the interface. The current language extension also accepts `Set "cabinet code" to cedar`, `Update "cabinet code" to amber`, and `Recall "cabinet code"`. Select **Review interpretation**, inspect its canonical operations and actual-engine answers, then **Use reviewed result**. Exports contain the accepted record; canceling a preview leaves that record intact. Old version-1 imports keep the original grammar until explicitly reviewed and adopted as version 2. See the [language contract](docs/MEMORY_LANGUAGE.md) for all ten forms and the exact limits of interpretation. Without a configured artifact the panel explicitly uses a **dictionary reference**. To use an independently verified learned map, supply its local JSON at startup: ```powershell .\scripts\start-workbench.ps1 -MemoryArtifact 'G:\RenigmaLLM_Artifacts\memory-runs\\\memory-artifact.json' ``` The configured artifact's checksum is exposed in the interface. A reference answer is never reported as a successful training result. No model download or GPU is required to replay a learned integer map in the workbench. Install the separate CUDA environment and optional topology dependencies once: ```powershell .\scripts\bootstrap-gpu.ps1 -Topology $renigmaGpuPython = 'G:\RenigmaLLM_Artifacts\environment-gpu\Scripts\python.exe' & $renigmaGpuPython -m renigma gpu-check & $renigmaGpuPython -m renigma memory-experiment --scale calibration --seeds 0 & $renigmaGpuPython -m renigma memory-experiment --scale main & $renigmaGpuPython -m renigma memory-verify 'G:\RenigmaLLM_Artifacts\memory-runs\' & $renigmaGpuPython -m renigma memory-benchmark 'G:\RenigmaLLM_Artifacts\memory-runs\\\memory-checkpoint.json' & $renigmaGpuPython -m renigma memory-diagnostics 'G:\RenigmaLLM_Artifacts\memory-runs\\\memory-checkpoint.json' ``` For both follow-up studies, select the first scientifically accepted main trial in the fixed order softmax, sparsemax, 1.5-entmax, then seed 0 through 4 within each selector. Use that same trial's `memory-checkpoint.json` for diagnostics and benchmarking, and its sibling `memory-artifact.json` for the workbench. The memory packager verifies this selection rule; an arbitrary passing checkpoint does not satisfy the registered follow-up contract. The GPU protocol explicitly selects the RTX 5070. CUDA unavailability is a visible failure. Dense tensor training compares softmax, sparsemax and fixed 1.5-entmax at the same sizes and budget. The main memory is batch x 32 slots x 65 value channels, with 1,024 learned routing logits. A key-to-slot table shared by reads and writes learns fixed-vocabulary allocation; it does not learn names or general language. Use `--resume ` with the original arguments to continue an incomplete batch. Each command invocation is capped at two hours; each worker at 30 minutes. A run stopped by a ceiling remains incomplete. Completed/failed attempts and their actual learned parameters are retained. Review the receipt's scientific status separately from whether its subprocess completed. A different source or protocol starts a new batch. Never tune against the frozen holdout and present it as fresh validation. An 8 GiB monitored GPU allocation target and 1 GiB device reserve supplement the host/disk limits. WDDM GPU accounting and the PyTorch allocator do not provide total process isolation. Tensorization and zero selector probabilities do not themselves prove acceleration: the benchmark measures actual dense/indexed execution. Read [the memory protocol](docs/MEMORY_PROTOCOL.md), [language contract](docs/MEMORY_LANGUAGE.md), and [diagnostic protocol](docs/MEMORY_DIAGNOSTICS.md). The separate [GPU/topology dependency inventory](docs/MEMORY_DEPENDENCIES.md) records installed versions and declared terms, including the optional topology chain's GPLv3-declared component. The original release evidence is historical and remains preserved; subsequent findings have their own receipts. After the full memory matrix, diagnostics, and benchmark finish, create a separate local memory research snapshot with the GPU environment: ```powershell & $renigmaGpuPython scripts/package_memory_release.py --main 'G:\RenigmaLLM_Artifacts\memory-runs\' --calibration 'G:\RenigmaLLM_Artifacts\memory-runs\' --diagnostics 'G:\RenigmaLLM_Artifacts\runs\' --performance 'G:\RenigmaLLM_Artifacts\memory-performance\' ``` This historical study packager requires the source associated with those runs. For the sealed MEM-001/EXEC-001 study, use its archived source snapshot; the new LANG-002/EXEC-002 runtime has a different fingerprint. Do not rewrite old receipts to associate them with later code. This script requires terminal scientific results for all 15 main trials and retains negative findings and earlier incomplete attempts. It checks source, environment, evidence hashes, and the selected checkpoint across follow-up studies; packages explicit source/evidence allowlists; and refuses to overwrite an existing archive. The archive's member manifest and detached SHA-256 identify the snapshot. It contains source and synthetic evidence, without dependency binaries, and does not publish remotely. Use the original `package_release.py` only for a verified routing-study snapshot. ## Reviewed language and parallel scan Read the [LANG-002 protocol](docs/LANGUAGE_REVIEW_PROTOCOL.md), [EXEC-002 protocol](docs/MEMORY_SCAN_PROTOCOL.md), and [continuation findings](docs/CONTINUATION_FINDINGS.md). Recheck authored grammar coverage and historical version-1 compatibility locally: ```powershell & $renigmaGpuPython scripts/evaluate_memory_language.py & $renigmaGpuPython scripts/check_memory_compatibility.py --output 'G:\RenigmaLLM_Artifacts\lang002-compatibility-new.json' ``` The compatibility command requires the verified sealed memory-stage ZIP. The scan command below reuses the exact registered EXEC-001 input/checkpoint bytes and creates a new unique attempt folder. It performs no optimizer updates. Use `--previous PATH` only to locate an unchanged copy of that original folder. ```powershell & $renigmaGpuPython scripts/run_memory_scan.py & $renigmaGpuPython scripts/run_memory_scan.py --verify 'G:\RenigmaLLM_Artifacts\memory-scan\' ``` The scan worker has a 300-second ceiling and the invocation a 600-second ceiling, with the existing 8 GiB GPU / 12 GiB host memory limits. Correctness precedes timing. Read-only verification checks the retained bytes, provenance, dictionary answers and recorded measurements; it does not rerun GPU timing. To seal this continuation's reviewed source and retained evidence in a new local ZIP (refuses an existing target): ```powershell & $renigmaGpuPython scripts/package_continuation.py 'G:\RenigmaLLM_Artifacts\memory-scan\' ``` The continuation packager requires its passing recorded tests, language checks, review ledger, original sealed memory-stage ZIP and browser test harness. It checks the byte links, includes the older ZIP unchanged, and creates a payload manifest and detached checksum. It does not execute research or publish remotely. ## Operational representation experiment The [REP-001 protocol](docs/REPRESENTATION_PROTOCOL.md) tests the proposed commuting-diagram criterion in a known 98-state world. Exact context-loss controls accompany three learned objectives, widths 2/5/10, and five seeds. Primary outcomes are decoded states under unseen operation compositions; latent errors and quantization costs are measured separately. ```powershell & $renigmaGpuPython scripts/run_representation.py --probe & $renigmaGpuPython scripts/run_representation.py & $renigmaGpuPython scripts/run_representation.py --verify 'G:\RenigmaLLM_Artifacts\representation-runs\' ``` The probe is a separate 100-update development run. The official command creates a unique source/design/protocol snapshot, then supervises the fixed 45-trial matrix. A completed experiment may favor any objective or none. The read-only verifier checks retained evidence and replays exact controls; it does not retrain the models. Source, checkpoints and synthetic results remain local. No general language-learning claim follows from this study. Read the completed [REP-001 findings](docs/REPRESENTATION_FINDINGS.md) for all three widths, positive and negative results, measured resources and the next diagnostic question. Regenerate the all-seed summary and scientific plot with `scripts/summarize_representation.py `. The exact known-coordinate control and the learned model scores are reported separately. `scripts/replay_representation.py ` independently replays frozen weights with NumPy. The current audit retains one strict categorical mismatch; the supervised `scripts/diagnose_representation_replay.py ` identifies the observed near-tie without training or changing the original results. Both reports remain evidence. `scripts/package_representation.py ` seals the reviewed source, complete study, probes and diagnostic locally after review. ## Supplied-coordinate follow-up [REP-002](docs/REPRESENTATION_FIXED_PROTOCOL.md) compares learned coordinates with supplied Fourier coordinates. Both arms train their decoder and operation heads from the same training states and share identical initial decoder/head tensors. Ten trials use five paired seeds. This reuses the REP-001 world as a post-outcome diagnostic; it is not fresh benchmark confirmation. ```powershell & $renigmaGpuPython scripts/run_fixed_representation.py --probe & $renigmaGpuPython scripts/run_fixed_representation.py & $renigmaGpuPython scripts/run_fixed_representation.py --verify 'G:\RenigmaLLM_Artifacts\representation-fixed-runs\' & $renigmaGpuPython scripts/summarize_fixed_representation.py 'G:\RenigmaLLM_Artifacts\representation-fixed-runs\' & $renigmaGpuPython scripts/replay_fixed_representation.py 'G:\RenigmaLLM_Artifacts\representation-fixed-runs\' --output 'G:\RenigmaLLM_Artifacts\.json' ``` Native FP32 outputs are retained, including transformed coordinates and raw decoder scores. Replay reports categorical disagreements even when continuous errors are small. The [REP-002 findings](docs/REPRESENTATION_FIXED_FINDINGS.md) report outcomes, remaining failures and the next experiment. The new packager `scripts/package_fixed_representation.py ` seals reviewed evidence locally. Historical verification should use its original sealed source with Python `-B`; adding REP-002 changes the current runtime fingerprint even though all REP-001 runtime files remain unchanged. ## Frozen head intervention [REP-003](docs/HEAD_INTERVENTION_PROTOCOL.md) tests whether the H context-flip matrix accounts for REP-002's remaining Fourier-model errors. All five models run four arms: native, H-only refit, other-heads-only refit and all-refit. It copies the parent inputs, freezes encoders/decoders and performs zero optimizer updates. Refits are the already recorded training-only matrices. ```powershell & $renigmaGpuPython scripts/run_head_intervention.py --parent 'G:\RenigmaLLM_Artifacts\representation-fixed-runs\rep-a98ae7a10fd3' & $renigmaGpuPython scripts/run_head_intervention.py --verify 'G:\RenigmaLLM_Artifacts\head-intervention-runs\' & $renigmaGpuPython scripts/summarize_head_intervention.py 'G:\RenigmaLLM_Artifacts\head-intervention-runs\' & $renigmaGpuPython scripts/replay_head_intervention.py 'G:\RenigmaLLM_Artifacts\head-intervention-runs\' --output 'G:\RenigmaLLM_Artifacts\.json' ``` The [intervention findings](docs/HEAD_INTERVENTION_FINDINGS.md) distinguish repairs from regressions and report exact isolation controls. This is a local intervention on previously evaluated models, not another language-training run. Use `scripts/package_head_intervention.py ` to seal reviewed inputs, outputs and source after verification, preserving the earlier archive separately. ## H-only fitting comparison [REP-004](docs/HEAD_FITTING_PROTOCOL.md) continues the intervention with two fixed-budget fitting rules. It starts from each native H tensor and compares prediction-plus-latent loss with latent-only loss, using fresh Adam state while freezing the encoder, decoder and all seven other heads. Native H and the recorded train-only refit remain zero-update references. Each fitted arm receives exactly 1,000 updates; evaluation scores do not select settings or checkpoints. ```powershell & $renigmaGpuPython scripts/run_head_fitting.py --parent 'G:\RenigmaLLM_Artifacts\representation-fixed-runs\rep-a98ae7a10fd3' & $renigmaGpuPython scripts/run_head_fitting.py --verify 'G:\RenigmaLLM_Artifacts\head-fitting-runs\' & $renigmaGpuPython scripts/summarize_head_fitting.py 'G:\RenigmaLLM_Artifacts\head-fitting-runs\' --output 'G:\RenigmaLLM_Artifacts\.json' & $renigmaGpuPython scripts/replay_head_fitting.py 'G:\RenigmaLLM_Artifacts\head-fitting-runs\' --output 'G:\RenigmaLLM_Artifacts\.json' ``` The parent folder must contain the retained local REP-002 inputs; the public repository does not include those historical checkpoints. The new runner records the exact published license-metadata migration and retains the parent's bytes. It rejects other changes to inherited runtime files. Read-only verification checks runtime bytes independently of later documentation-only Git commits. The comparison tests recovery on existing cases, not fresh-world generalization. The [REP-004 findings](docs/HEAD_FITTING_FINDINGS.md) report the completed GPU comparison: latent-only H fitting repaired all 2,062 length-16 errors without regressions; prediction-plus-latent repaired 1,186 but introduced 93 new errors. Independent NumPy replay matched every saved answer. Both fitted arms have a 100% median, so inspect the all-seed results rather than the median alone.