Marv

Driving marv

marv is a compiled language whose author is a coding agent and whose auditor is a human. The compiler is a service (JSON-RPC, salsa-incremental) plus a CLI. Your job is to run the loop tightly and respect the invariants. Full context: docs/agents.md, README.md, and spec/03 (the protocol).

The loop

1. check the file(s) you generated (marv check <file>, or the marv_check MCP tool).
2. If there are errors, prefer applying the fix a diagnostic carries (confidence ≥ 0.8) over regenerating; otherwise regenerate the offending definition using the message.
3. fmt to canonical form (marv fmt --write) — never hand-format; there is exactly one form.
4. verify pure / verified-subset definitions (marv verify); on failed, use the counterexample to repair, then re-verify. unsupported is fine (falls back to runtime checks).
5. run / build with an explicit capability grant (marv run --grant …, marv build).
6. commit to freeze reproducible hashes (marv commit); already-reviewed hashes need no re-audit.

Two ways to call it

• CLI — marv fmt|check|run|build|verify|commit (see docs/cli.md). Good for one-shot work.
• MCP server (marv-mcp) — tool-call access with a persistent snapshot: marv_open_snapshot then marv_check / marv_signature / marv_error_set / marv_effects / marv_core / marv_verify / marv_apply_fix / marv_format / marv_commit. Wiring: docs/agents.md.

Invariants (do not fight these)

• No ambient authority — power enters only through capability parameters (Io, Fs, Net, Http, Clock, Rand, Alloc, Spawn); pass a function only what it needs. A function with no Net/Http parameter cannot reach the network or an HTTP request.
• One canonical form — run fmt, don't argue about style.
• Local reasoning — every signature is fully annotated; annotate.
• Determinism — same source ⇒ same hashes/diagnostics.
• Honesty — don't claim a check/verify passed that you didn't run; the tools report unsupported rather than guessing, and so should you.

What parses today

mod/import, local source module sets, struct/enum/fn/interface/impl (including pure fn, generics, bounds, and capability interfaces), let/var, assignment, if/else, match, loops, early return, errors (!T, ?), collection literals, string/bytes/JSON helpers, capability method calls from source, unsafe fn audit metadata, calls/recursion, field projection, and requires/ensures contracts. For raw FFI operations, production listener/resource lifecycles, recursive materialized JSON, or not-yet-supported backend forms, use a *.core.json snapshot or check docs/roadmap.md before generating source.