qriton 0.4.0 → 0.5.0

package/docs/hlm-setup.md

@@ -0,0 +1,105 @@
+# Set up an HLM model workspace
+
+Qriton is the coding tool. Hugging Face supplies the published model weights,
+and a local Python runtime loads them. Each installation uses its own workspace, runtime, and model files.
+
+## Choose a model
+
+Install the CLI, create a project folder, and view the supported setup paths:
+
+```sh
+npm install -g qriton
+mkdir my-hlm-project
+cd my-hlm-project
+qriton hlm setup
+qriton hlm setup hlm5-1b
+```
+
+Guided setup supports `hlm5-1b`, `hlm5-1b-hybrid`, and `hlm5-3b`. It requires an
+installed Python 3.10–3.12 interpreter. To select one explicitly:
+
+```sh
+qriton hlm setup hlm5-1b python python3.11
+```
+
+On Windows, replace `python3.11` with `python` or the full interpreter path.
+This command previews setup without starting Python, making network requests,
+or writing files. The preview lists the pinned runtime, dependency versions,
+project files, and user settings that will change.
+
+## Apply the reviewed setup
+
+Copy the apply command and fingerprint printed by the preview:
+
+```text
+qriton hlm setup hlm5-1b apply <fingerprint>
+```
+
+Keep the `python <executable>` selection in the apply command if you used one.
+Changing the configuration, runtime, or starter files invalidates the preview.
+Plan mode permits the preview and blocks apply.
+
+Apply creates a Python environment under `.qriton/hlm/runtime/`, downloads the
+specified HLM5 source commit with file integrity checks, and installs the
+Python dependencies. It checks the installed runtime without loading model
+weights. Dependency installation uses the official Python package index and
+the PyTorch CPU index where needed. Automatic setup requires host execution
+and unrestricted network policy; it does not relax a restricted policy.
+
+The workspace contains editable runner code and a registry under
+`.qriton/hlm/project/`. Setup selects this environment and registry in Qriton's
+user settings while preserving unrelated preferences. Existing project files
+are retained. Start a new coding session or restart a serving host after setup
+so it loads those settings.
+
+Setup records its intent and outcome on disk. A failed or interrupted runtime
+installation remains visible and is not automatically replayed. The printed
+receipt identifies its environment for inspection. Successfully set up
+environments can be explicitly checked again.
+
+## Download and run the model
+
+Model weights are a separate explicit download:
+
+```sh
+qriton hlm fetch hlm5-1b
+qriton hlm doctor
+qriton hlm project hlm5-1b
+qriton hlm run hlm5-1b -- --action inspect
+qriton hlm run hlm5-1b -- --prompt "The history of computing began" --tokens 16
+qriton hlm runs
+```
+
+Downloads go into `.qriton/hlm/models/<id>/` in this workspace. The 1B releases
+need about 4.2 GB of disk each; the 3B release needs about 10.8 GB. Python
+dependencies require additional space, and FP32 inference needs substantial
+RAM. The runtime and model files include their respective licenses.
+The guided runtime uses CPU inference.
+
+The downloader uses a pinned Hugging Face revision and verifies every file's
+size and SHA-256. Inspecting the runner's `--help` does not load the model.
+Runtime setup, file presence, and a successful process exit do not establish
+model accuracy; assess completion and evaluation outputs separately.
+
+## Work on the implementation
+
+Open Qriton in this folder and ask it to inspect or change
+`.qriton/hlm/project/model/run.py`. The assistant can discover the registered
+models, edit their code, request approval to run a command, and review the
+saved output. The starter registry includes all three supported language
+models; fetch each model before using it.
+
+For existing model projects, select their registry with `hlm.projectRegistry`.
+Other Hugging Face architectures and custom checkpoints need their own loader,
+dependencies, and registered runner. Guided setup currently covers the listed
+HLM5 releases. See the [HLM workbench guide](hlm.md) for editable memory,
+classifiers, and existing project integration, and [configuration trust](workspace-trust.md)
+for workspace overrides.
+
+## Platform coverage
+
+Runtime installation has been checked on macOS ARM64, Windows x64, and Linux
+ARM64. HLM5 1B baseline inference and saved project runs have been checked on
+macOS and Windows. Linux coverage currently includes runtime installation and
+reuse; model inference on Linux and the other catalog models needs separate
+validation. These checks establish integration behavior, not model accuracy.

package/docs/hlm.md

