diff --git a/README.md b/README.md index 04feff2..820f166 100644 --- a/README.md +++ b/README.md @@ -162,3 +162,15 @@ See [`docs/TRAINING_FLOW_V2.md`](docs/TRAINING_FLOW_V2.md) for full plan. ## License MIT + +--- + +## Repo boundary + +This is the **model plane** of the IGLA marathon. The control plane (Railway +client, `tri-railway` CLI, `tri-gardener` autonomous orchestrator, +`gardener_runs` ledger) lives in [`gHashTag/trios-railway`](https://github.com/gHashTag/trios-railway). +See [`docs/adr/0001-repo-boundaries.md`](docs/adr/0001-repo-boundaries.md) for +the binding contract. + +`phi^2 + phi^-2 = 3 · TRINITY · NEVER STOP` diff --git a/docs/adr/0001-repo-boundaries.md b/docs/adr/0001-repo-boundaries.md new file mode 100644 index 0000000..6d9d3c4 --- /dev/null +++ b/docs/adr/0001-repo-boundaries.md @@ -0,0 +1,75 @@ +# ADR-0001 — Repo boundaries: `trios-railway` vs `trios-trainer-igla` + +- **Status:** Accepted +- **Date:** 2026-04-28 +- **Authors:** gHashTag (operator), tri-gardener team +- **Anchor:** `phi^2 + phi^-2 = 3 · TRINITY · NEVER STOP` + +## Context + +The IGLA marathon (Gate-2 BPB < 1.85, Gate-3 BPB < 1.5) ships through two +independent repositories. Earlier in the race the boundary between them +was implicit, which led to a near-miss: an operator considered deleting +`trios-trainer-igla` while reasoning about the gardener layout. This +ADR makes the boundary explicit so it survives sleep, shift handoff, and +LLM context loss. + +## Decision + +There are exactly two repositories on the IGLA critical path. Each has +one job. They never depend on each other's source — only on shipped +artefacts (Docker images, GHCR tags, JSONL ledgers). + +### `gHashTag/trios-railway` — control plane + +- Owns the typed Railway GraphQL client (`crates/trios-railway-core`). +- Owns `bin/tri-railway` (operator CLI: `plan9`, `service deploy`, etc.). +- Owns `bin/tri-gardener` (autonomous orchestrator, ASHA rungs, + plateau detector, queue picker, `gardener_runs` ledger). +- Owns the Neon `railway_audit_*` and `gardener_runs` schemas. +- Never contains trainer model code, training scripts, or weights. +- May depend on the **artefact** `ghcr.io/ghashtag/trios-trainer-igla:*` + by tag/digest only. + +### `gHashTag/trios-trainer-igla` — model plane + +- Owns the trainer (`crates/trios-trainer-igla`, attention/JEPA/etc.). +- Owns `Dockerfile` that produces `ghcr.io/ghashtag/trios-trainer-igla`. +- Owns `assertions/seed_results.jsonl` and BPB-emitting code paths. +- Never imports `trios-railway-core` or any control-plane crate. +- May read its own deploy environment variables but does not call + Railway GraphQL itself — that is the control plane's job. + +### Bidirectional contract + +- The trainer image's environment is set by the control plane via + `variableUpsert`. Variable names are part of the contract and + versioned in `docs/contracts/trainer-env.md` (control plane). +- BPB telemetry flows trainer → Neon `bpb_samples` (writer in trainer) + and Neon `bpb_samples` → gardener (reader in control plane). The + schema is owned by the control plane. + +## Consequences + +- The trainer repo is **NEVER** deleted, archived, or renamed as part + of any control-plane refactor. If a control-plane task description + mentions touching the trainer repo for anything other than the + trainer's own code or this ADR, the operator stops and re-asks. +- Control-plane crates do not import trainer code. PRs that try are + rejected. +- Trainer crates do not import `trios-railway-core`. PRs that try are + rejected. +- A change to the trainer image schema (env vars, ports, ledger paths) + requires a paired commit: contract update in `trios-railway` and + the actual change in `trios-trainer-igla`, both referenced in the + PR body. + +## References + +- Tracker: [`gHashTag/trios-railway#43`](https://github.com/gHashTag/trios-railway/issues/43) +- Gardener spec: [`gHashTag/trios-railway#49`](https://github.com/gHashTag/trios-railway/issues/49) +- Gardener PR-1: [`gHashTag/trios-railway#50`](https://github.com/gHashTag/trios-railway/pull/50) +- Race: [`gHashTag/trios#143`](https://github.com/gHashTag/trios/issues/143) +- φ-physics foundation: [`gHashTag/trios#329`](https://github.com/gHashTag/trios/pull/329) + +`phi^2 + phi^-2 = 3 · TRINITY · NEVER STOP`