# Zio Feature Matrix

This is the authoritative implementation-status table for public Zio
documentation. Repository counts are generated in [Project Status](status.md),
and the reproducible AST evaluator measurement is documented in the
[AST Evaluator Baseline](../benchmarks/README.md).

Status meanings:

- **Stable**: covered by the referenced unit or executable-example contract.
- **Experimental**: runnable, but its API and behavior may change.
- **Demo**: loads and runs, but demonstrates a data shape only — the named
  capability is not implemented.
- **Planned**: represented only by a placeholder, example data, specification,
  or roadmap; it is not an implemented capability.

| Area | Status | Evidence |
| --- | --- | --- |
| Reader and syntax expansion | Stable | reader unit tests |
| `eval` primitive (code-as-data evaluation) | Experimental | [`core/src/builtins/macroexpand.rs`](../core/src/builtins/macroexpand.rs) — evaluates in the global environment (CL-style); required by the learner's homoiconic loop |
| AST evaluator and closures | Stable | core evaluator tests |
| Core macros and stdlib | Stable | [`examples/macros.zio` contract](../examples/macros.zio) |
| ZOS classes and generic dispatch subset | Experimental | [`examples/zos-concept.zio` contract](../examples/zos-concept.zio) |
| Persistent collection library | Experimental | [`lib/zio/persistent.zio`](../lib/zio/persistent.zio) — all functions runnable; map iteration order is undefined |
| Datalog storage (create-db, transact) | Experimental | [`lib/zio/datalog.zio`](../lib/zio/datalog.zio) — tx-data must be a list of lists |
| Datalog query evaluator | Planned | `q` is a stub: the query form is accepted but not evaluated (no unification, join, or rules) |
| Protocol system (`defprotocol`/`extend-type`) | Experimental | [`lib/zio/protocol.zio`](../lib/zio/protocol.zio) — dispatches via ZOS generic functions |
| Entity model (`defentity`/`make-entity`) | Experimental | [`lib/zio/entity.zio`](../lib/zio/entity.zio) — ids are process-unique counter strings; globally unique identity awaits a core primitive |
| Agent framework | Demo | [`lib/zio/agent.zio`](../lib/zio/agent.zio) — data model and history run; `step` echoes canned text, no LLM call or tool execution |
| AI host protocols (`zio-ai`: `LlmHost`/`EmbedHost`, `llm-complete`/`embed`) | Experimental | [ADR-016](adrs.md), [`ai/src/lib.rs`](../ai/src/lib.rs) — external attach via `install` (core untouched); no host → stable `capability-denied:` error; mock record/replay with fail-fast replay-miss ([`ai/tests/contract.rs`](../ai/tests/contract.rs)); OpenAI-compatible HTTP behind the `http` feature ([`ai/src/http.rs`](../ai/src/http.rs)) |
| LLM proposer library (`lib/zio/proposer.zio`) | Experimental | [`cli/tests/libs/proposer.zio`](../cli/tests/libs/proposer.zio) contract + [`ai/tests/proposer_contract.rs`](../ai/tests/proposer_contract.rs) — data prompt template, line response protocol, deterministic correction retry, `make-llm-proposer` over `llm-complete`; parse 对拍 with the Rust mirror in `zio_ai::mock::test_support` |
| Concurrent primitives (`future-call`, `chan`) | Experimental — synchronous placeholder | [ADR-012](adrs.md): nothing spawns a thread; `future-call` evaluates eagerly. Real concurrency is a deferred decision |
| Module system (`module`/`export`/`require`, `ns/name`, `:as`, `:refer`) | Experimental | [`cli/tests/modules.rs`](../cli/tests/modules.rs) — exports enforced on refer and qualified access; file modules via cwd or `ZIO_PATH` |
| File I/O through IoHost (`load`/`slurp`/`spit`/`file-exists?`) | Experimental | [ADR-011](adrs.md); `BufferIoHost` offers an in-memory FS for tests/sandboxes |
| WASM build + landing-page REPL | Experimental | [`core/src/wasm.rs`](../core/src/wasm.rs), [`site/src/pages/index.astro`](../site/src/pages/index.astro), [`site/src/lib/engine.ts`](../site/src/lib/engine.ts) |
| ZIR, bytecode VM, and JIT | Planned | [approved VM design](superpowers/specs/2026-08-10-zio-vm-applications-site-design.md) |
| Process capability and pacman updater | Planned | [approved applications design](superpowers/specs/2026-08-10-zio-vm-applications-site-design.md) |
| Numeric kernel and scientific API | Planned | [approved applications design](superpowers/specs/2026-08-10-zio-vm-applications-site-design.md) |
| Pipeline DSL (`pipeline` macro) | Experimental (MVP) | [`lib/zio/pipeline.zio`](../lib/zio/pipeline.zio) — filter/map/aggregate-count/emit stages; expansion errors for unknown stages; compile-time ExpandError semantics remain Planned |
| Homoiconic learner (`learn-function`) | Experimental | [`lib/zio/learn.zio`](../lib/zio/learn.zio) — generation loop over the proposer protocol ([ADR-016](adrs.md)): untrusted proposers emit candidate strings; reader + closed-world whitelist gates, canonical dedup, eval budget (`:max-generations`/`:max-evals`) and per-candidate error isolation live in the loop; enumerator demoted to `make-enum-proposer`, `make-llm-proposer`/`make-hybrid-proposer` in [`lib/zio/proposer.zio`](../lib/zio/proposer.zio); contracts in [`cli/tests/libs/learn.zio`](../cli/tests/libs/learn.zio) + [`ai/tests/learn3_contract.rs`](../ai/tests/learn3_contract.rs). Seeded search, compile cache, fuel-budgeted sub-VM remain Planned |
| grove P1: evidence, model identity, feedback lifecycle, teacher protocol | Experimental | [grove design](self-learning-architecture.md), [delivery plan](superpowers/plans/2026-10-02-self-learning.md) W00–W03. `learning/` = the `grove` host crate: versioned records + stable error classes ([`learning/src/contracts.rs`](../learning/src/contracts.rs)), content-addressed artifacts with digest verification and temp-then-commit writes ([`learning/src/artifacts.rs`](../learning/src/artifacts.rs)), SQLite transactions with role-gated writes, idempotent signal receipts and optimistic head/publication versions ([`learning/src/store.rs`](../learning/src/store.rs)); contracts in [`learning/tests/store_contract.rs`](../learning/tests/store_contract.rs) (22) and [`learning/tests/feedback_contract.rs`](../learning/tests/feedback_contract.rs) (12). Feedback policy is pure Zio ([`lib/zio/learn/feedback.zio`](../lib/zio/learn/feedback.zio)): field-scoped precedence, human-over-teacher, conflict isolation, abstain as a first-class value, frozen dataset revisions. Teacher protocol in [`ai/src/teacher.rs`](../ai/src/teacher.rs) with capability declaration, soft-output vocabulary alignment, license checks and proposal-typed programs; HTTP adapter + 16 contracts in [`ai/tests/teacher_contract.rs`](../ai/tests/teacher_contract.rs) |
| grove acceptance task (geometry image + sensor XOR) | Experimental | [`examples/self-learning/generate.py`](../examples/self-learning/generate.py) — grouped splits (0 leakage), missing-modality abstain contract, holdout container stores no label byte; `python examples/self-learning/generate.py --self-check`; frozen gates in [`examples/self-learning/task.json`](../examples/self-learning/task.json) and [`examples/self-learning/protocol.json`](../examples/self-learning/protocol.json) |
| grove local teacher (torch CPU reference) | Experimental | [`workers/torch/train.py`](../workers/torch/train.py) real backprop on CPU (loss 0.696 → 0.0003, val accuracy 1.000 on the frozen W00 split), served by [`workers/torch/teacher.py`](../workers/torch/teacher.py) and queried through the Rust teacher host in [`learning/tests/teacher_local.rs`](../learning/tests/teacher_local.rs) |
| grove W04: torch worker + isolated execution | Experimental | permitted operator graph, structurally validated before any tensor runs ([`workers/torch/graph.py`](../workers/torch/graph.py)); versioned NDJSON control protocol with frame caps ([`workers/torch/worker.py`](../workers/torch/worker.py)); host spawns the worker inside user/network/pid/mount namespaces via `unshare -Urn` with rlimits and process-group kill, and **fails closed** when namespaces are unavailable ([`learning/src/worker.rs`](../learning/src/worker.rs)); 10 host contracts in [`learning/tests/worker_contract.rs`](../learning/tests/worker_contract.rs) (network probe reachable outside / blocked inside; timeout reaps the tree; trained weights load in a separate process) + 13 worker protocol tests in [`workers/torch/tests/test_worker.py`](../workers/torch/tests/test_worker.py) |
| grove W05: joint code/weight learning driver | Experimental | the model description is Zio data and structural candidates are rewrites of it ([`lib/zio/learn/model.zio`](../lib/zio/learn/model.zio)); recipes declare consumable signals, budgets and init policy ([`lib/zio/learn/recipes.zio`](../lib/zio/learn/recipes.zio)); on the frozen W00 task the linear baseline stays at 0.531 val accuracy while the nonlinear rewrite reaches 1.000 (+46.9pp lift over the frozen +15pp gate) — measured by [`learning/tests/dual_learning_contract.rs`](../learning/tests/dual_learning_contract.rs) (9 contracts incl. fork reinitialization, per-candidate failure isolation, budget ledger) |
| grove W06: checkpoints, pause, resume, fork | Experimental | worker state artifacts are non-executing JSON (params + Adam moments + CPU RNG base64), written atomically (temp + fsync + rename) at a declared step ([`workers/torch/worker.py`](../workers/torch/worker.py)); the host vets the state manifest (schema, protocol, run lineage — foreign-run state is refused) before the checkpoint row exists, resumes into a *new* run with an inherited ledger (`LearningContinuation`) or a declared-fresh one, gates `ControlledReplay` on a declared deterministic host, marks `Paused` only after a successful save, and forks branches that point at the parent without touching it ([`learning/src/checkpoint.rs`](../learning/src/checkpoint.rs)); the decisive contract: a run killed at step 300 and resumed in a new process reaches byte-identical parameters vs 600 uninterrupted steps ([`learning/tests/checkpoint_contract.rs`](../learning/tests/checkpoint_contract.rs), 10) |
| grove W07: historical re-evaluation + publication gates | Experimental | versioned `EvaluationProtocol` (seeds, gates, timeout policy, device); re-evaluation appends records and never rewrites history, cross-protocol mixing is refused (a model that passed an easier protocol cannot publish against a stricter one), timeouts/crashes stay in the denominator at zero quality, non-finite metrics are refused at the boundary, hard gates precede publication regardless of mean quality, publication is an expected-version-checked flip ([`learning/src/evaluation.rs`](../learning/src/evaluation.rs)); quality/cost non-dominated selection; shared acceptance budget that forks cannot multiply ([`learning/src/store.rs`](../learning/src/store.rs) `acceptance_budget`); 11 contracts in [`learning/tests/evaluation_contract.rs`](../learning/tests/evaluation_contract.rs) |
| grove W08: `grove` CLI + local end-to-end | Experimental | new `grove-app` crate, binary `grove` (`app/src/main.rs` + `app/src/lib.rs`): demo/inspect/checkpoint/fork/resume/compare/select/publish map onto library contracts; the CLI **loads provisioned protocols instead of rebuilding them** (a flag dropping frozen gates cannot publish — caught by the e2e); `demo --case dual` runs the real flow on the frozen W00 task: baseline 0.539 → nonlinear candidate through an actual pause/resume (state committed at step 150, run paused, new run ledger 150+150) → 0.996, +45.7pp, published v1; the underfit baseline is refused with its gate failure named ([`app/tests/learning_e2e.rs`](../app/tests/learning_e2e.rs), 6) |
| grove W09: multi-worker population coordination | Experimental | one coordinator owns the ledger, branch heads and execution slots: attempts hold **leases** (an expired or cancelled attempt cannot overwrite newer progress), commits carry the attempt id AND the branch's expected head version, billing is idempotent by message id, and an unknown external outcome stays on the books as unknown rather than assumed exactly-once ([`learning/src/coordinator.rs`](../learning/src/coordinator.rs)); allocation policy is pure Zio (baseline + accuracy leader + diversity quota under one shared grant; safe-point pausing) ([`lib/zio/learn/population.zio`](../lib/zio/learn/population.zio)); **parallelism is measured, not asserted**: [`learning/tests/population_contract.rs`](../learning/tests/population_contract.rs) proves two workers' execution windows intersect (>500ms observed), a branch killed at its checkpoint leaves the other running and resumable, forks draw from one ledger; `grove demo --case population --workers 2` reproduces it with two isolated worker processes |
| grove W10: product API + authorized publication | Experimental | optional `http` feature (the library and CLI never need a network stack): same-origin JSON API over the library contracts ([`app/src/api.rs`](../app/src/api.rs)) — observe/predict-signal/train/fork/publish/compare/events; **one bearer token = one role**, enforced on every mutating call (reader cannot annotate, annotator cannot train, operator cannot publish) and localhost is not a pass; mutations are idempotent by operation id (a replay returns the *first* response, status code included) and publication carries an expected-version check; a non-loopback bind without tokens is refused. `grove serve --root PATH --bind HOST:PORT` ([`app/tests/api_contract.rs`](../app/tests/api_contract.rs), 6) |
| grove W11: product interface | Experimental | same-origin web UI served from the product's own origin — no CORS grant to operate a control surface ([`app/web/index.html`](../app/web/index.html), [`app.js`](../app/web/app.js), [`styles.css`](../app/web/styles.css), served by [`app/src/api.rs`](../app/src/api.rs)). The page shows, as *separate* facts, what a correction is bound to (the exact prediction and its snapshot) and whether anything has learned from it yet; a lineage view that marks a checkpoint **not recoverable** when its state artifact is gone rather than hiding it; module and expert contracts with their semantic spaces and permission requirements; a confirm-gated publish. Real inference runs through the same isolated torch worker the trainer uses ([`app/src/inference.rs`](../app/src/inference.rs)) on a GVD1 container the product writes itself ([`app/src/container.rs`](../app/src/container.rs)) — an observation with a short pixel list is refused, never padded. Keyboard-operable, labelled forms, text status alongside colour ([`app/tests/ui_contract.rs`](../app/tests/ui_contract.rs), 5) |
| grove W12: retraction, retention, recovery | Experimental | reachability analysis from the roots that must survive (active publication, branch heads, non-terminal runs, frozen revisions) decides what may be deleted; retention is a declared policy (store meta `retention.horizon_ms`), and **no declared horizon deletes nothing** — an undeclared policy is not a licence to destroy history ([`learning/src/store.rs`](../learning/src/store.rs), [`learning/src/artifacts.rs`](../learning/src/artifacts.rs)). Retracting a signal propagates through frozen views → runs → checkpoints → snapshots and marks them non-deployable, so publication and resume are both refused while the frozen revision keeps its members. A deleted or byte-corrupted state artifact returns `artifact-unavailable`; a restart reclaims expired leases and re-takes coordinator ownership, so a dead worker's receipt cannot commit ([`learning/src/coordinator.rs`](../learning/src/coordinator.rs)); 10 contracts in [`learning/tests/lifecycle_contract.rs`](../learning/tests/lifecycle_contract.rs) (GC deleted 4 unreachable objects and refused 4 reachable ones under a 7-day vs 0 horizon) |
| grove W13: module branching, composition, joint fine-tuning | Experimental | a module binds the semantic space it consumes and the one it emits, and the composition check is **semantic, not numeric** — equal width is not equal meaning ([`learning/src/composition.rs`](../learning/src/composition.rs)). A shared parameter group is one evolution unit and may not be restored as two conflicting versions; the permission closure is a maximum, so composing can require more than its parts but never less; composition writes a NEW snapshot with multi-parent lineage and leaves both parents byte-identical ([`learning/src/lineage.rs`](../learning/src/lineage.rs)). A joint plan always evaluates the whole composite — a submodule's local score can never promote it. `demo --case modular` evolves the fusion and head modules apart, has the mismatched-space composition refused with its reason, trains the composite to 1.000 on the frozen task and publishes *that*; the modules themselves report `n/a` because they are not classifiers, and a composition that regresses is reported as a regression ([`learning/tests/composition_contract.rs`](../learning/tests/composition_contract.rs), 9) |
| grove W14: three-index experience, abstraction, reuse | Experimental | structural, behavioural and semantic indexes over the *existing* signal/observation/prediction records — no second fact store ([`learning/src/memory.rs`](../learning/src/memory.rs)); behavioural fingerprints carry a named probe set and are never compared across sets; semantic vectors carry an encoder id and a **space version**, and a query at a different version is refused without an explicit migration. Four refusals are enforced and tested: a semantic near-neighbour never merges into a different AST, probe sets never mix, retrieval never crosses a licence, and a capability derived from a retracted source refuses to load. Abstraction promotion is gated on original-task regression AND a new-task evaluation ([`lib/zio/memory.zio`](../lib/zio/memory.zio), [`lib/zio/vector.zio`](../lib/zio/vector.zio)); 12 contracts in [`learning/tests/memory_contract.rs`](../learning/tests/memory_contract.rs) plus 28 + 23 library markers in [`cli/tests/libs/memory.zio`](../cli/tests/libs/memory.zio) and [`vector.zio`](../cli/tests/libs/vector.zio). **Measured result is negative and reported as such**: on a task that did not participate in discovery, total description length (calls + definition) went 18 → 22 (one call → two calls) against 18 → 18 for the original; the abstraction is behaviourally correct but does not pay for itself at a 3-leaf program size |
| grove W15: extended recipes | Experimental | soft distillation, pairwise preference, demonstration cloning inside a declared legal action set, self-supervised representation learning, delayed environment feedback, and a restricted discrete policy-gradient recipe with an explicit action/reward/termination contract ([`workers/torch/recipes.py`](../workers/torch/recipes.py), [`lib/zio/learn/recipes.zio`](../lib/zio/learn/recipes.zio)); the host enforces the declaration rather than trusting it — an undeclared signal kind, an over-cap budget and an unknown recipe are refused ([`learning/src/recipes.rs`](../learning/src/recipes.rs)). Measured, not asserted: soft-distill val KL 0.6918 → 0.1264 at T=1 (and temperature demonstrably changes the objective); preference held-out ranking 0.5469 → 0.9531 with abstentions proven not to enter the objective (identical loss with and without 12 abstaining pairs); demonstration 0.9297, degrading to 0.8932 with 25% illegal actions *masked* rather than trained; self-supervised moves the representation (cosine 0.7700) while the **task** metric is reported separately at 0.5117 and still fails its gate; delayed results settle 64/64 and an unsettled run produces a parameter delta of exactly 0.0; policy gradient return −1.0000 → 0.7500 ([`workers/torch/tests/test_recipes.py`](../workers/torch/tests/test_recipes.py), 51; [`learning/tests/recipe_contract.rs`](../learning/tests/recipe_contract.rs), 15). No external vendor soft outputs are integrated: only hard distillation is exercised against a local teacher |
| grove W16: expert routing, output combination, multi-teacher distillation | Experimental | router, expert snapshot versions, output space, combination rule and per-call budget are bound into one `ModelSnapshot` identity ([`learning/src/ensemble.rs`](../learning/src/ensemble.rs)). Experts in different output spaces are refused at bind time, never averaged; **no available expert means abstain**, a vote tie has no honest winner, and `all-agree` with a missing expert abstains because unanimity cannot be established; an unavailable expert is *named* and its cost still billed, so coverage is a real number. One call is charged for every expert it used. Population agreement is a distillation **target with an agreement level**, never a verified label — a unanimous-but-wrong population still faces task acceptance ([`learning/tests/ensemble_contract.rs`](../learning/tests/ensemble_contract.rs), 12; the rule contrast is demonstrated in `demo --case modular`) |
| Concurrency model decision | Adopted (ADR-014) | threads bind to the VM phase; AST interpreter stays single-threaded; `Value` !Send is verified |
| Memory model (Arc cycles) | Known, anchored (ADR-015) | self-referential closures leak by design until the VM-phase GC decision |
| Landing site | Stable | Astro static build: [`site/src/pages/index.astro`](../site/src/pages/index.astro) (landing), [`site/src/pages/agent/index.astro`](../site/src/pages/agent/index.astro) (Agent & LLM), [`site/content/grove/index.mdx`](../site/content/grove/index.mdx) (grove subpage, external MDX via content collection); wasm engine committed at `site/public/wasm`, rebuilt with `tools/build-wasm.sh` |
| grove subpage on the landing site | Experimental | [`site/content/grove/index.mdx`](../site/content/grove/index.mdx) — static exposition of the grove design and measured demo numbers; it is **not** the product surface (`app/web/`, served by `grove serve`) and runs no learning itself |

The stable reader row does not include set literals: `#{...}` remains planned
and must not be used in runnable examples.