Emery Adapters

First-party source and target Wasm components for Emery.

Using Emery in a project? You do not need this repository. Install adapters with a pin from the engine CLI — for example emery init contracts@0.5.0 — and follow the Emery README.

Authoring or debugging an adapter? This repo is your home. Edit prose or Rust, then re-run a live eval case until it passes.

The pin you pass to emery (contracts@0.5.0) is this workspace’s shared SemVer ([workspace.package].version). Operators consume published GHCR artifacts; authors iterate here natively without a Wasm rebuild for prose changes.

Choose your path

I want to…	Go to
Fix or tune adapter prompts / references	Quick start → Repair loop
Fix Rust adapter logic	Rust-only loop · docs/testing.md
Create a new adapter (source or target)	docs/authoring.md
Set up the toolchain, publish, or bump the engine pin	CONTRIBUTING.md
Use Emery as an operator	Emery README — leave this repo

The root Makefile forwards goals to cargo-make; docs use cargo make … so flags like --restart are not eaten by GNU Make.

What an adapter is

An adapter is one Rust crate that ships as one Wasm component. The engine calls its operations; you never hand-edit lifecycle or plan.yaml from adapter code.

Role	Operations	Examples
Source	survey, extract	intent, documentation, typescript, screenshots, captures
Target	guidance, build, merge	contracts, omnia, vectis

How adapters show up for operators: pinned package (contracts@0.5.0 / emery:contracts@0.5.0) pulls from GHCR on first use; bare names resolve only a project component cache seeded by emery adapter add or a local .wasm at init. Details: Emery adapter install notes and CONTRIBUTING.md § Publishing.

Rust-only loop

Native crate tests do not need cursor-agent or model credentials:

cargo make check
cargo nextest run -p contracts    # or any adapter crate name

Use this path for Rust logic, validators, and deterministic behavior. Live eval (below) is for prompt quality.

Prerequisites (live eval)

Needed only for cargo make eval …:

1. Authenticated cursor-agent on PATH — cursor-agent login, or CURSOR_API_KEY in a repo-root .env (the eval task loads it).
2. Optional: CURSOR_MODEL=<model-id>, CURSOR_TIMEOUT_SECS=<secs> (unset → Cursor backend default of 600s).

If eval hangs or fails authenticating, check cursor-agent login / .env — see CONTRIBUTING.md § Troubleshooting. Grading is deterministic (not a model): the eval binary links every first-party adapter into a native catalog and drives production verbs through the shared cursor backend.

Quick start

From the repository root, run one build case (~2–5 minutes; needs cursor auth):

cargo make eval contracts-design --restart

A passing run prints the retained sandbox and the authoritative report path — .emery/slices/returns-api/contracts/ in that sandbox carries the generated contract delta. A success report that wrote nothing still fails the case's expect gate.

To start developing, edit the contracts adapter’s prompts or references under targets/contracts/prose/, then run the same command again and compare the sandbox with the previous run (--restart replaces it). Native runs pick up prose changes automatically — no Wasm build is required.

cargo make eval    # list the cases

Target	Smoke case
contracts	cargo make eval contracts-design --restart
omnia	cargo make eval omnia-health --restart
vectis	cargo make eval vectis-single-screen --restart
vectis (open-GAP)	cargo make eval vectis-open-gap-fab --restart — pass criteria

Build vs workflow cases

Prefer a build case when iterating on one target adapter's build (minutes). Use a workflow case only when you need plan → execute → finalize or real source trees (tens of minutes). Catalog: examples/eval/README.md.

	Build case	Workflow case
Command	cargo make eval <id> --restart	cargo make eval <id> --restart [--until plan]
Fixture	committed refined slice	source trees + intent, plan authored live
Gates	built metadata, build/report.yaml, expect paths	authored plan awaiting review, drained plan, provenance

Omnia has a stock migration workflow case; the UNLICENSED Propellerhead upstream is shallow-cloned into the case's gitignored fixture/ cache on first run and reused offline after that:

cargo make eval omnia-r9k --restart      # typescript at_r9k_position_adapter → omnia

Depth: eval README § Omnia legacy migration.

After a run

Every case keeps one stable sandbox at sandbox/<id>/ (beside the wasm examples' sandbox/wasm-*/ trees), on success and failure alike:

sandbox/<id>/
  plan.yaml / change.md / discovery.md   # workflow cases
  .emery/slices/<slice>/               # proposal, specs, design, tasks, evidence
  .emery/slices/<slice>/build/report.yaml   # the authoritative build report
  …target outputs (contracts, crates/, shells, …)

Grading checks lifecycle, the report, expect paths, and (workflow) provenance; target quality is still a human look — see eval README § Grading. Per-leg repair counts are reported, not asserted; drift toward the repair budget is an early signal that prose or answer-schema changes degraded the first answer.

An existing sandbox refuses to rerun without --restart. Continue or debug it explicitly through the native verbs instead:

cargo make lab -- --project-dir sandbox/orders-contracts plan execute

Repair loop

1. Edit {targets,sources}/<name>/prose/** (prompts, references, rules). Cases load prose from the linked crates — no Wasm rebuild.
2. Re-run the same case (e.g. cargo make eval contracts-design --restart).
3. Compare the sandbox tree and report to the previous run.
4. Repeat until the case passes and the artifacts look right.

Do not burn a workflow case for a prompt typo — use a build case, or add one. Native crate tests (cargo nextest run -p <adapter>) stay the Rust inner loop; live eval is for prompt quality. See docs/testing.md.

Stuck?

Symptom	What to check
Eval hangs / auth errors	cursor-agent login or CURSOR_API_KEY in repo-root .env
cargo make fmt fails	Install nightly rustfmt: rustup toolchain install nightly --component rustfmt
cargo make wasm-contracts / wasm-omnia-r9k fails immediately	Needs sibling augentic/emery at ../emery
Patch-resolution errors after editing root Cargo.toml	[patch."https://github.com/augentic/emery.git"] needs ../emery; re-comment if not co-developing
Case fails with a green-looking report	Check expect paths in case.toml — missing files fail the gate
sandbox … already exists	Rerun with --restart, or continue it via cargo make lab -- --project-dir <sandbox> …

More first-run tips: CONTRIBUTING.md. Bugs and questions: GitHub Issues.

Further reading

Topic	Doc
Creating an adapter	docs/authoring.md
Eval case catalog (build + workflow)	examples/eval/README.md
Toolchain, layout, publishing	CONTRIBUTING.md
Test rungs	docs/testing.md
Wasm / WIT seam	examples/wasm/README.md
Agent / contract rules	AGENTS.md
Operator docs (engine)	Emery README · hosted guide
Lab CLI (native catalog; not the shipped CLI)	cargo make lab -- --project-dir <dir> slice list

License

Dual-licensed under MIT or Apache 2.0, at your option. Contribution norms (including DCO) match the engine repo — see emery CONTRIBUTING. Code of Conduct.