v0.3.0-beta.1 — public mind_train surface (bring-up trainer)

v0.3.0-beta.1 — public mind_train surface (bring-up trainer)

Opens the v0.3 line per the locked ship plan. The trainer that
produced the Phase 1 checkpoints is now a first-class Python module
with a typed contract.

New module: mind_nerve.mind_train

from pathlib import Path
from mind_nerve.mind_train import TrainConfig, train

result = train(TrainConfig(
    catalog_path=Path("corpus.tsv"),
    output_dir=Path("./run"),
    epochs=3,
    backend="python",      # 'native' lands with mindc 0.3.0
    smoke_test=False,
))
print(result.model_hash, result.metrics)

Frozen TrainConfig + TrainResult dataclasses, deterministic
checkpoint hashing (SHA-256 over the sorted file tree, paths bound
in), backend dispatch.

New CLI: mind-nerve train

mind-nerve train \
  --catalog corpus.tsv \
  --out ./run \
  --backend python \
  --epochs 3 \
  --smoke-test   # 500 pairs / 1 epoch / ~1 min to validate the pipeline

Backend resolution

• python (default) — PyTorch + sentence-transformers MNR-loss
  recipe ported from catalog-builder/train_phase1.py. Works today;
  this is the bring-up backend.
• native — Raises NotImplementedError until the mindc 0.3.0
  --emit-shared cdylib + Q16.16 native kernel land. Foundation
  already shipped in mindc 0.2.11 (--emit-shared flag).

When the native backend ships, the Python backend stays available
behind the same switch — for reproducibility and cross-backend
bit-identity comparison.

Tests

tests/integration/test_mind_train_contract.py covers 9 invariants:
frozen dataclasses, malformed-row tolerance in the parser,
deterministic seeded split, checkpoint hash determinism + path-binding,
backend resolution errors, JSON-safe config, fast-fail on missing
catalog. Full suite: 195 passed.

Roadmap

• v0.3.0 — Native backend swap (gated on mindc 0.3.0 cdylib emit).
• v0.9.0-rc.1 — Switch flip wave (per-head drop masks, L2-cosine,
  RMSNorm, ALiBi) — each behind a model_hash bump using the new
  train() entry.
• v1.0.0 — Native cdylib inference path, cross-arch bit-identity,
  Tier-1 multilingual coverage cleared, Phase 3 functional.

What mind-train does NOT yet do (deferred)

• Multilingual corpus orchestration (Tier-1 12 languages) — runs in
  the multilingual workstream against this TrainConfig surface.
• Resume-from-checkpoint — single-pass for now.
• Multi-host distributed training — single-process bring-up.