From 5ed7c1eb33b27cbb24e28723c1af6ad8359f90a3 Mon Sep 17 00:00:00 2001 From: CLAUDE <355856132+HoTT-stuff@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:26:44 +0000 Subject: [PATCH 1/4] feat(doctor): probe the ECHIDNA coprocessor contract (optional hint row) Co-Authored-By: Claude Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_0136P7Zjt3z72sTD8z7uGtnb --- CHANGELOG.adoc | 4 ++ docs/plan/ULTRAPLAN.adoc | 2 +- scripts/bactrian/doctor.sh | 79 ++++++++++++++++++++++++++++ tests/bactrian/doctor_test.sh | 98 +++++++++++++++++++++++++++++++++++ 4 files changed, 182 insertions(+), 1 deletion(-) 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..0da07e39 100755 --- a/scripts/bactrian/doctor.sh +++ b/scripts/bactrian/doctor.sh @@ -59,6 +59,85 @@ 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. +cop_out='' +cop_status=0 +# Run "$@" with a time limit when timeout exists. Set cop_out to the stdout +# (trailing newline kept, via the sentinel) and cop_status to the exit code. +cop_run() { + if command -v timeout >/dev/null 2>&1; then + cop_out=$(timeout 20 "$@" 2>/dev/null; printf 'x%s' "$?") + else + cop_out=$("$@" 2>/dev/null; printf 'x%s' "$?") + fi + 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. +# [blocked] here is a report word only; it is not counted (see above). +cop_report() { + printf ' [blocked] 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 + 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 ' [ready] 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..88100945 100755 --- a/tests/bactrian/doctor_test.sh +++ b/tests/bactrian/doctor_test.sh @@ -115,4 +115,102 @@ 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. +ln -s "$(command -v timeout)" "$tmp/bin/timeout" +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 -- "$1" <<<"$cop_row" || { printf 'row lacks %s:\n%s\n' "$1" "$cop_row" >&2; exit 1; } +} +forbid_present() { + 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" +} + +# (a) correct answers: present. +same_result "$(fake "printf '%s\\n' '$caps'" "printf '%s\\n' '$good'")" +require_row '[ready]'; require_row 'coprocessor present'; require_row 'no proof status' +# (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' From 7c67025efa9b4d7586107ab8cdce078ddf893a6e Mon Sep 17 00:00:00 2001 From: CLAUDE <355856132+HoTT-stuff@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:28:11 +0000 Subject: [PATCH 2/4] fix(doctor): mark the coprocessor row [optional] The row is never counted, so [ready] and [blocked] misread as counted. Co-Authored-By: Claude Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_0136P7Zjt3z72sTD8z7uGtnb --- scripts/bactrian/doctor.sh | 8 ++++---- tests/bactrian/doctor_test.sh | 7 ++++++- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/scripts/bactrian/doctor.sh b/scripts/bactrian/doctor.sh index 0da07e39..65b027cc 100755 --- a/scripts/bactrian/doctor.sh +++ b/scripts/bactrian/doctor.sh @@ -83,10 +83,10 @@ cop_one_line() { local body=${cop_out%$'\n'} [[ "$cop_out" == *$'\n' && -n "$body" && "$body" != *$'\n'* ]] } -# Print the not-present row with reason $1. -# [blocked] here is a report word only; it is not counted (see above). +# 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 ' [blocked] ECHIDNA coprocessor %s (optional; does not change the preflight result)\n' "$1" + 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() { @@ -132,7 +132,7 @@ probe_coprocessor() { elif [[ "$cop_out" != *'"proof":false'* ]]; then cop_report 'drift: result lacks "proof":false' else - printf ' [ready] ECHIDNA coprocessor present (hint channel only; no proof status; does not change the preflight result)\n' + printf ' [optional] ECHIDNA coprocessor present (hint channel only; no proof status; does not change the preflight result)\n' fi return 0 } diff --git a/tests/bactrian/doctor_test.sh b/tests/bactrian/doctor_test.sh index 88100945..342d1238 100755 --- a/tests/bactrian/doctor_test.sh +++ b/tests/bactrian/doctor_test.sh @@ -150,9 +150,13 @@ 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 @@ -180,7 +184,8 @@ same_result() { # the row must change neither the exit code nor any other line # (a) correct answers: present. same_result "$(fake "printf '%s\\n' '$caps'" "printf '%s\\n' '$good'")" -require_row '[ready]'; require_row 'coprocessor present'; require_row 'no proof status' +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. From 3b3dc5a57d0e4d61dfe84304d230a897bf557c70 Mon Sep 17 00:00:00 2001 From: CLAUDE <355856132+HoTT-stuff@users.noreply.github.com> Date: Thu, 19 Nov 2026 03:15:10 +0000 Subject: [PATCH 3/4] test(doctor): link timeout only when it exists Co-Authored-By: Claude Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_0136P7Zjt3z72sTD8z7uGtnb --- tests/bactrian/doctor_test.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/bactrian/doctor_test.sh b/tests/bactrian/doctor_test.sh index 342d1238..7a90e86c 100755 --- a/tests/bactrian/doctor_test.sh +++ b/tests/bactrian/doctor_test.sh @@ -118,7 +118,7 @@ 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. -ln -s "$(command -v timeout)" "$tmp/bin/timeout" +if command -v timeout >/dev/null 2>&1; then ln -s "$(command -v timeout)" "$tmp/bin/timeout"; fi 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}' From df8fa213049f309c3258c19083a87e145bc5ab9f Mon Sep 17 00:00:00 2001 From: CLAUDE <355856132+HoTT-stuff@users.noreply.github.com> Date: Thu, 19 Nov 2026 03:16:30 +0000 Subject: [PATCH 4/4] fix(doctor): do not run the coprocessor probe without timeout A preflight must never hang, and the row is optional, so report it as unavailable when no timeout tool exists. Document why the substring checks on the JCS line stay. Co-Authored-By: Claude Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_0136P7Zjt3z72sTD8z7uGtnb --- scripts/bactrian/doctor.sh | 24 +++++++++++++++++------- tests/bactrian/doctor_test.sh | 14 +++++++++++++- 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/scripts/bactrian/doctor.sh b/scripts/bactrian/doctor.sh index 65b027cc..5012f92f 100755 --- a/scripts/bactrian/doctor.sh +++ b/scripts/bactrian/doctor.sh @@ -64,17 +64,23 @@ fi # 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. +# 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 "$@" with a time limit when timeout exists. Set cop_out to the stdout +# 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() { - if command -v timeout >/dev/null 2>&1; then - cop_out=$(timeout 20 "$@" 2>/dev/null; printf 'x%s' "$?") - else - cop_out=$("$@" 2>/dev/null; printf 'x%s' "$?") - fi + cop_out=$(timeout 20 "$@" 2>/dev/null; printf 'x%s' "$?") cop_status=${cop_out##*x} cop_out=${cop_out%x*} } @@ -95,6 +101,10 @@ probe_coprocessor() { 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' diff --git a/tests/bactrian/doctor_test.sh b/tests/bactrian/doctor_test.sh index 7a90e86c..68f138e0 100755 --- a/tests/bactrian/doctor_test.sh +++ b/tests/bactrian/doctor_test.sh @@ -118,7 +118,7 @@ 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. -if command -v timeout >/dev/null 2>&1; then ln -s "$(command -v timeout)" "$tmp/bin/timeout"; fi +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}' @@ -182,6 +182,18 @@ same_result() { # the row must change neither the exit code nor any other line 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'