# Status

gpu-engine is pre-release. `package.json` is marked `private: true` and the package is not published on npm yet (install from a local tarball built from the repository).

All v1 milestones M0 through M6 are done, and CI requires M1 through M6 (`pnpm milestones --require M1,M2,M3,M4,M5,M6`). Every CLI command (`new`, `loop`, `promote`, `parity`, `inspect`, `doctor`), all four layers (`embed`, `conv`, `biScan`, `dense`), all three heads (`tag`, `pooled`, `retrieve`), level 3 test-set sealing (`promote --seal`) and ship checks are implemented. Nothing in `src/` throws `not implemented:`.

WebGPU limitation: every WebGPU test (`pnpm test:gpu`), `parity` run and the `auto` threshold (`AUTO_WEBGPU_MIN_MACS`) were measured on a software adapter (Mesa llvmpipe through Dawn, the `webgpu` package) in Node on a shared 4-core VM. Real GPU: not run. Real browser: not run.

## `gpu-engine` entry point

Runs in browsers and Node. Nothing reachable from this entry imports a `node:` module.

| Export | Status |
| --- | --- |
| `defineModel` | Implemented. Plans the model and throws `DEFINE_NET_ORDER`, `DEFINE_LAYER_SHAPE`, `DEFINE_HEAD_LABELS`, `DEFINE_FEATURE_ROW` or `DEFINE_BUDGET_EXCEEDED` on invalid definitions. Returns its argument unchanged. |
| `defineEval` | Implemented. Throws `DEFINE_SET_FOLDER` when any set points outside `data/train/`, `data/dev/` or `data/test/`, or when `table` points inside any of those folders. Returns its argument unchanged. |
| `defineDataset` | Implemented. Returns its argument unchanged; the harness reads it during the data step. |
| `features`, `layers`, `int6`, `sealed` | Implemented. Plain-object builders checked when a layout or plan is built. |
| `tokenize` | Implemented. Unicode code-point tokenizer with UTF-16 half-open offsets. |
| `GpuEngineError` | Implemented. Carries `error.diagnostic` (`code`, `message`, `why`, `fix`, optional `file` and `line`). |
| `loadModel`, `availability` | Implemented for `tag`, `pooled` and `retrieve` models on CPU and WebGPU, including `table` encoding and `auto` backend selection. WebGPU is tested on a software adapter (llvmpipe) only. `AUTO_WEBGPU_MIN_MACS` (51,314,688, five-sweep median on llvmpipe) is a placeholder for real devices. |
| Public types | Implemented in `src/types.ts` (including `RetrieveMatch`, `TableRow`, `ModelOutput`) and `DiagnosticCode` in `src/errors.ts`. |

## `gpu-engine/harness` entry point

Node only.

| Export | Status |
| --- | --- |
| `plan` | Implemented. Computes ops, tensor offsets, parameter count, `macsPerToken` and definition hash. |
| `forward` | Implemented for `tag`, `pooled` and `retrieve` (tower output). |
| `encode`, `decode`, `dequantize`, `toWeightsFile` | Implemented. Weights format version 1, with byte-identical `encode(decode(bytes))`. |
| `diagnostics`, `diagnostic`, `engineError`, `formatDiagnostic`, `GpuEngineError` | Implemented. Full diagnostic registry in `src/errors.ts`. |
| `loadProject` | Implemented. Loads the single `*.model.ts` and `*.eval.ts` in a folder, validates both, and parses `eval.table` for `retrieve` heads. |
| `train` | Implemented. Adam with linear warm-up and cosine decay, straight-through int6 QAT, multi-seed runs, wall-clock budget, dev checkpoints, and `retrieve` shared-tower training with `data.table` and `options.negatives`. Performs no file I/O. |
| `runNew` | Implemented. Runs `gpu-engine new <name> --head tag|pooled|retrieve [--dir <path>]` from `templates/`. |
| `runLoop` | Implemented. Runs `gpu-engine loop` including `--log`, `--status`, `--fail`, `--set`, `--mark` and `--dir`. |
| `runPromote` | Implemented for `promote`, `promote --verify` and `promote --seal` (with `--key-out`). |
| `runParity` | Implemented. Runs `gpu-engine parity [--dir <path>]`, compares trainer, CPU and WGSL on dev and four edge fixtures, writes `parity.json` and regenerates `MODEL_CARD.md`. |
| `runInspect` | Implemented. Prints input, tokens, feature rows, weights source, raw logits, head output, decoded result, backend and reason for one input. |
| `runDoctor` | Implemented. Runs all static checks including ship checks (when `dist/` exists) and level 3 checks (when `gate.json` is at level 3). |
| `renderModelCard`, `renderResults` | Implemented. Pure Markdown renderers used by `promote`, `promote --verify`, `parity` and `doctor`. |
| `TrainData`, `SealedDigest` | Exported types for training inputs and test-set digests. |

