diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 6afa75ef..935d66a7 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -10,6 +10,10 @@ https://semver.org/spec/v2.0.0.html[Semantic Versioning]. ==== Added +* `scripts/bactrian/doctor.sh` probes the ECHIDNA coprocessor contract + (echidna pull request 524, not merged). One optional row reports present, + unavailable or drift. It is a hint channel, never proof evidence, and it + never changes the preflight result or exit code. * **Chain minting: a minted repo can be minted again.** "Use this template" on a minted repo now mints correctly (owner ruling 2026-11-04, after the Codex review of #251 showed the grandchild inherited its parent's identity). diff --git a/docs/plan/ULTRAPLAN.adoc b/docs/plan/ULTRAPLAN.adoc index d1f8c9ea..cd044dec 100644 --- a/docs/plan/ULTRAPLAN.adoc +++ b/docs/plan/ULTRAPLAN.adoc @@ -32,7 +32,7 @@ waves W0 to W5 come from that plan. | B0 | WP-00A: the maintainer decides that this repository is the product repository, not a customised template. The README now describes the product. The deed still has UNASSIGNED fields. | Owner (F2) | B1 | The 8 upstream authorities in `.machine_readable/bactrian/authorities.lock` are UNPINNED. | Lead, WP-00 | B2 | `mise.toml` lists Zig as `latest`, not a fixed version. Idris2 is not in it: it comes from pack. OCaml, Dune, Why3, Apalache, Dedukti, Coq and Lean have no source and no pin. | Lead, WP-00, F6 -| B3 | The ECHIDNA call interface was recorded as unknown. It is known now: `echidna prove --output json`, schema `echidna.prove.result/1`. That command checks one backend and verifies no certificate, so its result alone is not replay evidence (see "Replay" below). | Interface known; replay path open (B-2) +| B3 | The ECHIDNA call interface was recorded as unknown. It is known now: `echidna prove --output json`, schema `echidna.prove.result/1`. That command checks one backend and verifies no certificate, so its result alone is not replay evidence (see "Replay" below). The preflight also probes the ECHIDNA coprocessor contract (`echidna coprocessor capabilities` and `dispatch`). The contract is in the unmerged echidna pull request 524. The probe is a hint channel and no proof evidence. Its row is optional and never changes the preflight result. | Interface known; replay path open (B-2) |=== == Definition of v1.0.0 diff --git a/scripts/bactrian/doctor.sh b/scripts/bactrian/doctor.sh index b2d7fd5f..5012f92f 100755 --- a/scripts/bactrian/doctor.sh +++ b/scripts/bactrian/doctor.sh @@ -59,6 +59,95 @@ else missing 'BACTRIAN_ECHIDNA_CMD is unset (ECHIDNA CLI/API adapter is not selected)' fi +# ECHIDNA coprocessor contract probe. OPTIONAL HINT CHANNEL: this row never +# changes $blockers or the exit code. A blocked preflight stays blocked and a +# present coprocessor unblocks nothing. An answer is a hint, never a proof, so +# a result that carries "proof":true is reported as drift, never as present. +# The contract is echidna pull request 524 (not merged when this was written). +# Output is JCS, so exact substring checks on the single line are sound: +# inside a JSON string a quote is always written backslash-quote, so the raw +# text "proof":true or "proof":false can only be a key with its value, never +# part of a message string. The check is fail-closed: "proof":true anywhere in +# the line gives drift, so a result is never present with a true proof flag. +# Limit: it does not prove the false sits under "trust" (the contract key +# trust.proof is the key proof inside the object trust), and an additive +# contract change can cause a false drift report on this optional row. The +# shared client in the evidence kit will parse the JSON; this pilot stays +# dependency-free (no jq). +# A preflight must never hang, so the probe runs only when timeout exists. +cop_out='' +cop_status=0 +# Run "$@" under timeout (the caller has checked that it exists). Set cop_out to the stdout +# (trailing newline kept, via the sentinel) and cop_status to the exit code. +cop_run() { + cop_out=$(timeout 20 "$@" 2>/dev/null; printf 'x%s' "$?") + cop_status=${cop_out##*x} + cop_out=${cop_out%x*} +} +# True when cop_out is exactly one line ending in a single newline. +cop_one_line() { + local body=${cop_out%$'\n'} + [[ "$cop_out" == *$'\n' && -n "$body" && "$body" != *$'\n'* ]] +} +# Print the not-present row with reason $1. The [optional] marker is used for +# every outcome of this row because the row is never counted as ready or blocked. +cop_report() { + printf ' [optional] ECHIDNA coprocessor %s (optional; does not change the preflight result)\n' "$1" +} +# Probe the contract. Print exactly one row. Never touch $blockers. +probe_coprocessor() { + local request='{"schema":"echidna.coprocessor.request/1","kind":"Math","op":{"BigIntGcd":{"a":"12","b":"18"}}}' + if ! command -v echidna >/dev/null 2>&1; then + cop_report 'unavailable: no echidna on PATH' + return 0 + fi + if ! command -v timeout >/dev/null 2>&1; then + cop_report 'unavailable: no timeout tool, probe not run' + return 0 + fi + cop_run echidna coprocessor capabilities + if [[ "$cop_status" -ne 0 && "$cop_out" != *'{'* ]]; then + cop_report 'unavailable: echidna has no coprocessor subcommand' + return 0 + fi + if [[ "$cop_status" -ne 0 ]]; then + cop_report "failed: capabilities exited $cop_status" + return 0 + fi + if ! cop_one_line; then + cop_report 'failed: capabilities did not print exactly one line' + return 0 + fi + if [[ "$cop_out" != *'"schema":"echidna.coprocessor.capabilities/1"'* ]]; then + cop_report 'drift: capabilities schema is not echidna.coprocessor.capabilities/1' + return 0 + fi + cop_run echidna coprocessor dispatch <<<"$request" + if [[ "$cop_status" -ne 0 ]]; then + cop_report "failed: dispatch exited $cop_status" + return 0 + fi + if ! cop_one_line; then + cop_report 'failed: dispatch did not print exactly one line' + return 0 + fi + if [[ "$cop_out" == *'"proof":true'* ]]; then + cop_report 'drift: result claims "proof":true (a hint is never a proof)' + elif [[ "$cop_out" != *'"schema":"echidna.coprocessor.result/1"'* ]]; then + cop_report 'drift: result schema is not echidna.coprocessor.result/1' + elif [[ "$cop_out" != *'"status":"computed"'* ]]; then + cop_report 'drift: result status is not computed' + elif [[ "$cop_out" != *'"outcome":{"BigInt":"6"}'* ]]; then + cop_report 'drift: gcd(12,18) outcome is not {"BigInt":"6"}' + elif [[ "$cop_out" != *'"proof":false'* ]]; then + cop_report 'drift: result lacks "proof":false' + else + printf ' [optional] ECHIDNA coprocessor present (hint channel only; no proof status; does not change the preflight result)\n' + fi + return 0 +} +probe_coprocessor + printf '\nCanonical authority lock syntax (this does not verify artifacts):\n' lock="$ROOT/.machine_readable/bactrian/authorities.lock" if [[ ! -f "$lock" ]]; then diff --git a/tests/bactrian/doctor_test.sh b/tests/bactrian/doctor_test.sh index 77a62d13..68f138e0 100755 --- a/tests/bactrian/doctor_test.sh +++ b/tests/bactrian/doctor_test.sh @@ -115,4 +115,119 @@ grep -v '^MPR' "$tmp/valid.lock" >>"$lock" printf 'MPR\t%s\t%s' "$revision" "$digest" >>"$lock" run_doctor 0 + +# ECHIDNA coprocessor probe: an optional hint row that never changes the result. +# A fake echidna comes first on PATH; the fixture tools follow it. +real_timeout=$(command -v timeout || true) # Linked in only after the no-timeout case. +rm "$tmp/bin/echidna" # Each case below supplies its own fake, or none. +caps='{"schema":"echidna.coprocessor.capabilities/1"}' +good='{"schema":"echidna.coprocessor.result/1","status":"computed","outcome":{"BigInt":"6"},"proof":false}' + +# Run doctor with a fake echidna. $1 is the fake's body, "none" for no echidna. +run_cop() { + local body=$1 dir status + if [[ "$body" == none ]]; then + dir="$tmp/bin" + else + dir="$tmp/fake" + rm -rf "$dir" + mkdir -p "$dir" + printf '#!/bin/sh\n%s\n' "$body" >"$dir/echidna" + chmod +x "$dir/echidna" + dir="$dir:$tmp/bin" + fi + if output=$(PATH="$dir" BACTRIAN_ECHIDNA_CMD="$tmp/bin/tool" "$bash_cmd" "$fixture_doctor" 2>&1); then + status=0 + else + status=$? + fi + cop_status=$status + cop_row=$(grep 'ECHIDNA coprocessor' <<<"$output") + without_row=$(grep -v 'ECHIDNA coprocessor' <<<"$output") +} +# A fake that answers per subcommand: $1 capabilities output, $2 dispatch output. +fake() { + printf 'case "$2" in capabilities) %s;; dispatch) read -r _; %s;; *) exit 2;; esac' "$1" "$2" +} +require_row() { # $1 pattern that the row must match + grep -Fq "[optional]" <<<"$cop_row" || { printf "row lacks [optional]:\n%s\n" "$cop_row" >&2; exit 1; } + grep -Fq -- "$1" <<<"$cop_row" || { printf 'row lacks %s:\n%s\n' "$1" "$cop_row" >&2; exit 1; } +} +forbid_present() { + if grep -Fq -e "[ready]" -e "[blocked]" <<<"$cop_row"; then + printf "row uses a counted marker:\n%s\n" "$cop_row" >&2; exit 1 + fi + if grep -q 'coprocessor present' <<<"$cop_row"; then + printf 'must not be present:\n%s\n' "$cop_row" >&2; exit 1 + fi +} + +# Baselines: the overall result without a coprocessor, ready and blocked. +run_cop none; require_row 'unavailable: no echidna on PATH' +ready_status=$cop_status; ready_rest=$without_row +[[ "$ready_status" -eq 0 ]] +mv "$tmp/src/driver/status.ml" "$tmp/module.ml" +run_cop none +blocked_status=$cop_status; blocked_rest=$without_row +[[ "$blocked_status" -eq 2 ]] +mv "$tmp/module.ml" "$tmp/src/driver/status.ml" + +same_result() { # the row must change neither the exit code nor any other line + run_cop "$1" + [[ "$cop_status" -eq "$ready_status" && "$without_row" == "$ready_rest" ]] || { printf 'ready result changed:\n%s\n' "$output" >&2; exit 1; } + mv "$tmp/src/driver/status.ml" "$tmp/module.ml" + run_cop "$1" + mv "$tmp/module.ml" "$tmp/src/driver/status.ml" + [[ "$cop_status" -eq "$blocked_status" && "$without_row" == "$blocked_rest" ]] || { printf 'blocked result changed:\n%s\n' "$output" >&2; exit 1; } + run_cop "$1" +} + +# No timeout tool on PATH: the probe must not run, even with a fake echidna present. +marker="$tmp/echidna-called" +rm -f "$marker" +same_result "$(fake ": >\"$marker\"; printf '%s\\n' '$caps'" ": >\"$marker\"; printf '%s\\n' '$good'")" +require_row 'unavailable: no timeout tool, probe not run'; forbid_present +[[ ! -e "$marker" ]] || { printf 'the fake echidna was called without timeout\n' >&2; exit 1; } +if [[ -z "$real_timeout" ]]; then + printf 'PASS (no timeout tool here: the timeout-dependent probe cases were skipped).\n' + exit 0 +fi +ln -s "$real_timeout" "$tmp/bin/timeout" + +# (a) correct answers: present. +same_result "$(fake "printf '%s\\n' '$caps'" "printf '%s\\n' '$good'")" +require_row '[optional]'; require_row 'coprocessor present'; require_row 'no proof status' +! grep -Fq -e "[ready]" -e "[blocked]" <<<"$cop_row" +# (b) no echidna: unavailable. +same_result none; require_row 'unavailable: no echidna on PATH'; forbid_present +# (c) echidna without the subcommand: unavailable, never present. +same_result 'echo "error: unrecognized subcommand" >&2; exit 2' +require_row 'unavailable: echidna has no coprocessor subcommand'; forbid_present +# (d) wrong schemas: drift. +same_result "$(fake "printf '%s\\n' '$caps'" "printf '%s\\n' '${good/result\/1/result\/2}'")" +require_row 'drift: result schema'; forbid_present +same_result "$(fake "printf '%s\\n' '${caps/capabilities\/1/capabilities\/2}'" "printf '%s\\n' '$good'")" +require_row 'drift: capabilities schema'; forbid_present +# Wrong status, wrong outcome, non-zero exit on the request: never present. +same_result "$(fake "printf '%s\\n' '$caps'" "printf '%s\\n' '${good/computed/refused}'")" +require_row 'drift: result status'; forbid_present +same_result "$(fake "printf '%s\\n' '$caps'" "printf '%s\\n' '${good/\"6\"/\"7\"}'")" +require_row 'drift: gcd'; forbid_present +same_result "$(fake "printf '%s\\n' '$caps'" "printf '%s\\n' '$good'; exit 1")" +require_row 'failed: dispatch exited 1'; forbid_present +# (e) "proof":true is never present, even when everything else is right. +same_result "$(fake "printf '%s\\n' '$caps'" "printf '%s\\n' '${good/\"proof\":false/\"proof\":true}'")" +require_row 'drift: result claims "proof":true'; forbid_present +# (f) two stdout lines are never present. +same_result "$(fake "printf '%s\\n' '$caps'" "printf '%s\\n%s\\n' '$good' '$good'")" +require_row 'failed: dispatch did not print exactly one line'; forbid_present +same_result "$(fake "printf '%s\\n%s\\n' '$caps' '$caps'" "printf '%s\\n' '$good'")" +require_row 'failed: capabilities did not print exactly one line'; forbid_present +# A present coprocessor never unblocks anything: BLOCKED output stays blocked. +mv "$tmp/src/driver/status.ml" "$tmp/module.ml" +run_cop "$(fake "printf '%s\\n' '$caps'" "printf '%s\\n' '$good'")" +mv "$tmp/module.ml" "$tmp/src/driver/status.ml" +[[ "$cop_status" -eq 2 ]]; require_row 'coprocessor present' +grep -q 'Preflight BLOCKED' <<<"$output" + printf 'PASS: Bactrian doctor checks controlled blocked/ready fixtures and rejects malformed locks.\n'