dentate 0.1.0__tar.gz

dentate-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Marius-Constantin Dinu / Alpha Omega Labs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

dentate-0.1.0/PKG-INFO

@@ -0,0 +1,423 @@
+Metadata-Version: 2.4
+Name: dentate
+Version: 0.1.0
+Summary: Dentate — RLVR + distillation for small models: SFT → support gate → GRPO → frozen eval, with the Spiral looped transformer demo
+Author-email: Marius-Constantin Dinu <dinu.marius.constantin@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://dentate.cortex.a2olabs.com
+Project-URL: Source, https://github.com/Xpitfire/dentate
+Project-URL: Issues, https://github.com/Xpitfire/dentate/issues
+Project-URL: Colab, https://colab.research.google.com/github/Xpitfire/dentate/blob/main/examples/colab/dentate_bootcamp.ipynb
+Keywords: reinforcement-learning,rlvr,grpo,distillation,small-language-models,spiral,bootcamp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: dentate/demo/NOTICE
+Requires-Dist: pyyaml
+Provides-Extra: serve
+Requires-Dist: fastapi<1,>=0.115; extra == "serve"
+Requires-Dist: uvicorn<1,>=0.30; extra == "serve"
+Requires-Dist: pydantic<3,>=2.9; extra == "serve"
+Requires-Dist: httpx<1,>=0.27; extra == "serve"
+Requires-Dist: PyJWT[crypto]<3,>=2.9; extra == "serve"
+Requires-Dist: python-multipart; extra == "serve"
+Provides-Extra: demo
+Requires-Dist: dentate[serve]; extra == "demo"
+Requires-Dist: torch<3,>=2.6; extra == "demo"
+Requires-Dist: transformers<6,>=4.46; extra == "demo"
+Requires-Dist: numpy<3,>=1.26; extra == "demo"
+Requires-Dist: spiral-lm<0.2,>=0.1.0; extra == "demo"
+Provides-Extra: bootcamp
+Requires-Dist: dentate[demo]; extra == "bootcamp"
+Provides-Extra: bootcamp-web
+Requires-Dist: dentate[serve]; extra == "bootcamp-web"
+Provides-Extra: api
+Requires-Dist: dentate[serve]; extra == "api"
+Provides-Extra: mlx
+Requires-Dist: mlx; extra == "mlx"
+Requires-Dist: mlx-lm; extra == "mlx"
+Requires-Dist: mlx-lm-lora; extra == "mlx"
+Provides-Extra: cuda
+Requires-Dist: torch>=2.6; extra == "cuda"
+Requires-Dist: transformers; extra == "cuda"
+Requires-Dist: peft; extra == "cuda"
+Requires-Dist: trl; extra == "cuda"
+Requires-Dist: datasets; extra == "cuda"
+Requires-Dist: verl; extra == "cuda"
+Provides-Extra: wandb
+Requires-Dist: wandb; extra == "wandb"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: playwright; extra == "dev"
+Requires-Dist: pytest-playwright; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: fastapi; extra == "dev"
+Requires-Dist: uvicorn; extra == "dev"
+Requires-Dist: python-multipart; extra == "dev"
+Requires-Dist: PyJWT[crypto]; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: torch>=2.6; extra == "dev"
+Requires-Dist: transformers; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: nbformat; extra == "dev"
+Dynamic: license-file
+
+# Dentate
+
+> **RLVR + distillation for small models.** Project → SFT → measured support → gated GRPO → frozen evaluation,
+> with the [Spiral](https://github.com/Xpitfire/spiral) looped transformer as the demo model.
+> Site: **https://dentate.cortex.a2olabs.com** · Package: `pip install "dentate[demo]"` · Apache-2.0
+
+Dentate trains a small model from *verifiable, scored experience* and refuses to reinforce what the model cannot
+already do: GRPO runs only after a pass@k support sweep finds a harvestable gap. Reward and evaluation share one
+semantic verifier; the frozen evaluation set is content-disjoint from every training pool. A failed gate is an
+honest, successfully measured result (post-GRPO accuracy is then absent, not zero).
+
+## Run it
+
+**pip** (Python 3.11+, CPU is enough; macOS / Linux / Windows):
+
+```bash
+pip install "dentate[demo]"
+dentate demo doctor          # torch / transformers / spiral / tokenizer / SPA checks
+dentate demo init            # bundled starter project + pinned SmolLM-135M-Instruct tokenizer → ~/.dentate/demo
+dentate demo run             # trains the starter on CPU → ~/.dentate/experiments/<timestamp>/result.dentate
+dentate serve                # the site on http://127.0.0.1:8793 — public pages + your local lab, data in ~/.dentate
+```
+
+No download happens after the install: the wheel bundles the starter project, the tokenizer (one pinned Hugging Face
+revision, SHA-256s in `dentate/demo/TOKENIZER.json`) and the built web app. No model weights, teacher or oracle.
+
+**Colab** — [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Xpitfire/dentate/blob/main/examples/colab/dentate_bootcamp.ipynb)
+`examples/colab/dentate_bootcamp.ipynb`: install → init → run → the site through Colab's port proxy.
+
+**Download the CLI** (no Python needed; one-folder bundles built by the release workflow):
+[macOS arm64](https://github.com/Xpitfire/dentate/releases/latest/download/dentate-macos-arm64.zip) ·
+[Linux x64](https://github.com/Xpitfire/dentate/releases/latest/download/dentate-linux-x64.zip) ·
+[Windows x64](https://github.com/Xpitfire/dentate/releases/latest/download/dentate-windows-x64.zip)
+
+**Hosted** — https://dentate.cortex.a2olabs.com: browse papers, docs and public results without an account; sign in to
+launch experiments on the bootcamp workers and to publish results and papers (private by default).
+
+Student guide: **[docs/BOOTCAMP.md](./docs/BOOTCAMP.md)** (local / Colab / hosted, project schema, result files,
+troubleshooting).
+
+### CLI
+
+| command | what |
+|---|---|
+| `dentate serve [--host 127.0.0.1] [--port 8793] [--data ~/.dentate]` | the whole site locally (same app as prod, implicit local session; loopback only) |
+| `dentate demo init [--dir ~/.dentate/demo]` | materialize tokenizer + starter, print the `export DENTATE_TOKENIZER_DIR=…` line |
+| `dentate demo run [--project P] [--out DIR] [--tokenizer DIR] [--quiet]` | train a `.dentate` project; `--out` must be new |
+| `dentate demo doctor` | environment check, exit 1 on any failure |
+| `dentate research-serve --out runs` | the owner research dashboard alone (the pre-0.1 `dentate serve`) |
+| `python -m dentate.bootcamp run\|serve\|worker` | attendee-local run, hosted frontdoor, training worker (unchanged) |
+
+Extras: `demo` (= `serve` + torch/transformers/numpy/spiral-lm), `serve` (FastAPI/uvicorn/pydantic/httpx/PyJWT/
+python-multipart); `bootcamp` / `bootcamp-web` / `api` are aliases; `mlx`, `cuda`, `wandb`, `dev` as before.
+
+### Releasing
+
+`make wheel` builds the SPA, then sdist + wheel, and asserts the wheel carries the demo tokenizer, starter and SPA;
+`make spiral-wheel` builds `spiral-lm` from `external/spiral`. Tagging `v*` runs `.github/workflows/release.yml`:
+build + verify + smoke from the wheel → PyPI (`PYPI_API_TOKEN`) → PyInstaller bundles for macOS-14/arm64,
+ubuntu-22.04/x64, windows-2022/x64 (`packaging/pyinstaller/dentate.spec`) attached to the GitHub release.
+
+Named for the **dentate gyrus** — the hippocampal region for **neurogenesis, pattern separation, and
+experience replay**. In Cortex, the [Gauntlet](../benchmark) gated composite is the **verifiable reward** Dentate
+uses to distill a strong oracle into a 1–8B local model and push past imitation with RLVR: Gauntlet scores →
+Dentate trains → the model re-registers as a Gauntlet harness → Gauntlet re-scores it → continual learning.
+
+## RL bootcamp: real hosted and attendee-local experiments
+
+The bootcamp is **not** the fake-backed research harness described further below. It trains a fresh CPU Spiral
+using the native reasoning SFT runner, measures sampled support with `passk_sweep`, and runs native GRPO only when
+both the support sweep and GRPO's independent gate permit it.
+
+Projects are attendee-local `.dentate` files: either bounded JSON configuration or a ZIP containing
+`project.json`, metrics/provenance JSON and optional SFT/GRPO checkpoint tensors. Import never unpickles a
+checkpoint in the public service. Imported metrics remain explicitly **historical and untrusted**;
+starting a project always cold-starts a new model, rather than implicitly resuming imported weights.
+Result packages preserve the new checkpoints, tokenizer file hashes, model/data seed, frozen tasks,
+semantic verifier version and new measurements. Keep the tokenizer alongside the package for reproduction.
+
+### Attendee-local run from a checkout
+
+`dentate demo run` is the packaged form of this. From a checkout, with the real Spiral package:
+
+```bash
+pip install -e '.[demo]' -e ./external/spiral
+dentate demo init                      # or: export DENTATE_TOKENIZER_DIR=dentate/demo/tokenizer
+python -m dentate.bootcamp run --project examples/rl-bootcamp/starter.dentate --out ./my-experiment
+```
+
+`examples/rl-bootcamp/prepare_tokenizer.py --out DIR --revision SHA` re-downloads the tokenizer from Hugging Face
+when baking a worker image at a different audited revision; the bundled copy is the one recorded in
+`dentate/demo/TOKENIZER.json`. Training itself is offline, with no teacher, oracle, external datasets or replay.
+The output directory must be new. It contains `result.dentate`, provenance, measurements and native
+Store run artifacts. Local CLI execution is not limited by the hosted lease; worker/UI jobs are.
+The UI's **Save editable project** saves configuration; **Download result package** saves the complete
+experiment. **Save original imported package** retains imported checkpoints and historical provenance.
+
+Use a locally produced checkpoint with the existing native benchmark (this is a **new benchmark**,
+not the frozen bootcamp comparison):
+
+```bash
+python -m dentate.cli reason-bench --checkpoint my-experiment/runs/sft/checkpoints/final.pt \
+  --teacher "$DENTATE_TOKENIZER_DIR" --device cpu --n-iters 2 --n-per-kind 8
+```
+
+For your own downloaded result package, its `checkpoints/sft.pt` and, when GRPO ran,
+`checkpoints/grpo.pt` members are the same native checkpoint format. Extract only these fixed members
+after validating the package with `dentate.bootcamp.project.load`; use the matching trusted tokenizer.
+Do not execute imported Python or load someone else's checkpoint into a privileged service.
+
+The final comparison uses one frozen content-disjoint set, excluding both training pools, SFT/GRPO
+internal evaluation sets and support-sweep tasks. Tiny finite task spaces can exhaust held-out content:
+`insufficient_heldout` stops before training rather than falling back to overlapping evaluation.
+Cold small models can legitimately produce `gate_failed`; then post-GRPO accuracy is absent, not zero.
+Native intermediate metrics and the frozen comparison have distinct scopes in the exported report.
+
+### Hosted frontdoor and trusted provider setup
+
+`python -m dentate.bootcamp serve` starts a **separate FastAPI application**. Do not publish the legacy
+`dentate.api.create_app` service. Keep the legacy runs, secrets and sandbox in a private owner backend;
+the frontdoor receives no owner data volume or owner provider credentials. Every legacy `/api/*`
+request is checked server-side for the explicitly mapped owner before a streaming proxy is opened.
+Attendees can access only their new temporary bootcamp jobs. The frontdoor imports no Torch models.
+
+Install `.[serve]` for the public service. Run `make web-build` before building the Python
+wheel: Vite writes `web/dist`, then the Makefile copies those built assets into `dentate/web`
+for package data. `DENTATE_SPA_DIR` can explicitly select a built SPA directory; the frontdoor refuses
+to start with missing built HTML. There is no fake/legacy HTML fallback.
+
+The legacy API grants local-owner sessions only with `create_app(..., local_owner=True)`; `dentate serve`
+always runs in that mode and therefore refuses non-loopback binds; `dentate research-serve` selects it only
+when bound to `127.0.0.1`, `::1`, or `localhost`.
+Non-loopback owner backends expose neither an automatic owner session nor local bootcamp jobs.
+The production Compose `site` service runs the separate frontdoor; `owner` has no published port
+and alone mounts the existing `dentate-data` volume. Set `DENTATE_FRONTDOOR_ENV_FILE` to the
+protected operator environment file before deployment. Never deploy the legacy image as `site`.
+
+Required operator configuration:
+
+| Variable | Contract |
+|---|---|
+| `DENTATE_PUBLIC_ORIGIN` | Exact HTTPS frontdoor origin, no path |
+| `DENTATE_TRUSTED_PROXY_IPS` | Exact ingress IPs/CIDRs, comma-separated; wildcard and `/0` forbidden |
+| `DENTATE_BOOTCAMP_ROOT` | Dedicated private writable state directory, default `/data/bootcamp` |
+| `DENTATE_LEGACY_URL` | Private owner-backend origin, default `http://127.0.0.1:8793`; never publicly routed |
+| `DENTATE_GOOGLE_CLIENT_ID`, `DENTATE_GOOGLE_CLIENT_SECRET` | App-specific Google OIDC client |
+| `DENTATE_GOOGLE_ISSUER` | Defaults to `https://accounts.google.com` |
+| `DENTATE_CORTEX_ISSUER`, `DENTATE_CORTEX_CLIENT_ID`, `DENTATE_CORTEX_CLIENT_SECRET` | App-specific Cortex OIDC issuer/client |
+| `DENTATE_OWNER_SUBJECTS` | JSON array of `{"issuer":"trusted issuer","subject":"verified subject"}` mappings |
+| `DENTATE_CORTEX_URL` | Independent Cortex resource API HTTPS origin; may be staging while the frontdoor is production |
+| `DENTATE_CORTEX_INSTALLATION` | Dedicated Dentate resource installation ID |
+| `DENTATE_CORTEX_INSTALLATION_TOKEN` | Dedicated installation bearer, at least 32 characters; never an admin token |
+| `DENTATE_CORTEX_ORGANIZATION` | Server-assigned organization ID for this installation |
+| `DENTATE_WORKER_IMAGE` | Approved immutable `registry/repository@sha256:...` worker image |
+
+The ingress must replace client-supplied forwarding headers, and only that ingress may reach the public
+service socket. The canonical hosted launcher trusts forwarding only from the explicitly configured
+ingress. Login admission is bounded per verified transport source; shared NATs can share the pending
+login allowance. Cookie sessions last 24 hours, store token hashes only and use Secure/HttpOnly cookies.
+Mutations require exact Origin plus CSRF; state, nonce and S256 PKCE bind OIDC login.
+
+Register these exact callbacks in the providers:
+`DENTATE_PUBLIC_ORIGIN/auth/callback/google` and `DENTATE_PUBLIC_ORIGIN/auth/callback/cortex`.
+Login starts at `/auth/login/google` or `/auth/login/cortex`; logout is `POST /auth/logout`.
+Google must attest `email_verified=true`. Cortex must supply that claim in the signed ID token or in
+subject-matching authenticated userinfo; Authentik's stock `email` scope hardcodes it to `false`, so
+provision the Cortex client with `scripts/provision-dentate-oidc.py` (in the Cortex repo), which
+installs an `email` mapping that attests only users whose current email equals their admin-pinned
+`verified_email` attribute (`DENTATE_VERIFIED_EMAILS`). No equal-email auto-linking occurs. Owner
+mode requires an explicit trusted issuer/subject mapping **and** verified
+`dinu.marius.constantin@gmail.com`.
+Without provider clients/source configuration, login remains unavailable; configuring a provider does
+not prove its credentials or callback registration work until the real login roundtrip succeeds.
+
+### Cortex training workers and retention
+
+Use the existing Cortex `/api/v1/resources` installation API. An operator registers a dedicated Dentate
+installation whose `metadataUrl` is the frontdoor origin, `secretRef` resolves its installation bearer,
+`maxRole` is `developer`, and `allowedImages` includes only the audited worker digest. No omegaXiv or
+other application grants/tokens are shared. Cortex calls
+`GET /v1/internal/cortex/runs/{id}` with that bearer to fetch server-derived execution metadata.
+The frontdoor bootstraps `/installations/{id}/runs` with only `{runId}`, receives a short-lived execution
+grant, then requests a fixed worker command/image/port through `/requests`. Attendees never select a
+command, image, credential, role, mount or filesystem path.
+
+Build the worker from `examples/rl-bootcamp/worker.Dockerfile` with the Dentate repository as build
+context and a reviewed `TOKENIZER_REVISION`. The image preinstalls real CPU Torch, Spiral and the
+tokenizer. It runs non-root with offline model loading; writable training artifacts go to Cortex's
+bounded `/work`, not its smaller `/tmp`. Cortex's root lease supervisor clears supplementary groups
+and drops the workload to UID/GID `1000` before execution; the standalone image uses `65532`.
+Publish and approve the resulting immutable digest.
+
+Each job is capped at 2 CPU, 2048 MiB memory, 256 MiB temporary workspace, and an execution lease
+of at most 30 minutes. Requested resource leases subtract elapsed bootstrap time and a safety margin.
+An installation should allow at most four concurrent containers / 8 GiB total memory; per-attendee
+workspace limits should allow one. App admission independently caps four active jobs globally, one
+per attendee, four retained records per attendee and 64 retained jobs globally. Invoke transport is
+JSON-framed/base64, at most 1 MiB per response / 30 seconds; project/result chunks are 256 KiB and
+training runs asynchronously with state polling. Upload packages are capped at 48 MiB compressed /
+64 MiB expanded, six allowlisted members, with traversal/symlink/duplicate/encrypted entries rejected.
+The frontdoor validates method, session, Origin and CSRF before reading imports. At most two
+authenticated imports are buffered through their handlers; excess imports get `503` with
+`Retry-After` before their bodies are read. Ordinary bootcamp/auth request bodies are capped at
+64 KiB. Worker upload chunks retain their separate 512 KiB encoded-envelope limit.
+Use the Cortex root `.cortex/app.yml` for deployment: it publishes the authenticating `site`
+frontend, includes private `owner`, checks `/healthz`, and requires the protected environment-file path.
+
+Server artifacts are temporary and deleted after 24 hours; attendees can download or explicitly
+delete them sooner. Cancellation terminates the local process group or releases the Cortex resource.
+On frontdoor restart, unfinished jobs fail explicitly rather than silently resuming; remaining resources
+are released when possible and always remain subject to Cortex's authoritative lease. Transport errors,
+lease expiry and release warnings remain observable, never replaced with synthetic successful metrics.
+Transient filesystem or SQLite maintenance failures are logged and retried on the next 30-second cycle;
+a failed artifact deletion does not stop cleanup of other jobs. Persistent failures require operator repair.
+Run one frontdoor process (`workers=1`); external multi-replica scheduling is not part of this contract.
+
+The installed PWA caches **only public shell assets**, never session/auth/API/job/owner responses.
+Offline navigation displays the shell and a failed-closed session screen. It never claims to execute
+Python offline. `mount_local(app, store_root)` from `dentate.bootcamp` adds local owner session and
+project/job routes to an existing local API; the legacy API's own data and training routes stay intact.
+
+## Design docs
+
+**The Spiral looped-transformer research harness (what actually ships in `pretrain/`):**
+- **[docs/TRAINING.md](./docs/TRAINING.md)** — online SeqKD + the self-stabilizing optimizer (rotational-equilibrium
+  AdamW · WSD · EMA · z-loss), the KD losses (soft-KD · SP-KD · JEPA · teacher-init), and the deep-loop stability
+  additions — with rationale + citations. The authoritative spec for the shipped distillation loop.
+- **[docs/ANALYSIS.md](./docs/ANALYSIS.md)** — the Analysis-tab interpretability & stability diagnostics (logit lens,
+  CKA, effective rank, ρ(J), the N-step Jacobian ∏J, arch internals) with formulas + citations.
+- **[docs/RESULTS.md](./docs/RESULTS.md)** — every notable run with full reproduction parameters, the current best
+  (`ceiling-mem-fullstack`), capacity/plasticity probes, the best model's diagnostics, and the reasoning-model results.
+- **[docs/MODEL_CARD.md](./docs/MODEL_CARD.md)** — the `spiral-reason` model card: architecture, ~1M core, training,
+  per-kind results, honest limits, performance, and how to run. **[docs/ROADMAP-REASONING.md](./docs/ROADMAP-REASONING.md)**
+  is the phased program (R0–R6); **[docs/FORMAT.md](./docs/FORMAT.md)** the chat protocol.
+- Architecture + deep-loop stability live in the Spiral repo: `external/spiral/docs/{MATH,STABILITY,SOURCES}.md`.
+
+**The RLVR-curriculum product vision (the broader Gauntlet design):**
+- **[docs/RESEARCH-2026-06.md](./docs/RESEARCH-2026-06.md)** — framework research (PyTorch vs MLX, verl/TRL,
+  on-policy distillation, W&B, the Gemma license).
+- **[docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — three tiers (student/teacher/oracle), the 3-source
+  reward (R1 verifiable ⊕ R2 reference ⊕ R3 RLAIF), masking task-gen, the eval/baseline/W&B layer (mermaid).
+- **[docs/REQUIREMENTS.md](./docs/REQUIREMENTS.md)** — F1–F30 / N1–N15 + roadmap.
+- **[docs/DASHBOARD.md](./docs/DASHBOARD.md)** — the training-dashboard design + API contract (W&B/TensorBoard/
+  Kaggle/Gauntlet-inspired; deployable at `dentate.<ip>.sslip.io`).
+- **[PLAN.md](./PLAN.md)** — the canonical phased checklist (P0–P7).
+
+## What's implemented — the dev harness (fake-backed vertical slice)
+The full pipeline runs **deterministically with zero downloads** on a *fake backend* + *fake oracle/teacher*
+over **synthetic** and **masking** task domains, so every layer is exercised and tested before real weights:
+
+```
+data → reward (R1 gate+tests ⊕ R2 similarity ⊕ R3 RLAIF/PRM) → SFT/GKD/DPO/GRPO → eval gate (CI rollback) → online
+                                              ↘ events + structured logs ↘ experiment/checkpoint store (resume) ↘ dashboard
+```
+
+**Fail-loud everywhere** (no hidden fallbacks): typed `errors.py`, an event bus that re-raises subscriber
+failures, requested-but-missing W&B → `TrackerError` (never a silent no-op). Runs persist to an inspectable
+JSON store with **checkpoint lineage + resume**; config via YAML + `--set` overrides; **sweeps** with multi-seed
+CIs. Every knob is a CLI command/param.
+
+Clean hexagonal architecture — a pure `domain/` (types + ports), with swappable adapters:
+
+| Port (`domain/ports.py`) | Fake (dev/test) | Real (its phase) |
+|---|---|---|
+| `Backend` | `backends/fake.py` | `backends/mlx.py` (P0/P3/P5), `backends/cuda.py` (P7) |
+| `Oracle` / `Judge` | `adapters/oracle/fake.py` | Anthropic (P3) |
+| `Teacher` | `adapters/teacher/fake.py` | MLX teacher (P3.5) |
+| `Tracker` | `NullTracker` | `WandbTracker` (`--report-to wandb`) |
+| `TaskSource`+`Verifier` | `tasks/synthetic.py`, `tasks/masking.py` | Gauntlet runrecord adapter |
+
+The fake backend models a policy as a scalar `skill` that rises with each training stage, so the curriculum,
+the reward composition, and the CI-aware promotion gate are all real and testable — only the *learner* is
+simulated. Swapping in MLX/CUDA + Anthropic is a one-line change in `harness.py`.
+
+## Run it
+```bash
+# from dentate/ (uses the fake backend — no model downloads). The test targets hydrate dentate's
+# own [dev] extra via `uv run`; the CLI targets still use the repo venv (../.venv).
+make run            # gated curriculum (default 'code'), persisted to ./runs
+make test           # 590 fast tests (fake backend; slow/real deselected)
+make smoke          # real MLX backend: downloads SmolLM-135M, runs a tiny LoRA SFT through the pipeline
+make lint           # ruff
+make checkpoints    # list runs   (make checkpoints RUN=<id> → checkpoint lineage tree)
+make site           # build the static dashboard (D1) → site/public/index.html
+make serve          # run the interactive dashboard (D2) on http://127.0.0.1:8793
+
+# or directly:
+PYTHONPATH=. python -m dentate.cli run    --domain synthetic --reward r1r2r3 --out runs --run-id demo
+PYTHONPATH=. python -m dentate.cli run    --backend mlx --model smollm-135m --stages sft --out runs  # REAL
+PYTHONPATH=. python -m dentate.cli resume --out runs --run demo --checkpoint baseline --stages grpo
+PYTHONPATH=. python -m dentate.cli fork   --out runs --run demo --set seed=1 --new-run-id demo2
+PYTHONPATH=. python -m dentate.cli sweep  --config sweep.yaml --out runs        # multi-seed grid + CIs
+PYTHONPATH=. python -m dentate.cli serve  --out runs                            # interactive dashboard
+PYTHONPATH=. python -m dentate.cli export-smi --checkpoint runs/RUN/checkpoints/final.pt \
+  --output /tmp/dentate-smi-source --tokenizer-dir PATH/TO/TOKENIZER \
+  --architecture auto --run-manifest runs/RUN/run.json
+```
+
+**Dashboards.** **D1** (`dentate site`) renders a static dashboard: runs index → run report with ECharts
+curves, stage timeline, the **full Config & Reproducibility panel** (every resolved parameter + copyable
+`reproduce`/`fork` commands + W&B/lineage links), checkpoint lineage, dataset preview. **D2** (`dentate research-serve`)
+is the interactive FastAPI app (`api.py` + `ui.py`): launch/fork/**train-further**/live-SSE, read+write API at
+parity with the CLI. Deploy bundle (`site/Dockerfile`, `../docker-compose.dentate.yml`, `.cortex/app.yml`)
+targets `dentate.<ip>.sslip.io`. See [docs/DASHBOARD.md](./docs/DASHBOARD.md).
+
+**Real backend.** `--backend mlx` runs a real model (SmolLM-135M LoRA SFT via `mlx-lm`) through the *same*
+curriculum/eval/store/dashboard as the fake backend (`make smoke`). DPO/GRPO on MLX = P5; CUDA/TRL = P7.
+
+Example (`run --domain synthetic --reward r1r2r3`):
+```
+baseline  composite 0.252
+sft   0.414 Δ+0.161 promoted   gkd 0.571 Δ+0.157 promoted
+dpo   0.582 Δ+0.011 promoted   grpo 0.673 Δ+0.091 promoted
+final composite 0.673  lift +0.420  gap_to_oracle 0.327 gap_to_teacher 0.244
+```
+
+## Layout
+```
+dentate/
+  domain/        ports (Protocols) + immutable types — the hexagonal core
+  config.py      typed specs (Model/Train/Reward/Teacher/Oracle/Distill/RewardModel/Domain/Eval/Wandb)
+  models/        registry: students (default Qwen3-4B-2507) + teachers (Gemma-4 ⇄ Qwen3-MoE)
+  tasks/         synthetic transforms + masking reconstruction (TaskSource + Verifier)
+  reward/        combine (gated R1⊕R2⊕R3) · service · distilled reward model
+  distill/       judge distillation (oracle rankings → local R3 reward model)
+  backends/      fake (dev) · mlx · cuda (stubs) · factory
+  adapters/      fake oracle/teacher · trackers (null/wandb)
+  data/          schemas (TRL-native) · jsonl io · replay buffer
+  eval/          stats · baseline registry + degradation gate · evaluate · report
+  train/         stage runners (sft/gkd/dpo/grpo) · curriculum (gated orchestrator)
+  online/        streaming continual-RLVR loop with replay
+  errors.py      typed error hierarchy (fail loud, no hidden fallbacks)
+  obs.py         structured logging + typed event bus
+  store.py       experiment/checkpoint store (JSON) — lineage + resume; the dashboard reads this
+  manifest.py    complete resolved run manifest (reproduce 1:1 + fork; no secrets)
+  runconfig.py   RunConfig + YAML load + --set overrides + sweep expansion
+  site.py        static dashboard generator (D1) — HTML + ECharts
+  api.py · ui.py interactive dashboard (D2) — FastAPI over the store/harness + vanilla-JS app + live SSE
+  backends/mlx.py  REAL Apple-Silicon backend — load/generate/logprobs + LoRA SFT over mlx-lm
+  harness.py     application wiring (curriculum / online / resume / fork / sweep; fake or mlx backend)
+  cli.py         models | tasks | run | eval | online | checkpoints | resume | fork | sweep | site | serve | export-smi
+  export_smi.py  tensor-only xLSTM/Spiral export for Sema Infer, with bound provenance
+```
+
+## Next (real backends)
+P0 spikes wire `backends/mlx.py` to `mlx-lm`/`mlx-lm-lora` and pin versions; P3 adds the Anthropic oracle and
+SFT-distill on `Qwen3-4B-2507`; P3.5 adds teacher GKD. The data + reward contracts are unchanged — see PLAN.md.