## By subsystem

| Subsystem | Status |
| --- | --- |
| Featurizer (`tokenize`, `shape`, `hash`, `flag`) | Implemented. Shared between trainer, CPU runtime and WebGPU runtime. |
| Layers (`embed`, `conv`, `biScan`, `dense`) | Implemented: forward, hand-written backward, finite-difference gradient test, CPU and WGSL. See [Layer catalog](https://gpu-engine.dev/docs/reference/layers). |
| `tag` head | Implemented: forward, backward, gradient test, CPU and WGSL. Promoted example: `examples/tag` (unit conversion phrases) with parity on llvmpipe. |
| `pooled` head (class and values forms) | Implemented: forward, backward, gradient test, CPU and WGSL. Promoted example: `examples/pooled` (note kind) with parity on llvmpipe. |
| `retrieve` head | Implemented: shared tower plus dot-product score step, backward, gradient test, CPU and WGSL. Promoted example: `examples/retrieve` (command lookup) with parity on llvmpipe. |
| int6 quantization and QAT | Implemented. Shared per-tensor quantizer for QAT and binary export. |
| Weights format v1 | Implemented. Byte layout matches SPEC section 5. |
| Trainer | Implemented in TypeScript (`train`). Proven on models of a few thousand parameters. |
| CPU runtime | Implemented. Calls `forward` directly (plus `scoreRows` for `retrieve`). |
| WebGPU runtime | Implemented. Runs all ops in one command encoder. Checked in CI (`pnpm test:gpu`) on Dawn over Mesa lavapipe (per-op within 1e-5; whole `tag`, `pooled` and `retrieve` models within 1e-3). Real GPU and real browser: not run. |
| CLI | Implemented. All six commands (`new`, `loop`, `promote`, `parity`, `inspect`, `doctor`) and all documented flags work. See [CLI](https://gpu-engine.dev/docs/reference/cli). |
| Sealed test-set guard (levels 1, 2 and 3) | Implemented. Guarded I/O, level 1 code scan, digests, counted reads in `reads.jsonl`, output muting during test scoring, outgoing text screening, and level 3 AES-256-GCM sealing (`promote --seal`, CI-only decrypt, `checkSeal` in `doctor`). |
| Ship checks (`checkShip`) | Implemented. Runs in `doctor` when `dist/` exists; CI `gate` job builds and verifies every promoted example under `set -euo pipefail`. |
| Scaffold, shipped skill and package docs | Implemented. `gpu-engine new` writes starter packages with `scripts/build.ts`, `AGENTS.md`, `SPEC.md`, `skills/gpu-engine/SKILL.md` and CI workflow. The packed tarball ships `dist`, `docs`, `skills`, `templates`, `llms.txt` and `SPEC.md`. |
| Promoted examples | `examples/tag`, `examples/pooled` and `examples/retrieve` are promoted at level 2 with parity on a software adapter (llvmpipe). Level 3 is not switched on for an in-repo example because it requires a repository secret. |
| Later-version features (SPEC section 6) | Not implemented (no milestone assigned): written or teacher data with provenance, blind second labels, warm start and distillation, and sweeps inside size budgets. |

## Docs site and playground

Per SPEC section 12:

- Every page covering unimplemented later-version behaviour states so in its body and links to this page.
- The [playground](https://gpu-engine.dev/playground) never runs `promote` and never lists, opens, exports or prints anything under `data/test/`.
- Playground examples contain no `data/test/` files.

In the browser, the playground loads the library's type declarations, typechecks the example files and shows TypeScript errors. It does not run `defineModel` or `plan`, does not show layer layouts, cost tables or budgets, and does not train because the examples ship no datasets or generators.

## Milestones

CI runs `pnpm milestones --require M1,M2,M3,M4,M5,M6`.

| Milestone | Scope | Done when | Status |
| --- | --- | --- | --- |
| M0 | Repository skeleton, `SPEC.md`, `AGENTS.md`, public types | CI passes on `main` with check, typecheck, doctor, test and validate | Done |
| M1 | Model kit for `tag` on CPU: featurizer, layers, trainer, QAT, weights format | A `tag` model trains, quantizes, saves, loads and runs on the CPU, and every layer passes its gradient test | Done |
| M2 | Harness: datasets, loop, gate, sealed test set, promote | `loop` runs in under a minute, and tests prove only `promote` reads the test set | Done |
| M3 | WGSL runtime and parity | `parity` passes in CI on Dawn over lavapipe for every layer and fixture | Done |
| M4 | Scaffold, skill and docs | `gpu-engine new` creates a package whose own checks pass, and the npm package contains the skill and `llms.txt` | Done |
| M5 | `pooled` head | A `pooled` example model goes through the whole pipeline to promote and parity | Done |
| M6 | `retrieve` head | A `retrieve` example model goes through the whole pipeline (section 14: one harness covers it) | Done |

## Open questions

From SPEC section 14:

- **Does one harness cover the `retrieve` shape?** Answered yes. It trains through `train`, is scored by `evaluate` and runs through `loadModel` using `eval.table`, `train.negatives` and `loadModel`'s `table` option, with `examples/retrieve` running the full pipeline through `promote` and `parity`. The one retrieve-only path is inside the trainer, where a loss needs a tower pass per candidate row.
- **How far does the TypeScript trainer scale before an external trainer is needed?** Open.
- **Do per-layer WGSL templates stay fast enough, or will fused kernels be needed?** Open.
- **What is the measured CPU-versus-GPU threshold per device class?** Answered for one device class only: on a software adapter (llvmpipe) on a shared 4-core VM, with each cell the median of five sweeps, WebGPU beat the CPU in every cell only from 51,314,688 multiply-adds per run (the largest count measured). WebGPU was faster in 6 cells below it (from 258,048 multiply-adds up) and won 4 of the 6 cells from 3,207,168 up (threshold cell included), while CPU won width 128 at 256 tokens (13,074,432 multiply-adds, 23.9 ms vs 26.9 ms). Earlier single-sweep runs chose 51,314,688, 12,828,672 and 13,074,432. Real GPUs and real browsers: not run, still open.
- **Can real browser parity run in CI rather than only locally?** Open.

Source: SPEC sections 5, 6, 7, 9, 10, 11, 12, 14 and 15, `scripts/milestones.ts`, and `.github/workflows/ci.yml`.

<!-- vitehub-docs:section-links -->
## In this section

- [What is gpu-engine](https://gpu-engine.dev/raw/docs/start.md)
- [Quick start](https://gpu-engine.dev/raw/docs/start/quick-start.md)
- [Rules for agents](https://gpu-engine.dev/raw/docs/start/agents.md)
- [Status](https://gpu-engine.dev/raw/docs/start/status.md) (this page)

All pages: [llms.txt](https://gpu-engine.dev/llms.txt)
