Model Engine with restore KV

.gitignore

@@ -2,3 +2,12 @@
 .core/
 .idea/
 .vscode/
+# build / test artefacts
+*.test
+*.out
+.DS_Store
+*.bak
+go.work.sum
+/build/
+*.air
+cmd/lem/*.metallib.gz

.gitmodules

@@ -2,3 +2,78 @@
 	path = external/go
 	url = https://github.com/dappcore/go.git
 	branch = dev
+[submodule "external/go-i18n"]
+	path = external/go-i18n
+	url = https://github.com/dappcore/go-i18n.git
+	branch = dev
+[submodule "external/go-io"]
+	path = external/go-io
+	url = https://github.com/dappcore/go-io.git
+	branch = dev
+[submodule "external/go-rag"]
+	path = external/go-rag
+	url = https://github.com/dappcore/go-rag.git
+	branch = dev
+[submodule "external/go-ratelimit"]
+	path = external/go-ratelimit
+	url = https://github.com/dappcore/go-ratelimit.git
+	branch = dev
+[submodule "external/api"]
+	path = external/api
+	url = https://github.com/dappcore/api.git
+	branch = dev
+[submodule "external/go-store"]
+	path = external/go-store
+	url = https://github.com/dappcore/go-store.git
+	branch = dev
+[submodule "external/mcp"]
+	path = external/mcp
+	url = https://github.com/dappcore/mcp.git
+	branch = dev
+[submodule "external/go-ws"]
+	path = external/go-ws
+	url = https://github.com/dappcore/go-ws.git
+	branch = dev
+[submodule "external/go-process"]
+	path = external/go-process
+	url = https://github.com/dappcore/go-process.git
+	branch = dev
+[submodule "external/go-log"]
+	path = external/go-log
+	url = https://github.com/dappcore/go-log.git
+	branch = dev
+[submodule "external/go-proxy"]
+	path = external/go-proxy
+	url = https://github.com/dappcore/go-proxy.git
+	branch = dev
+[submodule "external/go-scm"]
+	path = external/go-scm
+	url = https://github.com/dappcore/go-scm.git
+	branch = dev
+[submodule "external/mlx"]
+	path = external/mlx
+	url = https://github.com/ml-explore/mlx.git
+[submodule "external/go-container"]
+	path = external/go-container
+	url = https://github.com/dappcore/go-container.git
+	branch = dev
+[submodule "external/gui"]
+	path = external/gui
+	url = https://github.com/dappcore/gui.git
+	branch = dev
+[submodule "external/cli"]
+	path = external/cli
+	url = https://github.com/dappcore/cli.git
+	branch = dev
+[submodule "external/rocm-hip"]
+	path = external/rocm-hip
+	url = https://github.com/ROCm/HIP.git
+	branch = release/rocm-rel-7.2
+[submodule "external/rocm-clr"]
+	path = external/rocm-clr
+	url = https://github.com/ROCm/clr.git
+	branch = release/rocm-rel-7.2
+[submodule "external/rocr-runtime"]
+	path = external/rocr-runtime
+	url = https://github.com/ROCm/ROCR-Runtime.git
+	branch = release/rocm-rel-7.2

AGENTS.md

@@ -39,17 +39,73 @@ assert behavior directly against the symbol named by the test. A triplet named
 `TestOptions_WithMaxTokens_Bad` must invoke `WithMaxTokens` in its own body,
 not route through a dispatcher helper.
 
+## Writing Tests, Examples & Benchmarks
+
+Every source file ships three siblings — extend them, never create monolithic
+compliance files, versioned test files (`_v2`), or `ax7*` files:
+
+| Sibling of `foo.go` | Holds | Verified by |
+|---------------------|-------|-------------|
+| `foo_test.go` | one `Test<Symbol>_<Case>` per exported symbol per variant | `task test` |
+| `foo_example_test.go` | one `Example<Symbol>` per symbol, with an `// Output:` block | `task test` (runs + diffs the output) |
+| `foo_bench_test.go` | one `Benchmark<Symbol>` per hot symbol | `task bench` |
+
+**Tests — name the symbol, exercise it directly.** A test asserts against the
+symbol its name claims: `TestOptions_WithMaxTokens_Bad` must call
+`WithMaxTokens` in its own body, not route through a dispatcher/table helper.
+A test that never names its symbol is fake coverage the audit flags. Write the
+AX-7 triplet for each symbol — `_Good` (valid input, happy path), `_Bad`
+(invalid input is rejected), `_Ugly` (malformed / boundary / empty). Production
+functions that can fail return `core.Result`: the `_Good` test asserts `r.OK`
+then reads `r.Value`; the `_Bad`/`_Ugly` tests assert `!r.OK`.
+
+**Examples are compiled documentation.** `func ExampleWithMaxTokens()` ends with
+a `// Output:` block so `go test` runs and diffs it — a stale example fails the
+build. Print with `Println` from `dappco.re/go`, never `fmt.Println`.
+
+**Benchmarks measure the load path.** Shape:
+
+```go
+var sinkResult core.Result // package sink — stops the compiler eliding the call
+
+func BenchmarkDiscover(b *testing.B) {
+    dir := writeFixtureModel(b)     // setup OUTSIDE the timed loop
+    b.ReportAllocs()
+    b.ResetTimer()                  // discount the setup
+    for i := 0; i < b.N; i++ {
+        sinkResult = Discover(dir)  // assign to the sink so it can't be optimised away
+    }
+}
+```
+
+Read **B/op as hard as allocs/op** — the biggest wins (whole-slice clones,
+full-file reads) leave allocs/op flat while B/op screams. allocs/op is only
+trustworthy at steady state, so `task bench` runs `-benchtime=20x`; a cold
+3-iteration number is inflated by setup.
+
 ## Working Locally
 
-Use the same commands as the compliance brief before handing work back:
+Run the Taskfile gates before handing work back (portable lanes need no GPU;
+`*:metal` lanes need `task metallib` first):
+
+```sh
+task qa            # gofmt check + go vet + portable tests — the pre-handback gate
+task test          # portable suite (default tags, runs anywhere)
+task test:metal    # engine/metal suite (-tags metal_runtime; needs task metallib)
+task cover         # coverage.out + total — must clear the 95% codecov target
+task bench         # every benchmark with -benchmem (allocation regressions)
+```
+
+`codecov.yml` enforces **95%** on both the project and each patch, measured on
+the portable `task cover` profile (the surface a Linux CI compiles; engine/metal
+is Darwin-only and covered by `task test:metal`).
+
+For core/go idiom compliance specifically, the audit script is the work
+provider — a change is not complete until it reports `verdict: COMPLIANT` with
+every counter at zero:
 
 ```sh
 GOWORK=off go mod tidy
-GOWORK=off go vet ./...
-GOWORK=off go test -count=1 ./...
 gofmt -l .
 bash /Users/snider/Code/core/go/tests/cli/v090-upgrade/audit.sh .
 ```
-
-The audit script is the work provider for compliance tasks. A change is not
-complete until it reports `verdict: COMPLIANT` with every counter at zero.