Thanks for your interest in loractl — a terminal-native LoRA trainer in Rust.
This is a short pointer file; the detail lives in the artifacts that already
carry it, so it can't drift.
- Rust — edition 2024, MSRV
1.92(pinned in the workspaceCargo.toml). just— the task runner;justlists every recipe.Cargo.lockis committed, so a plaincargo buildalso works.- Optional, only for regenerating goldens or the opt-in feature paths:
uv(for the PyTorch reference scripts),cargo-audit, andcargo-deny.
Run the same checks CI runs:
just fmt-check && just lint && just test
just lintiscargo clippy --all-targets -- -D warnings(warnings are errors) over the default, offline feature set.just testruns the offline suite — numerics vs. the PyTorch golden plus synthetic convergence; no network, no GPU.- Supply-chain gates:
just audit(RustSec advisories) andjust deny(licenses/bans/sources). CI additionally runsfeature-lintsover the opt-inmnist/gpt2-real/wgpupaths — mirror those locally withjust lint-mnist/lint-gpt2-real/lint-wgpu/lint-plotwhen you touch a feature-gated path. The CLI's opt-inplotfeature (#215) also has offline tests:just test-plot.
Features are offline by default: mnist, gpt2-real, and wgpu are
opt-in and never part of the default build or just test.
hubs/*.md anchor prose claims to code symbols.
Surface fingerprints each anchored
symbol's logic — ignoring comments, formatting, and consistent renames — and
CI (.github/workflows/docs-drift.yml) fails when one moves.
It is optional locally: install surf and run just surf to get the same
verdict CI will. Without it installed, nothing breaks; the Action is the gate.
When it fires, do not rubber-stamp it. The gate is a prompt to re-read, not a chore:
- Read the claim it printed. Decide whether the prose is still true — Surface only knows the code moved, never whether the sentence is now wrong.
- If the prose is stale, fix it first.
- Only then
surf verifyto re-seal the hash, and commit prose + code together.
surf check --format json emits a machine-readable verdict if you want a
reviewer to judge the "is it still true?" half.
What it does not cover. Anchors guard the spans they point at, so a change
elsewhere can falsify a claim while this gate stays green. Empirical claims —
VRAM numbers, throughput, upstream bug status — are not anchorable at all; those
live in docs/roadmap.md and the ADRs and are maintained by hand.
Five lint warnings are permanent, by decision. surf lint flags unanchored
public callables in any file a hub anchors into, so diffusion_trainer.rs is in
scope only because memory-route.md anchors one private function there. Its five
pub fns — denoiser_filename, encoder_fingerprint, load_fp8_encoder,
load_fp8_module, load_quant_module — stay unanchored deliberately (#166): the
file churns ~26 commits/90d, well past the low-churn bar the anchored symbols met,
and integration tests in crates/loractl-core/tests/ already pin them with
literal assertions. Surface 0.8.0 cannot record that acceptance — surf.toml
takes only hubs and bundles, and there is no ignore subcommand (upstream:
Connorrmcd6/surface#171) — so they recur every run, and this paragraph is the
only place the decision lives. Lint exits 0; they block nothing. A new pub fn
there joins the list: judge it, never anchor mechanically.
New ML code lands with tests, and ML correctness is verified against a
reference, not merely asserted to run. The numerics proofs assert against
checked-in PyTorch goldens (regenerate with just reference /
just flow-reference / just gpt2-tiny-reference, which need torch via
uv). Follow RED → GREEN → REFACTOR — see
.claude/rules/development.md and
.claude/rules/testing.md.
- Conventional commits:
type(scope): summary. Scopes track the crates and subsystems:core,cli,api,config,trainer,ci,docs. release-please drives versioning off these, so the format matters. - Keep the README roadmap and the tracking issues (#1–#4, #17–#25) in sync when a milestone lands.
CLAUDE.md— architecture, the load-bearing event/render invariant, config layering, and the full command table.justfile— the source of truth for every recipe.docs/adrs/— the design record (why GPT-2 first, the adapter format, the HTTP API, the Krea 2 direction).docs/api/events.md— the HTTP/SSE wire contract.