Model Engine with restore KV

.github/workflows/build.yml

@@ -0,0 +1,122 @@
+# Build the sovereign `lem` binary for every target and ship the zips.
+# One binary named `lem` per platform (the GPU backend — metal/rocm/cuda — loads
+# its kernel sidecar at runtime); targets are separated by build folder, not by
+# binary name. Zips flow to a rolling `dev` prerelease.
+name: Build
+
+on:
+  push:
+    branches: [dev, main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: lem · ${{ matrix.goos }}/${{ matrix.goarch }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: macos-latest,     goos: darwin,  goarch: arm64, metal: true }
+          - { os: ubuntu-latest,    goos: linux,   goarch: amd64 }
+          - { os: ubuntu-24.04-arm, goos: linux,   goarch: arm64 }
+          - { os: windows-latest,   goos: windows, goarch: amd64 }
+    env:
+      CGO_ENABLED: "1"
+      GOWORK: "off"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive          # metal needs external/mlx
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.26"
+
+      - name: Install Task
+        run: go install github.com/go-task/task/v3/cmd/task@latest
+
+      - name: Build lem
+        shell: bash
+        env:
+          METAL: ${{ matrix.metal }}
+        run: |
+          set -e
+          if [ "$METAL" = "true" ]; then
+            task metallib && task build:embed     # self-contained metal lem
+          else
+            task build:native                     # plain lem (GPU sidecar loads at runtime)
+          fi
+
+      - name: Assemble build folder (build/dist/<target>/lem)
+        shell: bash
+        env:
+          TARGET: ${{ matrix.goos }}-${{ matrix.goarch }}
+        run: |
+          set -e
+          mkdir -p "build/dist/$TARGET"
+          cp bin/lem* "build/dist/$TARGET/"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: lem-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: build/dist/${{ matrix.goos }}-${{ matrix.goarch }}/
+
+  release:
+    name: Zip + rolling dev prerelease
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist        # one subfolder per target (lem-<goos>-<goarch>/lem)
+
+      - name: Zip each target
+        run: |
+          set -e
+          cd dist
+          for d in */; do (cd "$d" && zip -r "../${d%/}.zip" .); done
+          ls -la *.zip
+
+      - name: Publish rolling dev prerelease
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: dev
+          name: dev (rolling)
+          prerelease: true
+          files: dist/*.zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  sdk:
+    name: SDK clients (OpenAPI)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.26"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - uses: actions/setup-java@v4       # openapi-generator runs on the JVM
+        with:
+          distribution: temurin
+          java-version: "21"
+      - name: Install generators
+        run: |
+          npm install -g @openapitools/openapi-generator-cli@7.22.0
+          go install github.com/go-task/task/v3/cmd/task@latest
+      - name: Generate SDKs (lem spec -> OpenAPI 3.1 -> typed clients)
+        run: task sdk
+      - uses: actions/upload-artifact@v4
+        with:
+          name: lem-sdks
+          path: build/sdk/
+          if-no-files-found: warn

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+# Portable CI for go-inference — the default-tag (no-GPU) test + coverage lane.
+# go-inference is a Metal/CGO project; the FULL lem build (engine/metal, the
+# metallibs) needs macOS 26 / Metal 4 and lives in build.yml on a self-hosted
+# runner. This lane runs the portable suite (Taskfile `test`/`cover`) on any OS.
+name: CI
+
+on:
+  push:
+    branches: [dev, main]
+  pull_request:
+    branches: [dev, main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Portable test + coverage
+    runs-on: ubuntu-latest
+    env:
+      GOWORK: "off"          # resolve deps from go/go.mod tags, not the workspace
+      CGO_ENABLED: "1"       # go/ links duckdb (go-duckdb/v2 ships prebuilt linux libs)
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.26"
+
+      - name: Portable tests + coverage (default tags — engine/metal excluded)
+        working-directory: go
+        run: go test -count=1 -covermode=atomic -coverprofile=coverage.out ./...
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: go/coverage.out
+          flags: portable
+          fail_ci_if_error: false

.github/workflows/deps.yml

@@ -0,0 +1,46 @@
+# Dependency-bump issue tracker — Core ecosystem Go repos.
+# Copy to .github/workflows/deps.yml in each repo.
+#
+# Opens/updates a single 'deps'-labelled issue listing dappco.re/* dependencies
+# that have a newer published release (and closes it when all are current). Open
+# 'deps' issues across every repo then ARE the ecosystem's version-bump work
+# queue — filter by the label to see exactly what's outstanding.
+#
+# Triggers:
+#   - schedule            → daily safety-net poll
+#   - workflow_dispatch   → run on demand (set dry-run to preview the issue body)
+#   - repository_dispatch → an upstream release can ping {"event_type":"dep-bump"}
+name: Deps
+
+on:
+  schedule:
+    - cron: "0 7 * * *"
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: "Preview the issue body without touching issues"
+        type: boolean
+        default: false
+  repository_dispatch:
+    types: [dep-bump]
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  deps:
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      # go-inference is dev-canonical (main is the stale release branch), so the
+      # tracker scans dev's go.mod even when dispatched/scheduled from main.
+      - uses: actions/checkout@v4
+        with:
+          ref: dev
+
+      - uses: dAppCore/build/actions/deps@dev
+        with:
+          go-mod-dir: go
+          dry-run: ${{ github.event.inputs.dry-run || 'false' }}

.gitignore

@@ -2,3 +2,15 @@
 .core/
 .idea/
 .vscode/
+# build / test artefacts
+*.test
+*.out
+.DS_Store
+*.bak
+go.work.sum
+/build/
+*.air
+cmd/lem/*.metallib.gz
+
+# compiled lem binary (build artefact — built via Taskfile/go build)
+go/lem

.gitmodules

@@ -1,4 +1,15 @@
-[submodule "external/go"]
-	path = external/go
-	url = https://github.com/dappcore/go.git
-	branch = dev
+[submodule "external/mlx"]
+	path = external/mlx
+	url = https://github.com/ml-explore/mlx.git
+[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.