@@ -0,0 +1,356 @@
+# Qriton HLM integration
+
+Qriton exposes the parts of the HLM ecosystem that fit a coding workspace: local language-model inference, reviewed factual-memory edits, Energy Language checkpoint edits, and diagnostics for the memory graph's Hopfield recall policy.
+
+For a new installation, start with `qriton hlm setup`. The [public setup guide](hlm-setup.md)
+walks through selecting an interpreter, reviewing the runtime and starter-project plan,
+installing dependencies, downloading a published model, and running editable project code.
+
+The editable HLM5 1B models support single-token answers at exact prompts, with up to 32 fact addresses per overlay. Passing checks establishes behavior on the tested prompts, not general learning, paraphrase accuracy or better coding. `forget` deactivates an edit and retains historical snapshots; it is not secure deletion. HLM edits do not change the coding conversation's provider.
+
+## What is connected
+
+| Component | Integration | Scope |
+|---|---|---|
+| [HLM5 1B](https://huggingface.co/qriton/hlm5-1b-trunk) baseline | `hlm` model import/download, inspection, completion, editable memory | Single-token exact-prompt edits with measured target/locality checks. |
+| HLM5 1B hybrid | Same loader and memory-overlay adapter | Available for comparisons; full hybrid checkpoint validation is separate. |
+| [HLM5 3B Base](https://huggingface.co/qriton/hlm5-3b-base) | Pinned sharded-safetensors import/download and FP32 completion | Inference only. Loader coverage does not establish full-model quality or editing support. |
+| [HLM5 certificate package](https://github.com/qriton/hlm5) | Upstream certificate/dose and editable-memory APIs | Separately installed; model weights remain frozen. |
+| `.hlm` programs | Text-addressed `memorize`, `correct`, `forget` through `/hlm`; numerical basin edits through `/energy` | Two explicitly separate adapters. |
+| [Energy Language](https://github.com/qriton/energy-lang) / `qriton-hlm` | Existing HLM3 checkpoint workbench | Degree-3 polynomial Hopfield checkpoints; sampled structural checks and optional text evaluation. |
+| `@qriton/hopfield-anomaly` | Existing memory recall plus `memory probe` diagnostics | Embedding novelty/composition and plain-vs-Hopfield retrieval comparison. |
+| Qriton's gesture, activity, audio, CIFAR-10 and ModelNet10 models | Pinned downloads and classification of one local input file | Fixed label sets with family-specific runtime setup; no live sensor capture. |
+| [HF certificate explorer](https://huggingface.co/spaces/qriton/hlm5-energy-language) | Reference demonstration | The local integration runs in its own Python process; private prompts are not sent to the Space. |
+
+These base models are evaluation/completion tools. The coding conversation continues to use its configured instruction-following provider. Normal project facts still belong in the persistent memory graph; a one-token HLM edit is a different, narrower capability.
+
+Saved active HLM facts can nevertheless inform a coding turn. With `hlm.routeFacts: true` (the default), Qriton retrieves saved prompt/target strings by relevance and supplies them as labelled context to the configured chat model. This routing reads saved edit reports; it does not run HLM inference or change the coding model's weights. `hlm.enabled: false` disables agent workbench tools, but routing is controlled separately by `hlm.routeFacts`.
+
+`hlm.hosted: "deny"` withholds routed fact blocks, marked HLM tool data, deterministic receipts and generated HLM approval reminders from hosted providers. It also filters these sources before a failed or empty conversation summary falls back to copying transcript excerpts. It cannot remove facts a local model has already restated in ordinary conversation text. Keep HLM sessions local when that distinction matters; disabling routing does not erase earlier conversation content.
+
+## Work with existing model projects
+
+The model-project bridge connects Qriton's coding assistant to a compatible
+model registry and runner. It works alongside the pinned HF releases and
+their specialized workbenches. Your model project keeps its own loader,
+checkpoint format and inference or evaluation scripts.
+
+Set `hlm.projectRegistry` in **user configuration** to the exact registry you want
+to use. For example, for a workspace at `C:\model-projects`:
+
+```json
+{
+  "hlm": {
+    "enabled": true,
+    "projectRegistry": "C:\\model-projects\\multimodal_model_manager\\registry.json"
+  }
+}
+```
+
+Keep `hlm.python` set to the interpreter needed by those runners. Start Qriton
+in that workspace, or use `qriton -C C:\model-projects`. A paired phone
+can use the same commands on a serving host. A registry on the server is not a
+local execution target for a Qriton instance running on a different machine.
+
+```text
+qriton hlm projects
+qriton hlm project <model-id>
+qriton hlm run <model-id>
+qriton hlm runs
+```
+
+Append `json` to `projects`, `project <id>` or `runs` for structured output.
+Pass additional runner arguments after `--`, for example
+`qriton hlm run <id> -- --help`. Use `/hlm` instead of `qriton hlm` in chat.
+Phone discovery offers choices to inspect registered entries and run available
+commands. Typing a run command explicitly requests that operation. During a
+coding task, `hlm_run_project` opens the existing approval flow before execution.
+Plan mode permits discovery and blocks runs.
+
+The bridge reads registry v2 `models` and `demo_surfaces`. It resolves the
+entry's `demo_command`, then `command`, then its linked surface's `command`.
+It checks listed paths and displays the resolved argument vector without
+executing Python or loading checkpoints. Entries without a runner remain
+discoverable. Declared statuses such as `demo_ready` are shown as metadata;
+file presence does not establish runtime readiness or model quality.
+
+Runs pass **the exact discovered registry path** to `manager.py --registry`.
+They do not fall back to `registry.local.json`. The registry, manager and run
+plan have fingerprints; changing a reviewed plan invalidates its approval.
+The manager and its working directory must be inside the current workspace.
+Qriton uses its shared process runner, configured deadline and cancellation
+controls. A registered script executes under that process policy and the
+current authorization.
+
+Before execution, Qriton saves an intent under
+`.qriton/hlm/project-runs/`. It records completion, failure, timeout or
+interruption afterward, with bounded stdout/stderr, exit code and source
+fingerprints. If final persistence fails, it reports an uncertain outcome and
+retains the initial record. It never automatically replays an unfinished run.
+A successful exit is evidence about the process; assess evaluation results
+from the recorded outputs separately.
+
+The assistant can now follow a practical workflow: discover the model, inspect
+its source and assets, edit the implementation, run the selected command with
+approval, and review the outcome. This bridge does not manage background
+training jobs or publish models to HF.
+
+## See the memory edit
+
+Use `qriton hlm overview` in a shell or `/hlm overview` in a terminal session to see the local model catalog, installation metadata, selected revisions, agent-tool settings, fact-routing policy and next commands. This overview does not start Python, download assets or call a model. A present manifest is not proof that the model files or runtime work; use the suggested doctor and inspection commands to check them.
+
+For a broader workspace overview, use `/capabilities` in terminal chat or `qriton capabilities` in a shell. It reads configuration and workspace metadata only: no provider requests, Python startup, downloads, model loading or memory-store writes. An installation manifest is labeled as metadata, not proof that the runtime or weights are ready. The terminal banner links to this overview and reflects whether project memory and HLM agent tools are enabled.
+
+These capabilities serve different purposes:
+
+| Layer | Useful for | How to inspect it |
+|---|---|---|
+| Persistent memory graph | Project decisions and facts across coding sessions; links, corrections and restorable forgetting | `/memory`, `/recall <query>` |
+| Hopfield recall over embeddings | Inspecting novelty and mixtures of stored patterns when compatible vectors are available | `/memory probe <query>` |
+| HLM5 editable memory | Controlled single-token edits to a local frozen model, with measured acceptance and rollback | `/hlm preview`, `/hlm compare`, `/hlm evaluate`, `/hlm restore` |
+| HLM classifiers | Speech keywords, phone activity, gestures, images and 3D objects from one local file, with each layer's settling record | `/hlm classify <model> <file>` |
+
+After the optional runtime and 1B model are installed, compare a prompt before and after an approved edit:
+
+```sh
+qriton hlm compare hlm5-1b "The capital of Veldoria is"
+qriton hlm preview hlm5-1b examples/hlm/memorize.hlm examples/hlm/controls.json
+qriton hlm show <proposal-id>
+# If the preview passed and you want to activate this edit:
+qriton hlm apply <proposal-id>
+qriton hlm compare hlm5-1b "The capital of Veldoria is"
+qriton hlm evaluate <proposal-id>
+qriton hlm restore <proposal-id>
+qriton hlm compare hlm5-1b "The capital of Veldoria is"
+```
+
+`compare` returns `base` and `active` next-token text, IDs, margins and full-logit hashes, the active revision, and `changed` flags plus the maximum absolute logit difference. It evaluates both variants in **one model load**, preserves the overlay, and uses the same workspace lock, asset verification and runtime binding as prediction. With no overlay, both predictions are identical. The 3B inference-only model also supports comparison without an editable overlay. Results describe one prompt; `evaluate` checks the proposal's saved controls and retained facts. Neither command establishes broad language understanding or improved coding performance.
+
+In chat, `/hlm compare` displays a short frozen/active comparison and the next evaluation command. The shell command preserves the full JSON report, including runtime fingerprints and logit hashes, for inspection or scripting.
+
+When HLM agent tools are enabled, the assistant can call `hlm_inspect` with `action: "compare"` and explain the result alongside the saved evaluation. HLM is loaded only for the operation and released afterward. Discovery does not enable these tools or change your coding provider. OpenAI can continue handling coding while the optional HLM workbench is used on demand.
+
+Exact-prompt checks cover one target, retained facts and unchanged controls. They are not a measure of general coding quality. The upstream [HLM5 research and limits](https://github.com/qriton/hlm5) describe the certificate mechanism and its operating scope.
+
+## Manage an HLM fact through conversation
+
+With a local editable model installed and `hlm.enabled: true`, the coding model can translate a request into the existing checked memory operations. For example: “Use the local HLM5 model to remember that Forgepack's release channel is beta,” followed by “Correct that channel to stable.” The requested token and controls still have to pass the native preview; a natural-language request does not bypass those checks.
+
+`hlm_inspect` with `action: "facts"` and `model: "hlm5-1b"` returns the active fact IDs, exact prompts, values and current revision. Use `model` for `inspect`, `facts`, `read`, `predict` and `compare`; use `proposal` for `show` and `evaluate`. The legacy `target` selector remains supported, but must agree with the named field if both are supplied. IDs derive from the model and exact prompt bytes, so they remain stable through correction and restoration, including for older overlays. For corrections and forgetting, `hlm_propose` requires `fact` and `revision`. An optional `prompt` is only an assertion: it must match the saved prompt exactly, including whitespace. The workbench resolves the original prompt from the fact ID under the workspace lock and rejects stale revisions or mismatched assertions before inference. The assistant should clarify ambiguous matches instead of choosing a different prompt spelling.
+
+An optional `reason` records the proposer's explanation in the preview and active fact metadata. It is not independent evidence or a user-authority label. Unrelated facts retain their reasons; restoring a revision restores its metadata too. The same preview, refusal, approval and artifact checks apply to both fact-ID and script-based edits.
+
+If a passing tool preview is followed by a chat-only approval handoff—claiming approval is pending, or saying it is ready for approval and telling you to apply it—Qriton may issue one conditional reminder to open the real approval flow; preview-only requests still stop without activation, and the reminder grants no permission.
+
+After activation, list facts again and call `hlm_inspect` with `action: "read"` and the current `fact` and `revision`. The saved revision identifies the model; an optional `model` must match it. This loads the native HLM at the canonical prompt and compares the returned token ID and positive margin with the saved target. `verified: true` means that exact native read matched. A wrong token or tie returns a failed tool result; stale, missing, altered or uncheckable facts fail explicitly. This verifies model behavior, not factual truth or semantic generalization.
+
+Successful activations, restorations and verified native reads produce **HLM tool receipts** recording actual tool observations, including revision IDs and native output. In a turn containing only HLM tools, a confirmed apply or restore switches the closing response to an **HLM operation summary** generated from these receipts. Subsequent model narration and thinking are suppressed before streaming and do not become the saved answer; further tool calls and approvals still run. Restore is reported as undoing the supplied proposal and selecting its parent revision. Fact presence or a token value is not inferred from the word “restore”; a verified native read has its own receipt.
+
+This summary covers recorded HLM operations only. Failed calls and interruption/step-limit status remain visible, and an interrupted turn does not undo an operation already committed. Other explanation requests need a separate answer. A registered non-HLM tool anywhere in the turn, or new user steering, keeps subsequent responses in the ordinary answer mode; discarded narration is never replayed. Read-only turns also retain ordinary narration. In these cases receipts are appended as evidence and can flag unknown labelled IDs, but cannot validate or correct the model's prose. Text already emitted before activation is outside the summary boundary. The existing hosted-deny policy withholds both forms of marked receipt output.
+
+To undo a change, call `hlm_inspect` with `action: "status"`, read the model's active proposal ID from `models`, then use `action: "show"` with that `proposal` to confirm the change. Pass this active change ID to `hlm_apply` with `action: "restore"`. Restore selects its parent revision; supplying the parent ID does not request restoration to that ID. The approval preview names the operation being undone and the revision that will become active. Restoring the first change returns to the frozen base.
+
+The shell and phone expose the same reads:
+
+```sh
+qriton hlm facts hlm5-1b
+qriton hlm read hlm5-1b <fact-id> <revision>
+```
+
+`forget` removes the fact from the active list. Evaluate its proposal to recheck removal and retained facts; restoring that proposal brings back the prior active fact. Historical snapshots and earlier conversation text remain, so a fresh session is needed to test recall without giving the assistant the answer in its transcript. Automatic fact routing continues to use labelled saved reports and does not claim fresh HLM inference.
+
+
+The operation-summary boundary addresses that captured restore-narration failure in HLM-only mutation turns. Its regression tests replay false, chunked model narration through the real Agent and tools with a synthetic HLM runtime. This is an output-contract fix; it does not change HLM inference, admission, approvals or stored overlays, and does not constitute a new native lifecycle pass.
+
+## Use HLM from your iPhone
+
+Connect a paired Qriton iPhone app to a workspace running `qriton serve`. From `/status` or `/models`, choose **Qriton models**, or type `/hlm`; on the phone this opens the same metadata overview as `qriton hlm overview`. Choices offer available next operations, while commands containing placeholders need your own prompt or file path. The app's typed-command and choice interface carries these host commands; no separate phone model installation is involved.
+
+The phone accepts the HLM workbench commands, including quoted prompts and paths:
+
+```text
+/hlm overview
+/hlm compare hlm5-1b "The capital of Veldoria is"
+/hlm preview hlm5-1b examples/hlm/memorize.hlm examples/hlm/controls.json
+/hlm show <proposal-id>
+/hlm apply <proposal-id>
+/hlm evaluate <proposal-id>
+/hlm restore <proposal-id>
+```
+
+Files and runtime configuration belong to the host workspace. Install the optional runtime there before operations that need it. `/energy` also reaches the host's HLM3 checkpoint workbench. Workbench progress appears in the conversation, and **Stop** cancels the active operation. A terminal exposed through `/share` does not accept this phone slash-command interface; use a serving host for it.
+
+Explicit `/hlm apply` and restore commands authorize the named operation just as they do in the terminal. When the assistant proposes activation during an ordinary coding task, it uses the same HLM tools and approval rules as the terminal: suggest and auto-edit modes ask for approval on the phone, and configured second-person approval still applies. Plan mode blocks installation and activation. A phone approval does not waive measured preview checks, fingerprints or stale-state rejection.
+
+With fact routing enabled, the shared coding agent can retrieve saved active HLM facts into a phone task. The conversation displays their source model and revision, plus the available check or relevance information. Attribution identifies the saved edit and retrieval evidence; it does not establish that a fact is true. Routing still uses the configured coding provider and honors `hlm.hosted`; the phone does not turn HLM5 into a coding-chat provider.
+
+The host integration uses the app's existing command, result, choice and approval messages. A physical iPhone acceptance check is still required for this change: open the overview, compare a prompt, inspect a preview, approve and deny an assistant activation, stop an operation, and confirm fact attribution in a coding turn. Automated host tests do not establish the native interface's behavior on a device.
+
+## Install the optional runtime
+
+The guided path is `qriton hlm setup <model-id>` followed by its fingerprinted
+apply command. It supports the three published HLM5 language models, installs
+a pinned runtime in a workspace environment, and selects the runtime and
+starter registry in user settings. Model weights remain an explicit fetch.
+The following instructions describe configuring a separately managed runtime.
+
+Install the upstream `hlm5` package and its dependencies in a Python environment. The tested local environment uses Python 3.10 and PyTorch 2.6. A separately checked-out upstream source directory can be selected explicitly:
+
+```sh
+git clone https://github.com/qriton/hlm5.git .qriton/hlm-runtime
+git -C .qriton/hlm-runtime checkout 46d00c55a47f8542f65ca7dcd1b4c464aeb33003
+python3.10 -m venv .qriton/hlm-venv
+.qriton/hlm-venv/bin/python -m pip install ./.qriton/hlm-runtime safetensors
+```
+
+```json
+{
+  "hlm": {
+    "enabled": true,
+    "python": "/absolute/path/to/venv/bin/python",
+    "sourcePath": "/absolute/path/to/hlm5-repository",
+    "timeoutMs": 180000
+  }
+}
+```
+
+The interpreter needs `torch`, `tokenizers`, and, for 3B, `safetensors`. `sourcePath` contains the upstream `hlm5/` package. It can be empty if that package is already installed in the interpreter. Model code is executable code selected through this configuration; the downloader fetches model data, tokenizer, documentation and license files, not Python source.
+
+When using `.qriton/config.json`, review it with `qriton trust show` and grant its fingerprint with `qriton trust grant <fingerprint>` before running the commands below. Editing that file requires a new grant. See [workspace configuration trust](https://unpkg.com/qriton/docs/workspace-trust.md).
+
+```sh
+qriton hlm doctor
+qriton hlm catalog
+qriton hlm fetch hlm5-1b
+# Or use a local HF release snapshot with matching files:
+qriton hlm import hlm5-1b /path/to/local/release
+qriton hlm inspect hlm5-1b
+qriton hlm predict hlm5-1b "The history of computing began" 16
+```
+
+Available IDs are `hlm5-1b`, `hlm5-1b-hybrid`, and `hlm5-3b`. Each download uses a pinned HF commit and verifies every file's size and SHA-256. The manifest is checked against Qriton's bundled catalog, and files are reverified before use. Failed or cancelled installations leave no installed partial model. An existing installation is checked and reused without overwriting it.
+
+Files live under `.qriton/hlm/models/`. A 1B release needs about 4.2 GB of disk; 3B needs about 10.8 GB. FP32 inference also needs substantial RAM. Loading uses memory mapping and meta-device initialization to avoid a second full model allocation. Heavy model operations are serialized within a workspace, and each process exits when its operation finishes. The release's included `LICENSE` describes its use terms.
+
+After a forced process termination, `.qriton/hlm/operation.lock` can remain. Remove it only after verifying that the recorded process has exited.
+
+## Edit factual memory with `.hlm`
+
+The HLM5 workbench defines a text-addressed `.hlm` dialect:
+
+```text
+memorize "The capital of Veldoria is" " Paris"
+```
+
+The leading space is part of the target. The tokenizer must encode it to exactly one token. `correct` updates an existing prompt address, and `forget` deactivates it. These operations each require a separate preview. They do not assert that the model learned a general concept or can answer paraphrased questions.
+
+The supplied [control suite](../examples/hlm/controls.json) includes a paraphrase and unrelated prompts. Replace or extend it for the intended task. A suite requires 2–16 distinct controls; the edit prompt cannot be one of them.
+
+```sh
+qriton hlm preview hlm5-1b examples/hlm/memorize.hlm examples/hlm/controls.json
+qriton hlm show <proposal-id>
+qriton hlm apply <proposal-id>
+qriton hlm predict hlm5-1b "The capital of Veldoria is"
+qriton hlm evaluate <proposal-id>
+```
+
+Use [correct.hlm](../examples/hlm/correct.hlm) and [forget.hlm](../examples/hlm/forget.hlm) in later previews to exercise corrections and forgetting. `memorize` rejects duplicate active addresses; `correct` and `forget` require an existing address. Already-predicted targets and unreachable targets are refused. Expensive residual-synthesis rescue is not run automatically.
+
+Preview uses the upstream float64 reachability certificate and dose selection, then tests the serialized FP32 memory overlay through the full model. Activation requires:
+
+- The requested token wins with a positive measured margin, or forgetting restores the original logits at that prompt.
+- Every remaining active fact still predicts its stored target with a positive margin.
+- All supplied controls have bit-identical logits to both the parent revision and the frozen trunk.
+- Up to six near-identical prompts, generated from the edit prompt by changing one code or number in it (for example `G71R070` → `G71R071`, `G71S070`), have bit-identical logits to the parent revision. Asset registers repeat one question across thousands of codes, and memory keys match on similarity, so an edit keyed on one code must not answer for the others. The report lists them under `neighbours`, and a refusal names the prompts that moved.
+
+Every refusal states its reason: the target was not reached, a stored fact or a control changed, or a near-identical prompt changed.
+
+In practice the neighbour check matters most after the first edit: calibration is frozen on that first prompt, so later edits with a different question template are more likely to reach every code that shares their template, and they are now refused instead of applied.
+
+The adapter uses upstream degree-5 memory, temperature 0.10, and gate threshold 0.95. First-edit prompt/control hidden states provide pooled ZCA calibration, which remains frozen across revisions. This calibration choice is recorded; it is not an exact reproduction of the paper's multi-fact calibration dataset. A certificate alone is insufficient for activation: measured FP32 behavior must also pass.
+
+Apply selects the overlay used by subsequent `hlm predict` calls. Snapshots contain the editable memory and calibration, not another copy of the large base model. Previews and receipts bind the script, model manifest, runtime/adapter code, controls, parent and candidate fingerprints. `evaluate` repeats the saved checks without changing the original activation decision.
+
+Preview and evaluation reuse frozen hidden states for repeated token sequences within that one operation, bounded to 64 entries and 64 MiB. Each overlay still runs the original output-head and preservation checks. This adapter change produces a new runtime fingerprint: older proposal metadata and restore operations remain available, but native inference on those snapshots requires their matching runtime. They are not silently migrated or accepted under the new adapter.
+
+```sh
+qriton hlm restore <active-proposal-id>
+qriton hlm status
+```
+
+Restore newer revisions first. Restoring the first revision returns to the frozen trunk. `forget` and restore retain historical snapshots for audit and recovery; they are not secure deletion. This workbench supports up to 32 fact addresses in an overlay. Stale proposals, changed artifacts, model assets or runtime implementations are refused.
+
+Commands also work after `/hlm` in chat. `hlm.enabled` exposes five agent tools: inspect/predict, classify, propose, preview, and apply/restore. Agent activation requires approval in suggest and auto-edit modes. Plan mode permits inspection and isolated previews, but blocks model installation and activation. Explicit CLI/slash apply commands are direct user instructions.
+
+## Four eyes: a second person approves
+
+For critical systems, an HLM edit can require a second person, on another machine, before it applies. List the approvers' machine ids in `hlm.approvers` (each approver gets theirs from `qriton hlm id`):
+
+```json
+{ "hlm": { "approvers": ["3ca8c8cd2c4193259a133802145a97a4"] } }
+```
+
+With approvers set, `hlm apply` refuses until a valid approval is kept for that proposal:
+
+```sh
+qriton hlm request <proposal-id>     # on the machine with the model: a signed request
+qriton hlm review <request>          # on the approver's machine: who asks, what changes, what the checks measured
+qriton hlm approve <request>         # on the approver's machine: signs an approval
+qriton hlm accept <approval>         # back on the first machine; then hlm apply
+```
+
+In terminal chat, `/hlm request <proposal-id> <peer>` sends the request over the encrypted mesh. The approver sees it with `/hlm approve …` ready to run, and the approval comes back automatically. Codes are signed, so they can also travel by any other channel.
+
+At apply, the approval is checked again:
+- **Signature:** it must come from the machine it names.
+- **Approver:** that machine must be in `hlm.approvers`, and must not be the machine applying.
+- **Age:** it expires 24 hours after the request.
+- **State:** it must match the exact proposal and model state it was requested for. Any apply, restore, model change or runtime change in between makes it stale.
+
+The history records who approved. A machine cannot approve its own request, plan mode cannot approve, and no model can request or approve: these are commands for people only. `restore` never waits for a second person, so an incident can always be rolled back immediately.
+
+The approver signs what the requesting machine reports: the checks run where the model is. Compare the machine fingerprint shown by `hlm review` out of band before approving.
+
+## Classify audio, motion, images and 3D shapes
+
+Five small HLM classifiers read one file each and run on the CPU:
+
+| Model | Reads | Answers | Accuracy (measured / published) |
+|---|---|---|---|
+| `hlm-keyword` | WAV speech; the first second at 16 kHz | yes, no, up, down, left, right, on, off, stop, go, silence, unknown | 92.1% / 92.1% (Speech Commands v2 validation) |
+| `hlm-activity` | CSV, 128 rows at 50 Hz: body acceleration x y z (g, gravity removed), gyroscope x y z (rad/s) | walking, upstairs, downstairs, sitting, standing, laying | 93.5% / 93.5% (UCI HAR test, unseen people) |
+| `hlm-gesture` | CSV of accelerometer x y z, any length | the 8 uWave gestures | 94.2% / 94.2% (uWave test) |
+| `hlm-vision-small` | Any image, resized to 32×32 | the 10 CIFAR-10 classes | 78.7% / 78.6% (CIFAR-10 test) |
+| `hlm-spatial-small` | Point cloud: `.npy` (N×3) or x y z text | the 10 ModelNet10 objects | 81.8% / 83.6% (ModelNet10 test) |
+
+```sh
+qriton hlm fetch hlm-keyword                     # pinned weights, SHA-256 checked
+qriton hlm classify hlm-keyword recordings/stop.wav
+```
+
+The result gives the label, the top five probabilities, the input's SHA-256, and per layer how many settling iterations the network used (and its final energy, where the model reports one). The same input file always gives the same answer: point clouds are sampled with a fixed seed.
+
+Each classifier only knows its own classes. A recording of another word comes back as `_unknown_` at best, and a photo of something outside CIFAR-10 still gets one of the ten labels, so treat a low top probability as "not sure". The accuracy column is what we reproduced from the published weights; the 3D model scores slightly below its published figure: 81.8% with the fixed sampling qriton uses, 81.6–83.2% across nine different samplings.
+
+The classifiers need `torch` and `numpy` in `hlm.python` (plus `torchaudio` for audio and `Pillow` for images), and the Qriton model code for each family in `hlm.classifierSources`:
+
+```json
+{ "hlm": { "classifierSources": {
+  "hlm-micro": ["<hlm-micro code>"],
+  "hlm-vision": ["<hlm-vision code>", "<hlm-core src>"],
+  "hlm-spatial": ["<hlm-spatial code>", "<hlm-core src>"] } } }
+```
+
+`qriton hlm doctor <classifier-id>` checks that setup without classifying anything. With `hlm.enabled`, chat models can call `hlm_classify` on workspace files; with `hlm.hosted: "deny"`, the results stay away from hosted models like all HLM data.
+
+## Inspect associative recall
+
+```sh
+qriton memory probe "Which conventions apply to our API tests?"
+```
+
+Or use `/memory probe <query>` in chat. The diagnostic compares plain and Hopfield recall over the same stored graph, query embedding and limits. It reports selected memories, added/removed results, energy, novelty, composition and the resulting recall policy. It does not reinforce memories or change the configured policy. Embedding requests use the existing configured embedding backend.
+
+These readings describe embedding geometry. They do not measure factual truth or establish an HLM-specific retrieval advantage. Missing/incompatible embeddings leave keyword/graph recall available.
+
+Manual model checks belong to a source checkout. The installed package does not include them. A successful exact-prompt edit does not change the coding model.

package/docs/workspace-trust.md

@@ -0,0 +1,68 @@
+# Workspace configuration trust
+
+Qriton requires an explicit grant before applying a project's `.qriton/config.json`. This includes existing project configuration. Without a valid grant, startup stops before loading credentials, contacting providers, or starting an optional Python runtime. A workspace without project configuration uses user/default settings without a grant.
+
+## Review and grant
+
+Run these commands in the intended workspace, or supply `-C /path/to/project` to each command:
+
+```sh
+qriton trust show
+```
+
+The offline report displays the canonical workspace, configuration file, a SHA-256 fingerprint, current trust status, and configuration with secret fields and URL credentials/query values redacted. Review the actual file, especially approval mode, shell rules, provider endpoints, model selection, and HLM/Energy executable and source paths. Then use the fingerprint you reviewed:
+
+```sh
+qriton trust grant <fingerprint>
+qriton doctor policy
+```
+
+Replace `<fingerprint>` with the reported 64-character value. A stale or incorrect value is rejected. Do not automate approval by piping a freshly computed fingerprint straight into `grant`; that skips review of what the configuration authorizes.
+
+Trust is bound to the canonical workspace and the exact configuration bytes. A symlink alias for the same workspace shares its grant; a different workspace cannot reuse it. Editing configuration, including formatting, requires review and a new grant. Removing the file returns new invocations to user/default configuration. Creating, changing, or removing it during an active session stops subsequent guarded operations and requires a restart.
+
+```sh
+qriton trust revoke
+```
+
+Revocation takes effect at the next execution boundary, including after a pending tool approval. It does not undo completed actions or terminate a subprocess already running. Revoke remains available when project configuration or the receipt is malformed. Plan mode cannot grant trust; revocation is allowed.
+
+Receipts live in `$QRITON_HOME/trust/`, normally `~/.qriton/trust/`, with private files and atomic replacement. The state directory and resolved user configuration must be outside the active workspace. Project configuration must be a bounded regular file inside that workspace; symlinked configuration files are rejected.
+
+## Effective policy
+
+`qriton doctor policy` works offline even when project configuration is untrusted. `/policy` displays the loaded session's settings in chat. Reports show whether project configuration was applied, current trust status, whether a restart is needed, allowed approval modes, and each setting's origin: default, environment, user, trusted project, invocation, or a runtime change.
+
+Untrusted project overrides are not merged into an inspection configuration. `qriton trust show` displays the proposed project values separately. Inspection configurations cannot execute actions. `qriton config init` writes user settings/defaults without copying project permissions or endpoints into global configuration.
+
+The regular precedence remains defaults/environment defaults, user configuration, trusted project configuration, and invocation overrides. `QRITON_MODEL` overrides configured model selection before an explicit `--model`; `OLLAMA_HOST` overrides the configured Ollama endpoint. Launcher-managed limits apply after merging. `--yolo` changes approval mode within those limits and does not grant workspace trust.
+
+## Launcher-managed limits
+
+A trusted launcher can set `QRITON_POLICY` to an absolute path outside the workspace:
+
+```json
+{
+  "version": 1,
+  "allowedModes": ["suggest", "plan"],
+  "allowProjectConfig": true
+}
+```
+
+```sh
+QRITON_POLICY=/absolute/path/to/managed-policy.json qriton -C /path/to/project
+```
+
+`allowedModes` is a nonempty list drawn from `suggest`, `auto-edit`, `full-auto`, and `plan`. The default allows all four. A disallowed configured or requested mode fails explicitly; Qriton does not silently choose another. The same check applies to `--mode`, `--yolo`, `/mode`, agent dispatch, and resume. Saved sessions cannot restore an older permission grant.
+
+`allowProjectConfig: false` prevents project settings from being applied even if a receipt already exists, and prevents new grants. Project configuration is still read for inspection and validated as a bounded JSON object; malformed files cause an error. This switch does not disable reading repository instruction files as task context.
+
+The optional `network` block adds destination limits and hosted-fallback controls. Every applicable user and managed network policy must permit a request; project configuration cannot set network policy. Only the documented policy fields and `version` are accepted. Invalid, missing, or unreadable selected policy files fail closed. Changing or removing a loaded policy causes subsequent guarded actions to stop until Qriton is restarted. Keep the policy file, launcher environment, and user-state location under the administrator's control when using these limits for a managed deployment.
+
+## Scope of these controls
+
+This feature authorizes configuration. It does not approve every repository file, establish that project instructions are safe, or bind the contents of an executable named by a trusted path. Repository instructions cannot grant programmatic permissions; they remain model context and can still contain prompt injection.
+
+CLI startup, interactive commands, agent mode changes, tool execution after approval, and background model/memory work check the loaded trust and policy. Internal programmatic callers that construct a `Config` directly are trusted host code; the public CLI uses the guarded loader.
+
+The implemented managed limits cover approval modes, project-configuration loading, and HTTP destination policy. Session conflicts and save failures also have recovery handling. This grant does not provide OS isolation or organization-wide memory administration. Restricted network profiles block unconfined shell, Git and Python execution. In unrestricted mode, shell commands run with the user's OS privileges. Application checks do not contain arbitrary code that already has access to the same account.

package/examples/hlm/forgepack/README.md

@@ -0,0 +1,37 @@
+# Forgepack — reviewed edition
+
+Version: 0.7.0
+
+A dependency-free, offline release-readiness checker. It prints JSON and does not publish, run package scripts, or contact a service.
+
+This example uses `stable` as its default release channel. Use `--channel` to
+choose another channel. It runs independently of HLM and does not query model
+memory.
+
+Run from this directory:
+
+```sh
+npm test
+npm run release:check
+node bin/release-readiness.mjs --root /path/to/package --channel nightly
+```
+
+No installation is required. Node.js 22.16 or newer is supported.
+
+The report contains `name`, `version`, `channel`, `prerelease`, `ready`, and `issues`. `prerelease` describes the selected channel: it is false for `stable` and true for other channels. It does not parse or change the package version.
+
+A package is ready when:
+
+- `package.json` is a readable file inside the selected root, containing nonempty string `name` and `version` fields and a `files` array of nonempty strings.
+- `README.md` is a readable file inside that root with exactly one line beginning `Version:`. Its complete trimmed value must equal the manifest version, including any prerelease or build suffix.
+- Every declared file resolves to a regular file inside the root. Empty files are allowed. Absolute paths, paths that escape the root, directories, missing files, and symlinks pointing outside the root fail the check. Symlinks to regular files inside the root are allowed.
+
+`files` entries are **literal, forward-slash-separated paths**. The checker does not expand globs, apply npm ignore rules, or recurse into directories. It is not an `npm pack` simulation, a full package validator, or a security sandbox. Filesystem changes made concurrently can invalidate a report after it is produced.
+
+Channels must contain 1–64 ASCII letters, digits, dots, underscores, or hyphens and begin with a letter or digit. Duplicate flags and missing flag values are invalid.
+
+Exit codes:
+
+- `0`: ready; JSON report on stdout.
+- `1`: readiness checks failed; JSON report and issues on stdout.
+- `2`: invalid invocation, root, or manifest; an error on stderr.