From e4622cf060cda8d54fa0bb2b558e21abd1712618 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 01:07:13 +0000 Subject: [PATCH 1/2] feat(coprocessor): versioned contract and CLI entry point (D-G, contract first) Add `echidna coprocessor dispatch` and `echidna coprocessor capabilities`. Each prints one JCS line: schema echidna.coprocessor.result/1 or echidna.coprocessor.capabilities/1. The request schema is echidna.coprocessor.request/1. Trust rule: a coprocessor answer is a hint and never a proof. The result type can only write trust.proof = false. Status is a closed vocabulary: computed, declined, unavailable, error. Only computed exits 0. Contract version 1 exposes only in-process kinds that start no program and read no file (Math, Vector, Tensor, Crypto, Dsp, Physics, and FlintMath with the flint feature), through one fail-closed allow-list. Every other kind answers unavailable until the sandboxed runner exists. The owner ruled on 2026-11-19 that decision D-G opens now, contract first. The second consumer is the verifier family. docs/ROADMAP.adoc records the decision and what stays deferred. Stale comments in the coprocessor module and the prove contract document now match the code. Not run: a build with --features flint (needs the system libflint). No Creusot or Verus check ran on the new module: it is tested only. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_0136P7Zmp1i8PGVHkq3u2iNz --- docs/COPROCESSOR-CONTRACT.adoc | 191 ++++++ docs/PROVE-RESULT-CONTRACT.adoc | 5 +- docs/ROADMAP.adoc | 41 ++ docs/planning/ULTRAPLAN-2026-10-09.adoc | 2 + src/rust/cli/args.rs | 21 + src/rust/cli/coprocessor.rs | 64 ++ src/rust/cli/mod.rs | 2 + src/rust/coprocessor/mod.rs | 50 +- src/rust/coprocessor/types.rs | 20 +- src/rust/coprocessor_contract.rs | 784 ++++++++++++++++++++++++ src/rust/lib.rs | 3 +- src/rust/main.rs | 10 +- tests/coprocessor_output_json.rs | 169 +++++ 13 files changed, 1319 insertions(+), 43 deletions(-) create mode 100644 docs/COPROCESSOR-CONTRACT.adoc create mode 100644 src/rust/cli/coprocessor.rs create mode 100644 src/rust/coprocessor_contract.rs create mode 100644 tests/coprocessor_output_json.rs diff --git a/docs/COPROCESSOR-CONTRACT.adoc b/docs/COPROCESSOR-CONTRACT.adoc new file mode 100644 index 00000000..7807d237 --- /dev/null +++ b/docs/COPROCESSOR-CONTRACT.adoc @@ -0,0 +1,191 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += The `echidna.coprocessor.*/1` contract +:toc: macro + +`echidna coprocessor` runs one coprocessor computation and prints the +answer as machine-readable JSON. The first consumers are the per-language +verifier family (atoma, quintessence, Apodeixis.jl, bactrian, canonry, +chancel). Any other client may use it. The decision record is in +`docs/ROADMAP.adoc`, section 8 (2026-11-19). + +toc::[] + +[IMPORTANT] +.Trust rule: a hint, never a proof +==== +A coprocessor answer is a *hint*. It is never a proof. + +* No status says `verified`, `proved` or `proven`. +* `trust.proof` is always the JSON literal `false`. The Rust type + (`NotAProof`) has no other value. +* The contract has no `trust.confidence` field. +* A consumer must confirm an answer with a prover or an exhaustive check + before it raises any proof status. +==== + +== Shape + +Two subcommands. Each prints exactly one line on stdout, terminated by one +newline. The line is a single JCS-canonical (RFC 8785) I-JSON (RFC 7493) +object. Logs go to stderr. + +* `echidna coprocessor dispatch [--request FILE]` reads one request object + from `FILE`, or from stdin when no file is given, and prints one result + object. +* `echidna coprocessor capabilities` prints one capabilities object. + +=== Request: `echidna.coprocessor.request/1` + +[source,json] +---- +{"schema":"echidna.coprocessor.request/1","kind":"Math","op":{"BigIntGcd":{"a":"12","b":"18"}}} +---- + +[cols="1,1,4",options="header"] +|=== +| Field | Type | Meaning + +| `schema` | string | Always `echidna.coprocessor.request/1`. +| `kind` | string | A `CoprocessorKind` variant name (`Math`, `Vector`, ...). +| `op` | object | A `CoprocessorOp` in its existing serde form: external tagging, so the variant name is the only key and the fields are its value. +|=== + +The request is rejected with status `error` when it is not a JSON object, +has a key other than these three, misses one of them, names another schema, +names an unknown kind, or carries an op that does not parse. An op that the +kind's backend does not list in its `supported_ops` is also an `error`. + +=== Result: `echidna.coprocessor.result/1` + +[source,json] +---- +{"deterministic":true,"duration_ms":0,"echidna_version":"","kind":"Math","message":"","op":"BigIntGcd","outcome":{"BigInt":"6"},"schema":"echidna.coprocessor.result/1","status":"computed","trust":{"proof":false,"rank":3,"tier":"LibraryWrapped"}} +---- + +[cols="1,1,4",options="header"] +|=== +| Field | Type | Meaning + +| `schema` | string | Always `echidna.coprocessor.result/1`. +| `status` | string | `computed`, `declined`, `unavailable` or `error` (below). +| `kind` | string or null | The requested kind. `null` when the request did not parse. +| `op` | string or null | The op's variant name. `null` when the request did not parse. +| `outcome` | object, string or null | The `CoprocessorOutcome` in its existing serde form (`{"BigInt":"6"}`, `"Empty"`, `{"Failure":"..."}`, ...). Present for `computed` and `declined`, otherwise `null`. +| `message` | string | Human-readable diagnostic. Empty for `computed`. For `declined` it repeats the backend's reason. +| `trust.tier` | string or null | The backend's `CoprocessorTrustTier` variant name. `null` when no backend was constructed. +| `trust.rank` | integer or null | The tier's `u8` rank (1 to 5). `null` when no backend was constructed. +| `trust.proof` | `false` | Always `false`. See the trust rule. +| `deterministic` | boolean or null | The backend's `deterministic` capability. `null` when no backend was constructed. +| `duration_ms` | integer | Wall-clock time of parsing, construction and dispatch, in milliseconds. Saturates at 2^53 - 1. +| `echidna_version` | string | The version of the `echidna` binary that printed the object. +|=== + +=== Capabilities: `echidna.coprocessor.capabilities/1` + +[cols="1,1,4",options="header"] +|=== +| Field | Type | Meaning + +| `schema` | string | Always `echidna.coprocessor.capabilities/1`. +| `echidna_version` | string | As above. +| `kinds` | array | One entry for every `CoprocessorKind` variant, sorted by kind name. +| `kinds[].kind` | string | The kind's variant name. +| `kinds[].exposed` | boolean | Whether contract version 1 exposes the kind (the allow-list below). +| `kinds[].available` | boolean | The kind is exposed, this build has a backend for it, and its health is `Healthy`. +| `kinds[].trust` | object or null | The same `trust` object as in a result. `null` when no backend was constructed. +| `kinds[].deterministic` | boolean or null | The backend's `deterministic` capability, or `null`. +| `kinds[].supported_ops` | array of strings | The backend's op names. Empty when the kind is not available. +|=== + +The capabilities command never constructs the backend of a kind that is +not exposed. + +== Status mapping + +The vocabulary is closed. A new status needs a new schema identifier. + +[cols="1,4",options="header"] +|=== +| `status` | When + +| `computed` | The backend returned an outcome other than `Failure`. `Empty` (no answer exists, for example a non-invertible modular inverse) is `computed`. +| `declined` | The backend returned `Failure`. The input was well formed and the operation refused it. `message` carries the reason. Example: `VectorAdd` on vectors of different length. +| `unavailable` | The kind is not exposed by contract version 1, the factory returned no backend, or the backend health is not `Healthy`. +| `error` | The request is malformed, the op does not belong to the kind, dispatch returned an error (for example an integer string that does not parse), or the outcome cannot be written as I-JSON. +|=== + +== Exposed kinds + +Contract version 1 exposes only in-process kinds that start no external +program and read no file. The allow-list is one constant, +`EXPOSED_KINDS` in `src/rust/coprocessor_contract.rs`. It fails closed: a +kind not on the list is `unavailable`, and its backend is never +constructed. + +* Exposed: `Math`, `Vector`, `Tensor`, `Crypto`, `Dsp`, `Physics`, and + `FlintMath` only when the `flint` cargo feature is compiled in. +* Not exposed: `Io`, `Graphics`, `Audio`, `Fpga`, `PariGp`, `Maxima`, + `Singular`, `Gap`, `Macaulay2`. Each answers `unavailable` with a message + that says the sandboxed runner of plan item 1.5 does not exist yet. + +== Numbers and bytes + +I-JSON has no NaN and no infinity. An outcome that holds a non-finite float +(`Float`, `FloatVec` or `FloatMatrix`) is not written. The result is +`error` with `outcome` null and a message that names the cause. + +Floats are written as JCS numbers, so `2.0` appears as `2`. Integers that +can grow without bound (`BigInt`, `BigIntPair`, `Factors`) are decimal +strings. `Vec` fields (the `Crypto` op inputs) keep their existing +serde form: an array of numbers from 0 to 255. + +== Exit code + +`0` when `status` is `computed`, `1` otherwise. This follows the +`echidna.prove.result/1` convention (`docs/PROVE-RESULT-CONTRACT.adoc`): +0 only for the one positive status, 1 for every other status. Read +`status` to tell the non-zero cases apart. + +[cols="1,1",options="header"] +|=== +| `status` | Exit code + +| `computed` | 0 +| `declined` | 1 +| `unavailable` | 1 +| `error` | 1 +|=== + +`capabilities` exits 0. + +== Consuming it + +Run the binary, read one line from stdout, and parse it as JSON. Check +`schema` first. Treat `outcome` as a hint: confirm it with a prover or an +exhaustive check before it raises any proof status. Do not read +`trust.tier` as a proof grade: it ranks the backend's implementation, not +the answer. + +== Versioning + +Adding a field is compatible: consumers must ignore unknown fields. +Removing, renaming or retyping a field, adding a status value, or +changing the meaning of an existing value needs a new schema identifier +(`/2`). Exposing a further kind is additive and keeps `/1`. + +== Status of this feature + +* Implemented: `src/rust/coprocessor_contract.rs` (types and the + request-to-result function), `src/rust/cli/coprocessor.rs` (I/O and exit + codes). +* Tested: a golden JCS line for `computed`; `declined`, `unavailable` + (`Io`), `error` for each malformed request, for an op of another kind and + for non-finite floats; the exact allow-list; `trust.proof` false in every + result (`coprocessor_contract` unit tests). End-to-end runs of the real + binary for every status, stdin and `--request FILE`, and `capabilities` + (`tests/coprocessor_output_json.rs`). +* Not verified: no Creusot or Verus check has run on this module. +* Deferred: the Julia router wiring, REST and gRPC routes, exposure of + the kinds outside the allow-list (among them the subprocess kinds and + `Io`) until the sandboxed runner exists, and any use of a coprocessor + answer in the trust pipeline. diff --git a/docs/PROVE-RESULT-CONTRACT.adoc b/docs/PROVE-RESULT-CONTRACT.adoc index 1644c404..48abbe0f 100644 --- a/docs/PROVE-RESULT-CONTRACT.adoc +++ b/docs/PROVE-RESULT-CONTRACT.adoc @@ -105,8 +105,9 @@ new schema identifier (`echidna.prove.result/2`). == Status of this feature -* Implemented: `src/rust/prove_contract.rs`, `src/rust/main.rs` - (`prove_json_command`), `crates/echidna-core/src/prove_result.rs`. +* Implemented: `src/rust/prove_contract.rs`, `src/rust/cli/prove.rs` + (`prove_json_command`, `emit_prove_result`), + `crates/echidna-core/src/prove_result.rs`. * Tested: golden JCS bytes for every status (`echidna-core` and `prove_contract` unit tests); planted non-canonical payloads are rejected; end-to-end runs of the real binary for `verified`, `failed` diff --git a/docs/ROADMAP.adoc b/docs/ROADMAP.adoc index 2d22964e..0c6598a0 100644 --- a/docs/ROADMAP.adoc +++ b/docs/ROADMAP.adoc @@ -360,3 +360,44 @@ once it’s next‑up. the "`Today`" column becomes "`Done`" and the "`End‑state`" column stays as the invariant. * Record non‑trivial decisions in this doc, not in chat. + +=== 8. Decision record + +[[decision-2026-11-19-coprocessor-contract]] +==== 2026-11-19: coprocessor contract (D-G opens, contract first) + +*Ruling.* The owner ruled that D-G opens now, contract first. Until today +the plan deferred the coprocessor surface "until a second consumer needs +it" (`docs/planning/ULTRAPLAN-2026-10-09.adoc`, item 6.2 and the D-G row). + +*Second consumer.* The per-language verifier family: atoma, quintessence, +Apodeixis.jl, bactrian, canonry and chancel. Their shared plan is +`docs/plan/FAMILY-ULTRAPLAN.adoc` in hyperpolymath/atoma, package F10. + +*What this change delivers.* + +* The contract document + link:COPROCESSOR-CONTRACT.adoc[`+docs/COPROCESSOR-CONTRACT.adoc+`], with + three schemas: `echidna.coprocessor.request/1`, + `echidna.coprocessor.result/1` and `echidna.coprocessor.capabilities/1`. +* The CLI subcommands `echidna coprocessor dispatch` and + `echidna coprocessor capabilities`. Each prints one JCS line. +* A closed status vocabulary (`computed`, `declined`, `unavailable`, + `error`) and the trust rule: a coprocessor answer is a hint, never a + proof. `trust.proof` is always `false`. +* A fail-closed allow-list of in-process kinds that start no external + program and read no file: `Math`, `Vector`, `Tensor`, `Crypto`, `Dsp`, + `Physics`, and `FlintMath` with the `flint` feature. +* Unit tests in `src/rust/coprocessor_contract.rs` and end-to-end tests in + `tests/coprocessor_output_json.rs`. No Creusot or Verus check has run on + the new module. + +*What stays deferred.* + +* The Julia router wiring. +* REST and gRPC routes. +* Exposure of the kinds outside the allow-list (`Io`, `Graphics`, `Audio`, + `Fpga`, `PariGp`, `Maxima`, `Singular`, `Gap`, `Macaulay2`), among them + the subprocess kinds and the file kind `Io`, until the sandboxed runner + of plan item 1.5 exists. +* Any use of a coprocessor answer in the trust pipeline. diff --git a/docs/planning/ULTRAPLAN-2026-10-09.adoc b/docs/planning/ULTRAPLAN-2026-10-09.adoc index 7c5fc444..008d8480 100644 --- a/docs/planning/ULTRAPLAN-2026-10-09.adoc +++ b/docs/planning/ULTRAPLAN-2026-10-09.adoc @@ -947,6 +947,7 @@ Work: are frozen, since a schema written earlier encodes the wrong types. * *6.2 Coprocessor trait (D-G).* Defer until a second consumer needs it. Each added trait is a surface to keep correct. + _Note 2026-11-19: D-G opened, contract first; see link:../ROADMAP.adoc#decision-2026-11-19-coprocessor-contract[ROADMAP §8]._ * *6.3 Chapel (D-L).* Keep Chapel opt-in. Default-on only after #161 meets a criterion fixed before the run. The TODO states 1.5× on eight or more cores. #161 is the real-corpus speedup bench, but its body states no threshold. One @@ -1034,6 +1035,7 @@ elegant arm under section 2. Blocking phases show which work waits on it. | (a) sign off all three together as the sheet proposes; (b) sequence transport after type freeze and defer the coprocessor | (b): freeze, then schema, then transport. Defer the coprocessor until needed + _(Note 2026-11-19: D-G opened, contract first; see link:../ROADMAP.adoc#decision-2026-11-19-coprocessor-contract[ROADMAP §8].)_ | 6.x | D-H | Corpus and model storage diff --git a/src/rust/cli/args.rs b/src/rust/cli/args.rs index 384622df..45098c9e 100644 --- a/src/rust/cli/args.rs +++ b/src/rust/cli/args.rs @@ -192,6 +192,12 @@ pub(crate) enum Commands { op: DesignOp, }, + /// Run one coprocessor computation as a JSON contract (a hint, never a proof) + Coprocessor { + #[command(subcommand)] + op: CoprocessorCommand, + }, + /// Suggest tactic variants that close a failing lemma Suggest { /// Target in `:` form, e.g. `Foo.thy:bar` @@ -351,6 +357,21 @@ pub(crate) enum CorpusOp { }, } +/// Subcommands of `echidna coprocessor` (`docs/COPROCESSOR-CONTRACT.adoc`). +#[derive(Subcommand)] +pub(crate) enum CoprocessorCommand { + /// Read one `echidna.coprocessor.request/1` object and print one + /// `echidna.coprocessor.result/1` object (JCS-canonical I-JSON) on + /// stdout. Logs go to stderr. + Dispatch { + /// Read the request from this file instead of stdin. + #[arg(long)] + request: Option, + }, + /// Print one `echidna.coprocessor.capabilities/1` object on stdout. + Capabilities, +} + #[derive(Subcommand)] pub(crate) enum LexiconOp { /// Pair theorem names and canonical statement shapes across training diff --git a/src/rust/cli/coprocessor.rs b/src/rust/cli/coprocessor.rs new file mode 100644 index 00000000..b113ea90 --- /dev/null +++ b/src/rust/cli/coprocessor.rs @@ -0,0 +1,64 @@ +// SPDX-License-Identifier: MPL-2.0 + +//! `echidna coprocessor`: the `echidna.coprocessor.*/1` contract on the +//! command line. This module only does I/O and exit codes; the contract +//! lives in `echidna::coprocessor_contract`. See +//! `docs/COPROCESSOR-CONTRACT.adoc`. + +use super::CoprocessorCommand; +use echidna::coprocessor_contract::{self, CoprocessorResult, CoprocessorStatus}; +use std::io::Read; +use std::path::PathBuf; + +/// Run one `echidna coprocessor` subcommand. Never returns. +pub(crate) async fn coprocessor_command(cmd: CoprocessorCommand) -> ! { + match cmd { + CoprocessorCommand::Dispatch { request } => { + let result = match read_request(request) { + Ok(input) => coprocessor_contract::dispatch_request(&input).await, + Err(e) => CoprocessorResult::malformed(e, 0), + }; + emit_coprocessor_result(&result); + }, + CoprocessorCommand::Capabilities => { + let line = coprocessor_contract::capabilities() + .to_jcs() + .expect("the capabilities report holds no floats and no large integers"); + println!("{line}"); + std::process::exit(0); + }, + } +} + +/// Read the request text from `file`, or from stdin when `file` is `None`. +fn read_request(file: Option) -> Result { + match file { + Some(path) => std::fs::read_to_string(&path) + .map_err(|e| format!("cannot read request file {}: {e}", path.display())), + None => { + let mut s = String::new(); + std::io::stdin() + .read_to_string(&mut s) + .map_err(|e| format!("cannot read request from stdin: {e}"))?; + Ok(s) + }, + } +} + +/// Print `result` as its one JCS line on stdout and exit (0 iff computed). +/// +/// If the value cannot be serialised, a minimal `error` object is printed +/// instead, so stdout always carries one contract object. +fn emit_coprocessor_result(result: &CoprocessorResult) -> ! { + let (line, status) = match result.to_jcs() { + Ok(line) => (line, result.status), + Err(e) => ( + CoprocessorResult::malformed(format!("could not serialise result: {e}"), 0) + .to_jcs() + .expect("an error result with no outcome serialises"), + CoprocessorStatus::Error, + ), + }; + println!("{line}"); + std::process::exit(status.exit_code()); +} diff --git a/src/rust/cli/mod.rs b/src/rust/cli/mod.rs index ecb5cc5e..f1a33fe4 100644 --- a/src/rust/cli/mod.rs +++ b/src/rust/cli/mod.rs @@ -6,6 +6,7 @@ //! dispatches to these. mod args; +mod coprocessor; mod corpus; mod design; mod lexicon; @@ -17,6 +18,7 @@ mod util; mod verify; pub(crate) use args::*; +pub(crate) use coprocessor::*; pub(crate) use corpus::*; pub(crate) use design::*; pub(crate) use lexicon::*; diff --git a/src/rust/coprocessor/mod.rs b/src/rust/coprocessor/mod.rs index 485f6df1..e5eb53b5 100644 --- a/src/rust/coprocessor/mod.rs +++ b/src/rust/coprocessor/mod.rs @@ -12,30 +12,27 @@ //! arithmetic cannot decide alone) and the meta-controller (for example: //! tensor / vector ops backing GNN-guided proof search). //! -//! Currently provided: -//! - `Math` backend (in-process, Rust + `num-bigint` family). +//! Currently provided, all constructed by `CoprocessorFactory::native`: +//! - In process, pure Rust: `Math` (`num-bigint` family), `Vector`, +//! `Tensor` (`nalgebra`), `Crypto` (`sha2`, `blake3`, `ed25519-dalek`), +//! `Physics`, `Dsp` (`rustfft`), `Graphics` (SVG strings) and `Audio` +//! (WAV bytes). +//! - In process, reads files: `Io` (`tokio::fs`). +//! - In process through C FFI: `FlintMath`, only with `--features flint`. +//! - External subprocess: `Fpga` (yosys), `PariGp`, `Maxima`, `Singular`, +//! `Gap` and `Macaulay2`. //! - Generic `JuliaCoprocessorBridge` transport for any Julia-side backend //! that registers at `http://127.0.0.1:8090/coprocessor/dispatch`. //! -//! Planned (Phase 6, each landing with its full implementation — never as -//! a stub): -//! - `Physics` — integration with InvestigativeJournalist.jl numerics -//! - `Dsp` — DSP.jl + LowLevel.jl -//! - `Fpga` — Yosys/Verilator integration via `ffi/zig` -//! - `Tensor` — Tensors.jl + StaticArrays -//! - `Vector` — Rust `std::simd` portable SIMD -//! - `Crypto` — ProvenCrypto.jl + RustCrypto under SPARK boundary -//! - `Graphics` — wgpu compute path -//! - `Audio` — DSP.jl audio extensions -//! - `Io` — LowLevel.jl IOPU +//! `src/rust/coprocessor_contract.rs` exposes a fail-closed subset of these +//! kinds on the command line (`echidna coprocessor`); see +//! `docs/COPROCESSOR-CONTRACT.adoc`. //! -//! Each variant lands in its own commit with a fully working implementation, -//! tests, capability declaration, trust tier classification, and Idris2 ABI -//! entry — never with `unimplemented!()` placeholders. -//! -//! The trust pipeline (`dispatch.rs`) consults the coprocessor's trust tier -//! when folding a coprocessor result into a prover-side trust calculation; -//! see `coprocessor::trust::CoprocessorTrustTier`. +//! No code outside this module reads the trust tier today: `dispatch.rs` +//! does not consult it, and `agent::meta_controller` dispatches coprocessor +//! pre-steps without reading it. A coprocessor result is not folded into +//! any prover-side trust calculation. See +//! `coprocessor::trust::CoprocessorTrustTier` for the ladder. use anyhow::Result; use async_trait::async_trait; @@ -112,18 +109,17 @@ pub trait Coprocessor: Send + Sync { /// Factory mirroring `ProverFactory`. /// -/// Phase 0 only constructs the `Math` backend natively. Phase 6 backends -/// add their own arms here as they land. The Julia bridge is constructed -/// separately because it parameterises by the *Julia-side* backend kind, -/// not by a fixed Rust impl. +/// Constructs a native backend for every kind; `FlintMath` only with +/// `--features flint`. The Julia bridge is constructed separately because +/// it parameterises by the *Julia-side* backend kind, not by a fixed Rust +/// impl. pub struct CoprocessorFactory; impl CoprocessorFactory { /// Construct a native (Rust) coprocessor by kind. /// - /// Returns `None` when the requested kind has no native Rust backend - /// — caller should fall through to a Julia bridge or external - /// subprocess backend in Phases 6-7. + /// Returns `None` only for `FlintMath` built without the `flint` + /// feature; the caller may then fall through to a Julia bridge. pub fn native(kind: CoprocessorKind) -> Option> { match kind { CoprocessorKind::Math => Some(Box::new(MathBackend::new())), diff --git a/src/rust/coprocessor/types.rs b/src/rust/coprocessor/types.rs index e1f5fe91..f50fc2d5 100644 --- a/src/rust/coprocessor/types.rs +++ b/src/rust/coprocessor/types.rs @@ -9,19 +9,18 @@ //! `CoprocessorCapabilities` is what a backend reports it can do, and //! `CoprocessorHealth` is its runtime liveness. //! -//! The op set starts with the Math operations needed by the number-theory -//! and algebraic-decision-procedure backends planned for Phases 2 and 3 -//! (FLINT, PARI/GP, GAP, QEPCAD-B, …). Future variants for Physics, DSP, -//! FPGA, Tensor, Vector, Crypto, Graphics, Audio, IO are added alongside -//! their backend implementations in Phase 6 — never as stubs. +//! The op set covers every implemented backend: Math, Vector, Tensor, +//! Crypto, Physics, FLINT, DSP, IO, Graphics, Audio, FPGA, and the +//! subprocess CAS backends (PARI/GP, Maxima, Singular, GAP, Macaulay2). +//! A new op is added together with the backend that implements it, never +//! as a stub. use serde::{Deserialize, Serialize}; /// The kind of coprocessor a backend implements. /// -/// Only variants with a fully-functional backend are present. Phase 6A -/// adds Vector / Tensor / Crypto / Physics; Phase 6B will add DSP / FPGA / -/// Graphics / Audio / IO together with their implementations. +/// Only variants with a fully-functional backend are present; every +/// variant below has one (`FlintMath` only with `--features flint`). /// /// Discriminants are explicit and `#[repr(u8)]`: they are the FFI tags that /// `src/abi/Coprocessor/Foreign.idr` (`coprocessorKindToU8`) mirrors, and @@ -56,7 +55,8 @@ pub enum CoprocessorKind { /// FLINT integer and polynomial algebra — the only CAS backend that links /// the library in-process rather than shelling out. Requires /// `--features flint` and a system FLINT (LGPL-3) installation. - /// Enabled by `CoprocessorFactory::native`; absent without the feature. + /// Built by `CoprocessorFactory::native`, which returns `None` for it + /// without the feature. FlintMath = 5, /// Digital signal processing — FFT/IFFT, window functions. Backed by @@ -83,7 +83,7 @@ pub enum CoprocessorKind { /// expressed in Verilog / SystemVerilog. Fpga = 10, - // ── Phase 2b: subprocess CAS backends (ExternalSubprocess / Tier 1) ── + // ── Subprocess CAS backends (ExternalSubprocess / Tier 1) ── /// PARI/GP number theory — subprocess to `gp`. Advanced factoring (ECM / /// GNFS), multiplicative order, next-prime queries. PARI is the gold /// standard for algorithmic number theory. diff --git a/src/rust/coprocessor_contract.rs b/src/rust/coprocessor_contract.rs new file mode 100644 index 00000000..0b67ae84 --- /dev/null +++ b/src/rust/coprocessor_contract.rs @@ -0,0 +1,784 @@ +// SPDX-License-Identifier: MPL-2.0 + +//! Producer side of the `echidna.coprocessor.result/1` contract. +//! +//! `echidna coprocessor dispatch` reads one `echidna.coprocessor.request/1` +//! object and prints one [`CoprocessorResult`] as JCS-canonical I-JSON on +//! stdout. `echidna coprocessor capabilities` prints one +//! [`CapabilitiesReport`]. This module holds the types and the pure +//! request-to-result function; `src/rust/cli/coprocessor.rs` does the I/O. +//! +//! Trust rule: a coprocessor answer is a hint, never a proof. No status +//! says `verified`, `proved` or `proven`, and `trust.proof` is the type +//! [`NotAProof`], which can only serialise as `false`. +//! +//! See `docs/COPROCESSOR-CONTRACT.adoc` for the contract. + +use std::time::Instant; + +use serde::{Serialize, Serializer}; +use serde_json::Value; + +use crate::coprocessor::{ + Coprocessor, CoprocessorFactory, CoprocessorHealth, CoprocessorKind, CoprocessorOp, + CoprocessorOutcome, CoprocessorTrustTier, +}; +pub use crate::prove_contract::ECHIDNA_VERSION; +use echidna_core::prove_result::MAX_SAFE_INTEGER; + +/// The request schema this module accepts. +pub const REQUEST_SCHEMA: &str = "echidna.coprocessor.request/1"; + +/// The result schema this module emits. +pub const RESULT_SCHEMA: &str = "echidna.coprocessor.result/1"; + +/// The capabilities schema this module emits. +pub const CAPABILITIES_SCHEMA: &str = "echidna.coprocessor.capabilities/1"; + +/// The value `trust.proof` always carries. A coprocessor answer is a hint. +pub const IS_PROOF: bool = false; + +/// The fail-closed allow-list of kinds that contract version 1 exposes. +/// +/// Only in-process kinds that start no external program and read no file. +/// Every kind not listed here answers `unavailable`, and its backend is +/// never constructed. `FlintMath` is listed only when the `flint` feature +/// is compiled in. +#[cfg(not(feature = "flint"))] +pub const EXPOSED_KINDS: &[CoprocessorKind] = &[ + CoprocessorKind::Math, + CoprocessorKind::Vector, + CoprocessorKind::Tensor, + CoprocessorKind::Crypto, + CoprocessorKind::Dsp, + CoprocessorKind::Physics, +]; + +/// The fail-closed allow-list of kinds that contract version 1 exposes. +/// +/// Only in-process kinds that start no external program and read no file. +/// Every kind not listed here answers `unavailable`, and its backend is +/// never constructed. `FlintMath` is listed only when the `flint` feature +/// is compiled in. +#[cfg(feature = "flint")] +pub const EXPOSED_KINDS: &[CoprocessorKind] = &[ + CoprocessorKind::Math, + CoprocessorKind::Vector, + CoprocessorKind::Tensor, + CoprocessorKind::Crypto, + CoprocessorKind::Dsp, + CoprocessorKind::Physics, + CoprocessorKind::FlintMath, +]; + +/// Every `CoprocessorKind` variant, in discriminant order. +pub const ALL_KINDS: [CoprocessorKind; 16] = [ + CoprocessorKind::Math, + CoprocessorKind::Vector, + CoprocessorKind::Tensor, + CoprocessorKind::Crypto, + CoprocessorKind::Physics, + CoprocessorKind::FlintMath, + CoprocessorKind::Dsp, + CoprocessorKind::Io, + CoprocessorKind::Graphics, + CoprocessorKind::Audio, + CoprocessorKind::Fpga, + CoprocessorKind::PariGp, + CoprocessorKind::Maxima, + CoprocessorKind::Singular, + CoprocessorKind::Gap, + CoprocessorKind::Macaulay2, +]; + +/// Whether contract version 1 exposes `kind`. +pub fn is_exposed(kind: CoprocessorKind) -> bool { + EXPOSED_KINDS.contains(&kind) +} + +/// The closed status vocabulary of a coprocessor result. +/// +/// There is deliberately no `verified`, `proved` or `proven`: a +/// coprocessor answer is a hint. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)] +#[serde(rename_all = "lowercase")] +pub enum CoprocessorStatus { + /// The backend returned an outcome other than `Failure`. + Computed, + /// The backend returned `Failure`: the input was well formed, and the + /// operation refused it. + Declined, + /// The kind is not exposed, has no backend in this build, or its + /// backend is not healthy. + Unavailable, + /// The request is malformed, dispatch failed, or the outcome cannot be + /// written as I-JSON. + Error, +} + +impl CoprocessorStatus { + /// Every status, in contract order. + pub const ALL: [CoprocessorStatus; 4] = [ + CoprocessorStatus::Computed, + CoprocessorStatus::Declined, + CoprocessorStatus::Unavailable, + CoprocessorStatus::Error, + ]; + + /// The wire string of this status. + pub fn as_str(self) -> &'static str { + match self { + CoprocessorStatus::Computed => "computed", + CoprocessorStatus::Declined => "declined", + CoprocessorStatus::Unavailable => "unavailable", + CoprocessorStatus::Error => "error", + } + } + + /// The process exit code for this status: 0 only for `computed`. + pub fn exit_code(self) -> i32 { + match self { + CoprocessorStatus::Computed => 0, + _ => 1, + } + } +} + +/// Marker that a coprocessor answer is not a proof. +/// +/// It has one value and serialises as [`IS_PROOF`] (`false`), so no code +/// path can emit `trust.proof: true`. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub struct NotAProof; + +impl Serialize for NotAProof { + /// Write the JSON literal `false`. + fn serialize(&self, s: S) -> Result { + s.serialize_bool(IS_PROOF) + } +} + +/// The `trust` object: the backend's tier, and the fixed `proof: false`. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct CoprocessorTrust { + /// The `CoprocessorTrustTier` variant name, or `None` when no backend ran. + pub tier: Option, + /// The tier's `u8` rank, or `None` when no backend ran. + pub rank: Option, + /// Always `false`. + pub proof: NotAProof, +} + +impl CoprocessorTrust { + /// The trust object for a backend of tier `tier`. + pub fn of(tier: CoprocessorTrustTier) -> Self { + CoprocessorTrust { + tier: Some(format!("{tier:?}")), + rank: Some(tier.as_u8()), + proof: NotAProof, + } + } + + /// The trust object when no backend was constructed. + pub fn none() -> Self { + CoprocessorTrust { + tier: None, + rank: None, + proof: NotAProof, + } + } +} + +/// One `echidna.coprocessor.result/1` object. +#[derive(Debug, Clone, Serialize)] +pub struct CoprocessorResult { + /// Always [`RESULT_SCHEMA`]. + pub schema: &'static str, + /// The verdict, from the closed vocabulary. + pub status: CoprocessorStatus, + /// The kind's variant name, or `None` when the request did not parse. + pub kind: Option, + /// The op's variant name, or `None` when the request did not parse. + pub op: Option, + /// The backend outcome (`computed` and `declined` only). + pub outcome: Option, + /// Human-readable diagnostic; may be empty. + pub message: String, + /// The backend's trust tier and the fixed `proof: false`. + pub trust: CoprocessorTrust, + /// The backend's `deterministic` capability, or `None` with no backend. + pub deterministic: Option, + /// Wall-clock time of the whole request, in milliseconds. + pub duration_ms: u64, + /// The ECHIDNA version that emitted this object. + pub echidna_version: String, +} + +/// What a result says about the backend that served it. +#[derive(Debug, Clone, Copy)] +pub struct BackendFacts { + /// The backend's trust tier. + pub tier: CoprocessorTrustTier, + /// The backend's `deterministic` capability. + pub deterministic: bool, +} + +impl BackendFacts { + /// Read the facts from a constructed backend. + pub fn of(backend: &dyn Coprocessor) -> Self { + BackendFacts { + tier: backend.trust_tier(), + deterministic: backend.capabilities().deterministic, + } + } +} + +impl CoprocessorResult { + /// Build a result with the current schema and version. + /// + /// `duration_ms` saturates at 2^53 - 1. + pub fn new( + status: CoprocessorStatus, + names: Option<(CoprocessorKind, &str)>, + outcome: Option, + message: impl Into, + backend: Option, + duration_ms: u64, + ) -> Self { + CoprocessorResult { + schema: RESULT_SCHEMA, + status, + kind: names.map(|(k, _)| kind_name(k)), + op: names.map(|(_, o)| o.to_string()), + outcome, + message: message.into(), + trust: backend + .map(|b| CoprocessorTrust::of(b.tier)) + .unwrap_or_else(CoprocessorTrust::none), + deterministic: backend.map(|b| b.deterministic), + duration_ms: duration_ms.min(MAX_SAFE_INTEGER), + echidna_version: ECHIDNA_VERSION.to_string(), + } + } + + /// An `error` result for a request that did not parse. + pub fn malformed(message: impl Into, duration_ms: u64) -> Self { + CoprocessorResult::new( + CoprocessorStatus::Error, + None, + None, + message, + None, + duration_ms, + ) + } + + /// Serialise to the one-line JCS-canonical I-JSON form (no newline). + /// + /// Fails rather than emit a non-finite float or an unsafe integer. + pub fn to_jcs(&self) -> Result { + if self.duration_ms > MAX_SAFE_INTEGER { + return Err(format!( + "duration_ms {} exceeds the I-JSON safe range", + self.duration_ms + )); + } + if let Some(o) = &self.outcome { + if !outcome_is_finite(o) { + return Err(NON_FINITE.to_string()); + } + } + serde_json_canonicalizer::to_string(self).map_err(|e| e.to_string()) + } +} + +/// The message for an outcome that holds NaN or an infinity. +const NON_FINITE: &str = + "the outcome holds a non-finite float (NaN or infinity), which I-JSON cannot carry"; + +/// Whether every float in `outcome` is finite (I-JSON has no NaN or infinity). +pub fn outcome_is_finite(outcome: &CoprocessorOutcome) -> bool { + match outcome { + CoprocessorOutcome::Float(x) => x.is_finite(), + CoprocessorOutcome::FloatVec(v) => v.iter().all(|x| x.is_finite()), + CoprocessorOutcome::FloatMatrix(m) => m.iter().flatten().all(|x| x.is_finite()), + CoprocessorOutcome::BigInt(_) + | CoprocessorOutcome::BigIntPair(_, _) + | CoprocessorOutcome::Factors(_) + | CoprocessorOutcome::Boolean(_) + | CoprocessorOutcome::Hex(_) + | CoprocessorOutcome::Polynomial(_) + | CoprocessorOutcome::Text(_) + | CoprocessorOutcome::Empty + | CoprocessorOutcome::Failure(_) => true, + } +} + +/// The wire name of `kind` (its serde form, which is the variant name). +pub fn kind_name(kind: CoprocessorKind) -> String { + match serde_json::to_value(kind) { + Ok(Value::String(s)) => s, + _ => format!("{kind:?}"), + } +} + +/// The wire name of `op` (the key of its externally tagged serde form). +pub fn op_name(op: &CoprocessorOp) -> String { + match serde_json::to_value(op) { + Ok(Value::Object(m)) if m.len() == 1 => m.keys().next().cloned().unwrap_or_default(), + Ok(Value::String(s)) => s, + _ => String::new(), + } +} + +/// A request that parsed: the kind and the op. +#[derive(Debug, Clone)] +pub struct CoprocessorRequest { + /// The requested kind. + pub kind: CoprocessorKind, + /// The requested op, in the existing `CoprocessorOp` serde form. + pub op: CoprocessorOp, +} + +/// Parse one `echidna.coprocessor.request/1` object. +/// +/// Rejects anything that is not a JSON object with exactly the keys +/// `schema`, `kind` and `op`, a schema other than [`REQUEST_SCHEMA`], an +/// unknown kind, and an op that does not parse as a `CoprocessorOp`. +pub fn parse_request(input: &str) -> Result { + let value: Value = + serde_json::from_str(input).map_err(|e| format!("request is not JSON: {e}"))?; + let Value::Object(map) = value else { + return Err("request must be a JSON object".into()); + }; + if let Some(extra) = map + .keys() + .find(|k| !matches!(k.as_str(), "schema" | "kind" | "op")) + { + return Err(format!("unknown top-level key {extra:?}")); + } + match map.get("schema") { + Some(Value::String(s)) if s == REQUEST_SCHEMA => {}, + Some(Value::String(s)) => return Err(format!("unsupported schema {s:?}")), + Some(_) => return Err("`schema` must be a string".into()), + None => return Err("missing key `schema`".into()), + } + let kind_v = map.get("kind").ok_or("missing key `kind`")?; + let kind: CoprocessorKind = serde_json::from_value(kind_v.clone()) + .map_err(|e| format!("unknown kind {kind_v}: {e}"))?; + let op_v = map.get("op").ok_or("missing key `op`")?; + let op: CoprocessorOp = + serde_json::from_value(op_v.clone()).map_err(|e| format!("op does not parse: {e}"))?; + Ok(CoprocessorRequest { kind, op }) +} + +/// Turn a backend outcome into a result (`computed`, `declined` or `error`). +/// +/// A `Failure` outcome is `declined`; an outcome with a non-finite float is +/// `error` with no outcome; anything else is `computed`. +pub fn result_from_outcome( + kind: CoprocessorKind, + op: &str, + outcome: CoprocessorOutcome, + backend: BackendFacts, + duration_ms: u64, +) -> CoprocessorResult { + let names = Some((kind, op)); + match outcome { + CoprocessorOutcome::Failure(reason) => CoprocessorResult::new( + CoprocessorStatus::Declined, + names, + Some(CoprocessorOutcome::Failure(reason.clone())), + reason, + Some(backend), + duration_ms, + ), + o if !outcome_is_finite(&o) => CoprocessorResult::new( + CoprocessorStatus::Error, + names, + None, + NON_FINITE, + Some(backend), + duration_ms, + ), + o => CoprocessorResult::new( + CoprocessorStatus::Computed, + names, + Some(o), + "", + Some(backend), + duration_ms, + ), + } +} + +/// The `unavailable` message for a kind that contract version 1 does not expose. +fn not_exposed_message(kind: CoprocessorKind) -> String { + format!( + "kind {} is not exposed by contract version 1: the sandboxed runner of plan item 1.5 does not exist yet", + kind_name(kind) + ) +} + +/// Run one request end to end. Never fails: every failure is a result. +/// +/// `duration_ms` covers parsing, backend construction and dispatch. +pub async fn dispatch_request(input: &str) -> CoprocessorResult { + let start = Instant::now(); + let elapsed = || u64::try_from(start.elapsed().as_millis()).unwrap_or(u64::MAX); + + let req = match parse_request(input) { + Ok(r) => r, + Err(e) => return CoprocessorResult::malformed(e, elapsed()), + }; + let op = op_name(&req.op); + let names = Some((req.kind, op.as_str())); + + if !is_exposed(req.kind) { + return CoprocessorResult::new( + CoprocessorStatus::Unavailable, + names, + None, + not_exposed_message(req.kind), + None, + elapsed(), + ); + } + let Some(backend) = CoprocessorFactory::native(req.kind) else { + return CoprocessorResult::new( + CoprocessorStatus::Unavailable, + names, + None, + format!("this build has no backend for kind {}", kind_name(req.kind)), + None, + elapsed(), + ); + }; + let facts = BackendFacts::of(&*backend); + let health = backend.health(); + if health != CoprocessorHealth::Healthy { + return CoprocessorResult::new( + CoprocessorStatus::Unavailable, + names, + None, + format!("backend health is {health:?}"), + Some(facts), + elapsed(), + ); + } + if !backend + .capabilities() + .supported_ops + .iter() + .any(|s| s == &op) + { + return CoprocessorResult::new( + CoprocessorStatus::Error, + names, + None, + format!("op {op} does not belong to kind {}", kind_name(req.kind)), + Some(facts), + elapsed(), + ); + } + match backend.dispatch(req.op).await { + Ok(outcome) => result_from_outcome(req.kind, &op, outcome, facts, elapsed()), + Err(e) => CoprocessorResult::new( + CoprocessorStatus::Error, + names, + None, + format!("{e:#}"), + Some(facts), + elapsed(), + ), + } +} + +/// One entry of the capabilities report. +#[derive(Debug, Clone, Serialize)] +pub struct KindCapability { + /// The kind's variant name. + pub kind: String, + /// Whether contract version 1 exposes the kind (the allow-list). + pub exposed: bool, + /// Exposed, a backend exists in this build, and it is healthy. + pub available: bool, + /// The backend's trust object, or `None` when no backend was constructed. + pub trust: Option, + /// The backend's `deterministic` capability, or `None` with no backend. + pub deterministic: Option, + /// The backend's supported op names; empty when not available. + pub supported_ops: Vec, +} + +/// One `echidna.coprocessor.capabilities/1` object. +#[derive(Debug, Clone, Serialize)] +pub struct CapabilitiesReport { + /// Always [`CAPABILITIES_SCHEMA`]. + pub schema: &'static str, + /// The ECHIDNA version that emitted this object. + pub echidna_version: String, + /// One entry per `CoprocessorKind` variant, sorted by kind name. + pub kinds: Vec, +} + +impl CapabilitiesReport { + /// Serialise to the one-line JCS-canonical form (no newline). + pub fn to_jcs(&self) -> Result { + serde_json_canonicalizer::to_string(self).map_err(|e| e.to_string()) + } +} + +/// Build the capabilities report. Constructs only exposed backends. +pub fn capabilities() -> CapabilitiesReport { + let mut kinds: Vec = ALL_KINDS + .iter() + .map(|&kind| { + let exposed = is_exposed(kind); + let backend = if exposed { + CoprocessorFactory::native(kind) + } else { + None + }; + match backend { + None => KindCapability { + kind: kind_name(kind), + exposed, + available: false, + trust: None, + deterministic: None, + supported_ops: Vec::new(), + }, + Some(b) => { + let available = b.health() == CoprocessorHealth::Healthy; + KindCapability { + kind: kind_name(kind), + exposed, + available, + trust: Some(CoprocessorTrust::of(b.trust_tier())), + deterministic: Some(b.capabilities().deterministic), + supported_ops: if available { + b.capabilities().supported_ops.clone() + } else { + Vec::new() + }, + } + }, + } + }) + .collect(); + kinds.sort_by(|a, b| a.kind.cmp(&b.kind)); + CapabilitiesReport { + schema: CAPABILITIES_SCHEMA, + echidna_version: ECHIDNA_VERSION.to_string(), + kinds, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Request JSON for `kind` and an op given as raw JSON. + fn request(kind: &str, op: &str) -> String { + format!(r#"{{"schema":"{REQUEST_SCHEMA}","kind":"{kind}","op":{op}}}"#) + } + + /// The parsed JSON of a result, after checking `trust.proof` is false. + fn json(r: &CoprocessorResult) -> Value { + let v: Value = serde_json::from_str(&r.to_jcs().expect("serialises")).unwrap(); + assert_eq!(v["trust"]["proof"], Value::Bool(false), "{v}"); + v + } + + /// Golden JCS bytes for one `computed` result with fixed fields. + #[test] + fn golden_computed_result() { + let facts = BackendFacts { + tier: CoprocessorTrustTier::LibraryWrapped, + deterministic: true, + }; + let r = result_from_outcome( + CoprocessorKind::Math, + "BigIntGcd", + CoprocessorOutcome::BigInt("6".into()), + facts, + 7, + ); + let expected = format!( + r#"{{"deterministic":true,"duration_ms":7,"echidna_version":"{ECHIDNA_VERSION}","kind":"Math","message":"","op":"BigIntGcd","outcome":{{"BigInt":"6"}},"schema":"echidna.coprocessor.result/1","status":"computed","trust":{{"proof":false,"rank":3,"tier":"LibraryWrapped"}}}}"# + ); + assert_eq!(r.to_jcs().unwrap(), expected); + } + + /// A real request through the real backend computes gcd(12, 18) = 6. + #[tokio::test] + async fn math_gcd_is_computed() { + let r = dispatch_request(&request("Math", r#"{"BigIntGcd":{"a":"12","b":"18"}}"#)).await; + assert_eq!(r.status, CoprocessorStatus::Computed); + let v = json(&r); + assert_eq!(v["outcome"], serde_json::json!({"BigInt": "6"})); + assert_eq!(v["kind"], "Math"); + assert_eq!(v["op"], "BigIntGcd"); + } + + /// `VectorAdd` on vectors of different length makes the backend return + /// `Failure` (`vector.rs`), which is `declined`. + #[tokio::test] + async fn length_mismatch_is_declined() { + let r = dispatch_request(&request( + "Vector", + r#"{"VectorAdd":{"a":[1.0,2.0],"b":[1.0]}}"#, + )) + .await; + assert_eq!(r.status, CoprocessorStatus::Declined, "{r:?}"); + assert!(!r.message.is_empty()); + let v = json(&r); + assert!(v["outcome"]["Failure"].is_string(), "{v}"); + } + + /// A kind outside the allow-list is `unavailable`, with no backend. + #[tokio::test] + async fn io_is_unavailable() { + let r = dispatch_request(&request("Io", r#"{"IoLineCount":{"path":"/etc/passwd"}}"#)).await; + assert_eq!(r.status, CoprocessorStatus::Unavailable); + assert!(r.message.contains("not exposed by contract version 1")); + assert!(r.message.contains("1.5")); + assert_eq!(r.trust, CoprocessorTrust::none()); + assert!(r.outcome.is_none()); + json(&r); + } + + /// Malformed requests are `error` with `kind` and `op` null. + #[tokio::test] + async fn malformed_requests_are_errors() { + let gcd = r#"{"BigIntGcd":{"a":"12","b":"18"}}"#; + let cases = [ + "{not json".to_string(), + "[]".to_string(), + request("Math", gcd).replace(REQUEST_SCHEMA, "echidna.coprocessor.request/9"), + request("NoSuchKind", gcd), + request("Math", r#"{"NoSuchOp":{}}"#), + request("Math", r#"{"BigIntGcd":{"a":"12"}}"#), + request("Math", gcd).replacen('{', r#"{"extra":1,"#, 1), + r#"{"schema":"echidna.coprocessor.request/1","kind":"Math"}"#.to_string(), + ]; + for c in cases { + let r = dispatch_request(&c).await; + assert_eq!(r.status, CoprocessorStatus::Error, "{c}"); + assert_eq!(r.kind, None, "{c}"); + assert_eq!(r.op, None, "{c}"); + assert!(!r.message.is_empty(), "{c}"); + json(&r); + } + } + + /// An op of another kind is `error`, not `declined`. + #[tokio::test] + async fn op_of_another_kind_is_an_error() { + let r = dispatch_request(&request("Math", r#"{"VectorNorm":{"a":[3.0,4.0]}}"#)).await; + assert_eq!(r.status, CoprocessorStatus::Error); + assert!(r.message.contains("does not belong"), "{}", r.message); + assert!(r.outcome.is_none()); + json(&r); + } + + /// A non-finite float in an outcome is `error`, and `to_jcs` refuses it. + #[test] + fn non_finite_outcome_is_an_error() { + let facts = BackendFacts { + tier: CoprocessorTrustTier::LibraryWrapped, + deterministic: true, + }; + for o in [ + CoprocessorOutcome::Float(f64::NAN), + CoprocessorOutcome::FloatVec(vec![1.0, f64::INFINITY]), + CoprocessorOutcome::FloatMatrix(vec![vec![f64::NEG_INFINITY]]), + ] { + let mut r = + result_from_outcome(CoprocessorKind::Vector, "VectorNorm", o.clone(), facts, 1); + assert_eq!(r.status, CoprocessorStatus::Error); + assert!(r.outcome.is_none()); + json(&r); + r.outcome = Some(o); + assert!(r.to_jcs().is_err()); + } + } + + /// The allow-list is exactly the in-process kinds named by the contract. + #[test] + fn allow_list_is_exact() { + use CoprocessorKind::*; + let mut expected = vec![Math, Vector, Tensor, Crypto, Dsp, Physics]; + if cfg!(feature = "flint") { + expected.push(FlintMath); + } + let mut got = EXPOSED_KINDS.to_vec(); + got.sort_by_key(|k| *k as u8); + expected.sort_by_key(|k| *k as u8); + assert_eq!(got, expected); + for k in [ + Io, Graphics, Audio, Fpga, PariGp, Maxima, Singular, Gap, Macaulay2, + ] { + assert!(!is_exposed(k), "{k:?}"); + } + } + + /// `ALL_KINDS` lists every variant once. + #[test] + fn all_kinds_is_complete() { + /// Fails to compile when a variant is added and not handled here. + fn listed(k: CoprocessorKind) -> bool { + use CoprocessorKind::*; + match k { + Math | Vector | Tensor | Crypto | Physics | FlintMath | Dsp | Io | Graphics + | Audio | Fpga | PariGp | Maxima | Singular | Gap | Macaulay2 => { + ALL_KINDS.contains(&k) + }, + } + } + let tags: Vec = ALL_KINDS.iter().map(|k| *k as u8).collect(); + assert_eq!(tags, (0..16).collect::>()); + assert!(ALL_KINDS.iter().all(|k| listed(*k))); + } + + /// No status spells a proof claim, and every status but `computed` exits non-zero. + #[test] + fn status_vocabulary_is_closed_and_hint_only() { + let names: Vec<&str> = CoprocessorStatus::ALL.iter().map(|s| s.as_str()).collect(); + assert_eq!(names, ["computed", "declined", "unavailable", "error"]); + for s in CoprocessorStatus::ALL { + assert_eq!(serde_json::to_value(s).unwrap(), s.as_str()); + assert_eq!(s.exit_code() == 0, s == CoprocessorStatus::Computed); + } + assert_eq!(serde_json::to_value(NotAProof).unwrap(), Value::Bool(false)); + } + + /// The capabilities report has one sorted entry per kind and honours the allow-list. + #[test] + fn capabilities_cover_every_kind() { + let report = capabilities(); + let line = report.to_jcs().unwrap(); + let v: Value = serde_json::from_str(&line).unwrap(); + assert_eq!(v["schema"], CAPABILITIES_SCHEMA); + let kinds = v["kinds"].as_array().unwrap(); + assert_eq!(kinds.len(), ALL_KINDS.len()); + let names: Vec<&str> = kinds.iter().map(|k| k["kind"].as_str().unwrap()).collect(); + let mut sorted = names.clone(); + sorted.sort(); + assert_eq!(names, sorted); + for k in kinds { + let exposed = k["exposed"].as_bool().unwrap(); + if !exposed { + assert_eq!(k["available"], false, "{k}"); + assert!(k["trust"].is_null(), "{k}"); + assert!(k["supported_ops"].as_array().unwrap().is_empty(), "{k}"); + } else if k["available"] == true { + assert_eq!(k["trust"]["proof"], false, "{k}"); + assert!(!k["supported_ops"].as_array().unwrap().is_empty(), "{k}"); + } + } + let math = kinds.iter().find(|k| k["kind"] == "Math").unwrap(); + assert_eq!(math["available"], true); + } +} diff --git a/src/rust/lib.rs b/src/rust/lib.rs index ec514d67..a6da04a7 100644 --- a/src/rust/lib.rs +++ b/src/rust/lib.rs @@ -9,7 +9,8 @@ pub mod agent; pub mod anomaly_detection; pub mod aspect; -pub mod coprocessor; // Math/Physics/DSP/FPGA/Tensor/Vector/Crypto/Graphics/Audio/IO compute (Phase 0: Math) +pub mod coprocessor; // Computation backends behind the Coprocessor trait (16 kinds; FlintMath needs --features flint) +pub mod coprocessor_contract; // `echidna coprocessor`: the echidna.coprocessor.result/1 producer pub mod corpus; // Project-corpus indexer (named decls + dependency DAG; first adapter: Agda) // `core` and `types` live in the `echidna-core` crate so vcl-ut and other // proof-exchange clients can consume the canonical Term / Goal / ProofState / diff --git a/src/rust/main.rs b/src/rust/main.rs index 7508555c..72817c6c 100644 --- a/src/rust/main.rs +++ b/src/rust/main.rs @@ -24,14 +24,14 @@ async fn main() -> Result<()> { // Parse CLI arguments let cli = Cli::parse(); - // Initialize tracing. With `prove --output json`, stdout carries only the - // result object, so logs go to stderr. + // Initialize tracing. With `prove --output json` and `coprocessor`, + // stdout carries only the contract object, so logs go to stderr. let json_stdout = matches!( cli.command, Commands::Prove { output: ProveOutput::Json, .. - } + } | Commands::Coprocessor { .. } ); init_tracing(cli.verbose, json_stdout); @@ -155,6 +155,10 @@ async fn main() -> Result<()> { design_command(op, &formatter).await?; }, + Commands::Coprocessor { op } => { + coprocessor_command(op).await; + }, + Commands::Suggest { target, prover, diff --git a/tests/coprocessor_output_json.rs b/tests/coprocessor_output_json.rs new file mode 100644 index 00000000..d3a300c0 --- /dev/null +++ b/tests/coprocessor_output_json.rs @@ -0,0 +1,169 @@ +// SPDX-License-Identifier: MPL-2.0 + +//! End-to-end tests of `echidna coprocessor` (the +//! `echidna.coprocessor.*/1` contract) against the real binary. +//! +//! Every exposed backend runs in process, so no external program is needed. +//! The `declined` case is `VectorAdd` on vectors of different length, which +//! `src/rust/coprocessor/vector.rs` answers with `Failure`. + +use serde_json::Value; +use std::io::Write; +use std::path::Path; +use std::process::{Command, Output, Stdio}; + +const GCD: &str = r#"{"schema":"echidna.coprocessor.request/1","kind":"Math","op":{"BigIntGcd":{"a":"12","b":"18"}}}"#; + +/// Run the echidna binary with `args` in `dir`, feeding `stdin`. +fn echidna(dir: &Path, args: &[&str], stdin: &str) -> Output { + let mut child = Command::new(env!("CARGO_BIN_EXE_echidna")) + .current_dir(dir) + .args(args) + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .expect("run echidna"); + child + .stdin + .take() + .unwrap() + .write_all(stdin.as_bytes()) + .unwrap(); + child.wait_with_output().expect("wait for echidna") +} + +/// Dispatch `request` on stdin. +fn dispatch(request: &str) -> Output { + let dir = tempfile::tempdir().unwrap(); + echidna(dir.path(), &["coprocessor", "dispatch"], request) +} + +/// Assert stdout is exactly one JCS line and return it parsed. +fn one_line(out: &Output, schema: &str) -> Value { + let stdout = String::from_utf8(out.stdout.clone()).expect("stdout is UTF-8"); + assert!(stdout.ends_with('\n'), "one final newline: {stdout:?}"); + assert_eq!( + stdout.matches('\n').count(), + 1, + "exactly one line: {stdout:?}" + ); + let line = stdout.trim_end_matches('\n'); + let v: Value = serde_json::from_str(line).unwrap_or_else(|e| panic!("{e}: {stdout:?}")); + assert_eq!( + serde_json_canonicalizer::to_string(&v).unwrap(), + line, + "the line is its own JCS form" + ); + assert_eq!(v["schema"], schema); + assert_eq!(v["echidna_version"], env!("CARGO_PKG_VERSION")); + v +} + +/// Assert the result contract and return the parsed object. +fn result(out: &Output) -> Value { + let v = one_line(out, "echidna.coprocessor.result/1"); + assert_eq!(v["trust"]["proof"], Value::Bool(false), "{v}"); + v +} + +/// gcd(12, 18) on stdin is `computed`, outcome `{"BigInt":"6"}`, exit 0. +#[test] +fn gcd_from_stdin_is_computed() { + let out = dispatch(GCD); + let v = result(&out); + assert_eq!(v["status"], "computed"); + assert_eq!(v["outcome"], serde_json::json!({"BigInt": "6"})); + assert_eq!(v["kind"], "Math"); + assert_eq!(v["op"], "BigIntGcd"); + assert_eq!(v["trust"]["tier"], "LibraryWrapped"); + assert_eq!(v["deterministic"], true); + assert_eq!(out.status.code(), Some(0)); +} + +/// `--request FILE` gives the same answer as stdin. +#[test] +fn gcd_from_request_file_is_computed() { + let dir = tempfile::tempdir().unwrap(); + std::fs::write(dir.path().join("req.json"), GCD).unwrap(); + let out = echidna( + dir.path(), + &["coprocessor", "dispatch", "--request", "req.json"], + "", + ); + let v = result(&out); + assert_eq!(v["status"], "computed"); + assert_eq!(v["outcome"], serde_json::json!({"BigInt": "6"})); + assert_eq!(out.status.code(), Some(0)); +} + +/// A backend `Failure` is `declined` and exits 1. +#[test] +fn length_mismatch_is_declined() { + let out = dispatch( + r#"{"schema":"echidna.coprocessor.request/1","kind":"Vector","op":{"VectorAdd":{"a":[1.0,2.0],"b":[1.0]}}}"#, + ); + let v = result(&out); + assert_eq!(v["status"], "declined"); + assert!(v["outcome"]["Failure"].is_string(), "{v}"); + assert!(!v["message"].as_str().unwrap().is_empty()); + assert_eq!(out.status.code(), Some(1)); +} + +/// A kind outside the allow-list is `unavailable` and exits 1. +#[test] +fn io_kind_is_unavailable() { + let out = dispatch( + r#"{"schema":"echidna.coprocessor.request/1","kind":"Io","op":{"IoLineCount":{"path":"/etc/passwd"}}}"#, + ); + let v = result(&out); + assert_eq!(v["status"], "unavailable"); + assert!(v["outcome"].is_null()); + assert!(v["trust"]["tier"].is_null()); + assert_eq!(out.status.code(), Some(1)); +} + +/// Malformed input, an unreadable file, and an op of another kind are `error`, exit 1. +#[test] +fn malformed_input_is_an_error() { + for (input, op_null) in [ + ("{not json", true), + ("", true), + ( + r#"{"schema":"echidna.coprocessor.request/1","kind":"Math","op":{"VectorNorm":{"a":[3.0]}}}"#, + false, + ), + ] { + let out = dispatch(input); + let v = result(&out); + assert_eq!(v["status"], "error", "{input}"); + assert_eq!(v["op"].is_null(), op_null, "{input}: {v}"); + assert_eq!(out.status.code(), Some(1), "{input}"); + } + let dir = tempfile::tempdir().unwrap(); + let out = echidna( + dir.path(), + &["coprocessor", "dispatch", "--request", "missing.json"], + "", + ); + assert_eq!(result(&out)["status"], "error"); + assert_eq!(out.status.code(), Some(1)); +} + +/// `capabilities` prints one line with one entry per kind, and exits 0. +#[test] +fn capabilities_list_every_kind() { + let dir = tempfile::tempdir().unwrap(); + let out = echidna(dir.path(), &["coprocessor", "capabilities"], ""); + let v = one_line(&out, "echidna.coprocessor.capabilities/1"); + let kinds = v["kinds"].as_array().unwrap(); + assert_eq!(kinds.len(), 16); + let io = kinds.iter().find(|k| k["kind"] == "Io").unwrap(); + assert_eq!(io["exposed"], false); + assert_eq!(io["available"], false); + let math = kinds.iter().find(|k| k["kind"] == "Math").unwrap(); + assert_eq!(math["exposed"], true); + assert_eq!(math["available"], true); + assert_eq!(math["trust"]["proof"], false); + assert_eq!(out.status.code(), Some(0)); +} From 91dc9a10e21d12b81f1710d986f8bf563c97a7da Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 11:37:33 +0000 Subject: [PATCH 2/2] fix(coprocessor): refuse a request whose kind is not a JSON string The contract defines `kind` as a string. serde also reads a unit enum variant from the object form, so `{"Math":null}` reached dispatch and gave status computed. The parser now refuses any non-string `kind` with status error. The malformed-request test gains two cases (the object form and a number). The object-form case failed before this change (status was Computed) and passes now. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_0136P7Zmp1i8PGVHkq3u2iNz --- src/rust/coprocessor_contract.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/rust/coprocessor_contract.rs b/src/rust/coprocessor_contract.rs index 0b67ae84..8f26c433 100644 --- a/src/rust/coprocessor_contract.rs +++ b/src/rust/coprocessor_contract.rs @@ -364,6 +364,11 @@ pub fn parse_request(input: &str) -> Result { None => return Err("missing key `schema`".into()), } let kind_v = map.get("kind").ok_or("missing key `kind`")?; + // The contract says `kind` is a string. serde would also read a unit + // variant from the object form (`{"Math":null}`), so refuse it here. + if !kind_v.is_string() { + return Err("`kind` must be a string".into()); + } let kind: CoprocessorKind = serde_json::from_value(kind_v.clone()) .map_err(|e| format!("unknown kind {kind_v}: {e}"))?; let op_v = map.get("op").ok_or("missing key `op`")?; @@ -662,7 +667,12 @@ mod tests { request("Math", r#"{"BigIntGcd":{"a":"12"}}"#), request("Math", gcd).replacen('{', r#"{"extra":1,"#, 1), r#"{"schema":"echidna.coprocessor.request/1","kind":"Math"}"#.to_string(), + // `kind` must be a JSON string. serde also reads a unit variant + // from the object form, so the parser must refuse it itself. + request("Math", gcd).replace(r#""kind":"Math""#, r#""kind":{"Math":null}"#), + request("Math", gcd).replace(r#""kind":"Math""#, r#""kind":7"#), ]; + assert!(cases[8].contains(r#""kind":{"Math":null}"#), "{}", cases[8]); for c in cases { let r = dispatch_request(&c).await; assert_eq!(r.status, CoprocessorStatus::Error, "{c}");