stegobench-plugin 1.0.0

The plugin protocol and the host that runs plugins
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
// Author:  Daniel Iwugo
// Comment: Christ is King
// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright (C) 2026 Daniel Iwugo
//! Can this tool be run on this machine, and do we know that it works?
//!
//! THE DISTINCTION THIS FILE REFUSES TO BLUR
//! -----------------------------------------
//! **Present is not working.** An image can be pulled, a binary can be on
//! PATH, and the tool can still produce nothing: the rich-model extractor did
//! exactly that over 2,000 images, exiting zero the whole way, because Octave
//! Forge packages were missing and Aletheia catches that error per image.
//!
//! So [`Presence`] answers "is it here" and says plainly that it has not
//! answered "does it work". `doctor` prints both states separately and never
//! lets the first stand in for the second, because a machine reported healthy
//! by a check that cannot fail is worse than one nobody checked.
//!
//! WHAT "HERE" MEANS, WHICH IS NOT ALWAYS THE SAME THING
//! ----------------------------------------------------
//! Presence asks about the program a run would actually launch, and for the
//! three routes that is three different programs: a container image, a binary
//! on PATH, or, for a tool that is a SERVICE, the adapter script that posts to
//! it. An entry setting `invoke.host` names an image, but nothing ever runs
//! that image here, so asking the container runtime about it answers a
//! question no run poses. It used to, and the cost was exact: `score` refused
//! to start against a service running on another host until the user pulled an
//! image nothing would use, and `doctor` skipped the self-test, which is the
//! only check that would have proved the service answers at all.
//!
//! For a service, then, "here" is a narrower claim than usual. The adapter is
//! here and can be run, and an address has been supplied. Whether anything is
//! listening at that address is the self-test's question, and nothing in this
//! file goes and asks it.

use std::path::PathBuf;
use std::process::Command;
use std::time::Duration;

use stegobench_core::registry::{Entry, Invoke};

use crate::{binary_version, hash_file, which};

/// Whether the code a run would launch is on this machine.
///
/// Deliberately "the code a run would launch" rather than "the tool". For a
/// service the two differ: what runs here is the adapter, and the tool itself
/// is somewhere else entirely.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Presence {
    /// Here, and pinned to this exact version.
    Present { pin: String },
    /// Not here, with the reason a human can act on.
    Absent { reason: String },
    /// We could not find out, which is its own answer and must not be
    /// reported as either of the others.
    Unknown { reason: String },
    /// The entry says this tool does not run on this machine's operating
    /// system, so it is not missing and installing something will not help.
    ///
    /// A separate answer from Absent because the two ask different things of
    /// the reader. "Not installed" is an instruction; "cannot run here" is a
    /// fact about the machine, and reporting the second as the first sends
    /// somebody looking for a package that does not exist.
    Unsupported { reason: String },
}

impl Presence {
    pub fn is_present(&self) -> bool {
        matches!(self, Presence::Present { .. })
    }
}

/// What `doctor` knows about one tool.
#[derive(Debug, Clone, PartialEq)]
pub struct Availability {
    pub name: String,
    pub presence: Presence,
    /// Whether a self-test has actually been run. **Not yet implemented**, and
    /// the field is here so that its absence is visible in the output rather
    /// than being quietly equated with health.
    pub verified: Option<bool>,
    /// Environment variables the tool needs that are not set. Names only.
    pub missing_secrets: Vec<String>,
}

impl Availability {
    /// The one line `doctor` prints.
    pub fn summary(&self) -> String {
        let state = match &self.presence {
            Presence::Present { pin } => {
                let short: String = pin.chars().take(23).collect();
                format!("present   {short}")
            }
            Presence::Absent { reason } => format!("MISSING   {reason}"),
            Presence::Unknown { reason } => format!("unknown   {reason}"),
            Presence::Unsupported { reason } => format!("n/a       {reason}"),
        };
        let verified = match self.verified {
            Some(true) => "  verified",
            Some(false) => "  SELF TEST FAILED",
            None => "  not verified",
        };
        let secrets = if self.missing_secrets.is_empty() {
            String::new()
        } else {
            format!("  needs {}", self.missing_secrets.join(", "))
        };
        format!("{:<16} {state}{verified}{secrets}", self.name)
    }
}

/// How long the container runtime gets to answer whether an image is here.
///
/// Generous, because a daemon that has just started can be slow, and this is a
/// ceiling for the one that never answers rather than a budget for the one
/// that is busy.
const DOCKER_TIMEOUT: Duration = Duration::from_secs(20);

/// Is a container image already on this machine?
///
/// Shells out rather than talking to the daemon socket: the socket is a
/// privileged interface and a benchmark has no business holding one open.
fn image_present(reference: &str) -> Presence {
    // Asked before spawning, because the two cases need different sentences
    // and a spawn failure cannot tell them apart: `captured` reports its
    // error as a string, so "docker is not installed" and "docker is
    // installed and broke" arrive here identically. Only the second deserves
    // the runner's own words; the first deserves plain ones.
    if which("docker").is_none() {
        return Presence::Unknown {
            reason: "no container runtime: docker is not on PATH".to_string(),
        };
    }
    let mut cmd = Command::new("docker");
    cmd.args(["image", "inspect", "--format", "{{.Id}}", reference]);
    // Bounded, because a container daemon that has wedged answers nothing and
    // never closes the pipe either, and `Command::output()` would wait on that
    // for as long as the machine stays up. This runs inside `list`, `describe`
    // and `doctor`, so an unbounded wait here is the whole tool hanging on a
    // question it only asked in passing.
    let out = crate::exec::captured(cmd, "docker image inspect", DOCKER_TIMEOUT);
    match out {
        Ok(o) if o.status.success() => Presence::Present {
            pin: String::from_utf8_lossy(&o.stdout).trim().to_string(),
        },
        Ok(_) => Presence::Absent {
            reason: format!("not pulled. docker pull {reference}"),
        },
        // "Unknown" rather than "Absent", and it always was: not being able to
        // ask whether an image is here is a different answer from its not
        // being here, and only one of the two is fixed by pulling. The reason
        // is the runner's own sentence, which distinguishes a runtime that is
        // not installed from one that stopped answering.
        Err(e) => Presence::Unknown {
            reason: format!("could not ask the container runtime: {e}"),
        },
    }
}

/// Longer than the local one, because this one crosses a network and a
/// registry behind a slow link is a different thing from one that is down.
const REGISTRY_TIMEOUT: Duration = Duration::from_secs(45);

/// Whether a pinned image is actually obtainable, and how we know.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Reach {
    /// The registry served a manifest for this exact digest.
    Fetchable,
    /// The registry answered and does not have it. The reason is the runtime's
    /// own words, because "no such repository" and "you are not authorised"
    /// are different problems for whoever has to fix them.
    Absent { reason: String },
    /// Nobody asked, or the asking failed for a reason that isn't an answer:
    /// no runtime, no network, a timeout. Distinguished from `Absent` because
    /// a check that could not run must never read as a check that passed.
    NotRun { reason: String },
}

/// Can a third party obtain the bytes this run was pinned to?
///
/// A digest names bytes exactly and says nothing about where they are. Every
/// image this project pins was built locally and pushed nowhere, while the
/// result document, the help topic and the guide all told readers the digest
/// meant they could pull it. Anybody who tried got an access denied error, and
/// the run they were trying to reproduce was the one being quoted at them.
///
/// Scoring never asks this: it needs a network, and a sandboxed run has none
/// by design. So it's a separate question, asked when somebody needs the
/// answer, which is when they're about to disclose or publish a number.
///
/// `docker manifest inspect` fetches the manifest and nothing else, so this
/// costs a few kilobytes rather than the gigabytes a pull would.
pub fn registry_reach(reference: &str) -> Reach {
    if which("docker").is_none() {
        return Reach::NotRun {
            reason: "no container runtime: docker is not on PATH".to_string(),
        };
    }
    let mut cmd = Command::new("docker");
    cmd.args(["manifest", "inspect", reference]);
    match crate::exec::captured(cmd, "docker manifest inspect", REGISTRY_TIMEOUT) {
        Ok(o) if o.status.success() => Reach::Fetchable,
        Ok(o) => Reach::Absent {
            reason: refusal_reason(&String::from_utf8_lossy(&o.stderr)),
        },
        Err(e) => Reach::NotRun {
            reason: format!("could not ask the registry: {e}"),
        },
    }
}

/// The useful line out of a registry refusal.
///
/// The runtime prints a login hint above the actual answer, and the answer is
/// the last line: "denied: requested access to the resource is denied" or
/// "unauthorized: authentication required". Those distinguish a repository
/// that isn't there from one you can't see, which are different problems for
/// whoever has to fix them, so the line is kept rather than replaced with a
/// sentence of ours.
fn refusal_reason(stderr: &str) -> String {
    stderr
        .lines()
        .rev()
        .find(|line| !line.trim().is_empty())
        .map(|line| line.trim().to_string())
        .unwrap_or_else(|| "the registry refused and gave no reason".to_string())
}

/// Is a binary on PATH, and what exactly is it?
///
/// The pin is the hash of the bytes that would run, not the version string.
/// Two builds can report the same version and differ, and the point of a pin
/// is to say which one produced a number.
fn binary_present(entry: &Entry, program: &str) -> Presence {
    let Some(path) = which(program) else {
        return Presence::Absent {
            reason: format!("{program} is not on PATH"),
        };
    };
    match hash_file(&path) {
        Ok(pin) => {
            // The label, not the raw first line the tool printed. A version
            // probe answer that cannot be a version arrives here as the reason
            // it was refused, so `doctor` says so in the column instead of
            // showing a score, a traceback or a usage message as though it
            // were a build identifier. See [`crate::binary_version`].
            let version = binary_version(entry);
            Presence::Present {
                pin: format!("{} {pin}", version.pin_label()),
            }
        }
        Err(e) => Presence::Unknown {
            reason: format!("{} could not be read: {e}", path.display()),
        },
    }
}

/// Checks one registry entry against this machine.
///
/// Reads the environment only to ask whether a named variable is set. It never
/// reads a secret's value, and no value reaches the returned structure, which
/// is what keeps a token out of `doctor --json` output that somebody will paste
/// into a bug report.
///
/// `adapter_roots` are the trees a relative `invoke.adapter` is resolved
/// against, and are empty for a caller that has no registry directory to name.
/// See [`crate::adapter`] for why the entry does not carry the answer itself.
pub fn check(entry: &Entry, adapter_roots: &[PathBuf]) -> Availability {
    let presence = match unsupported_here(entry) {
        Some(p) => p,
        None => present_here(entry, adapter_roots),
    };

    let missing_secrets = entry
        .secrets
        .iter()
        .filter(|name| std::env::var_os(name).is_none())
        .cloned()
        .collect();

    Availability {
        name: entry.name.clone(),
        presence,
        verified: None,
        missing_secrets,
    }
}

/// Does this entry rule out the machine we are on?
///
/// Only an entry whose program runs on THIS machine can be ruled out this way,
/// which is a locally installed binary or a host adapter. A container is a
/// Linux image wherever it runs, and on macOS and Windows the container runtime
/// supplies the Linux to run it in, so a platform list on an image entry would
/// describe the image's contents rather than where it can be used. A host
/// adapter is the opposite case: the image may well be Linux and irrelevant,
/// because the script runs here, so a platform list on one is a statement about
/// this machine and is honoured. An entry that says nothing is not ruled out:
/// unstated is a question nobody answered, not a claim that it runs everywhere.
fn unsupported_here(entry: &Entry) -> Option<Presence> {
    let runs_on_this_machine =
        entry.binary.is_some() || entry.invoke.as_ref().is_some_and(|i| i.host);
    if entry.platforms.is_empty() || !runs_on_this_machine {
        return None;
    }
    let here = std::env::consts::OS;
    if entry.platforms.iter().any(|p| p == here) {
        return None;
    }
    Some(Presence::Unsupported {
        reason: format!(
            "this entry runs on {} and this machine is {here}, so nothing to \
             install would make it available",
            entry.platforms.join(" and ")
        ),
    })
}

/// Can the adapter for a SERVICE entry run on this machine?
///
/// `invoke.host = true` says the thing to run is here rather than inside the
/// image, and [`crate::selftest::read_one`] means it literally: it launches
/// `invoke.entrypoint` with the adapter script and never touches the image at
/// all. So presence asks about exactly that program. Asking whether the image
/// is pulled would answer a question no run ever poses, and it is the question
/// this check used to answer: the image arm matched first, so a service
/// running on another host, which is the normal arrangement, was reported
/// missing and `score` refused to start until the user pulled an image nothing
/// would run.
///
/// **The image reference stays required, and still means what it meant.** It
/// is what a result names as the subject, pinned by digest so somebody else
/// can fetch the identical bytes. It is a fact about the artefact, not about
/// this machine, and the two were being conflated.
///
/// NOTHING HERE TOUCHES THE NETWORK, ON PURPOSE
/// --------------------------------------------
/// A probe of the service would answer the question this module refuses to
/// answer, which is whether the tool WORKS, and it would answer it badly: the
/// strongest thing a bare connection can report is that something accepted it
/// on that port. The self-test already asks the real question, by posting a
/// fixture and reading the number back, and because presence no longer waits
/// on a pulled image `doctor` now actually reaches it. A probe would also send
/// a request to somebody else's service every time a user typed `doctor`.
///
/// So the two situations the reader has to tell apart are told apart by the
/// two columns that already exist: an unset endpoint is a presence answer, and
/// a service that is down is a self-test failure carrying the adapter's own
/// message about the address it could not reach.
fn host_adapter_present(invoke: &Invoke, adapter_roots: &[PathBuf]) -> Presence {
    // Refused by `Entry::validate`, so this is only reachable for an entry
    // built in memory. It is still an entry fault rather than a missing
    // install, which is why it is Unknown and not Absent.
    let Some(rel) = &invoke.adapter else {
        return Presence::Unknown {
            reason: "invoke.host is set but the entry declares no adapter, so \
                     it names no program to run"
                .into(),
        };
    };

    // Resolved exactly as `run_host_adapter` resolves it, against the same
    // roots, so presence cannot say yes to a path a run would then fail to
    // open. The message names where it looked, which is the whole of the
    // difference between a two second fix and a bug report.
    let adapter = match crate::adapter::resolve(rel, adapter_roots) {
        Ok(p) => p,
        Err(why) => {
            return Presence::Absent {
                reason: why.to_string(),
            }
        }
    };

    let program = invoke
        .entrypoint
        .clone()
        .unwrap_or_else(|| crate::DEFAULT_HOST_ENTRYPOINT.into());
    if which(&program).is_none() {
        return Presence::Absent {
            reason: format!("{program} is not on PATH, and it is what runs the adapter"),
        };
    }

    // Asked last, because the first two are faults in the installation and
    // this one is a thing the reader has not done yet.
    if let Some(name) = &invoke.endpoint_env {
        // Trimmed, because the adapter trims. A variable holding a space is
        // unset as far as `stegashield_one.py` is concerned, and a presence
        // check that disagreed with the thing it is predicting would send a
        // corpus run off to fail on its first image.
        let supplied =
            std::env::var_os(name).is_some_and(|v| !v.to_string_lossy().trim().is_empty());
        if !supplied {
            // Unknown rather than Absent, and the distinction is the honest
            // one: the adapter is here and runnable, and without an address
            // there is no instance to ask, so whether this tool can run here
            // is a question nobody has supplied the information to answer.
            // Reporting it as Absent would send the reader looking for
            // something to install.
            //
            // One line, because `doctor` prints one line per tool over a whole
            // registry and a paragraph here pushes the other twelve off the
            // screen. The reasoning lives in docs/guide/http-detector.md.
            return Presence::Unknown {
                reason: format!(
                    "{name} is not set to an address, so there is no instance \
                     to ask. Start your own and export it; there is no default"
                ),
            };
        }
    }

    // The adapter's bytes, not the image's digest, and labelled so the two
    // cannot be read for each other. This is what decides how the question is
    // asked on this machine; the digest identifying the subject is in the
    // entry and `describe` prints it.
    match hash_file(&adapter) {
        Ok(pin) => Presence::Present {
            pin: format!("adapter {pin}"),
        },
        Err(e) => Presence::Unknown {
            reason: format!("{} could not be read: {e}", adapter.display()),
        },
    }
}

fn present_here(entry: &Entry, adapter_roots: &[PathBuf]) -> Presence {
    // A host adapter wins over both routes, and it has to win in exactly the
    // order `read_one` dispatches: presence is only worth anything if it asks
    // about the program a run would actually launch.
    if let Some(invoke) = &entry.invoke {
        if invoke.host {
            return host_adapter_present(invoke, adapter_roots);
        }
    }
    match (&entry.image, &entry.binary) {
        (Some(img), _) => image_present(&img.reference),
        (_, Some(bin)) => match bin.command.first() {
            Some(program) => binary_present(entry, program),
            None => Presence::Unknown {
                reason: "entry declares an empty command".into(),
            },
        },
        _ => Presence::Unknown {
            reason: "entry declares neither an image nor a binary".into(),
        },
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The real refusal a reader hit when they followed the guide's promise
    /// that a pinned digest meant they could pull it. The login hint above it
    /// is noise; the last line is the answer.
    #[test]
    fn a_registry_refusal_keeps_the_line_that_says_why() {
        let said = "Get \"https://registry-1.docker.io/v2/\": unauthorized\n\
                    unauthorized: authentication required\n";
        assert_eq!(
            refusal_reason(said),
            "unauthorized: authentication required"
        );
    }

    #[test]
    fn a_missing_repository_reads_differently_from_a_forbidden_one() {
        // Different problems for whoever has to fix them: one is "publish the
        // image", the other is "log in". Collapsing both into a sentence of
        // ours would lose that.
        assert_eq!(
            refusal_reason("denied: requested access to the resource is denied\n"),
            "denied: requested access to the resource is denied"
        );
    }

    #[test]
    fn a_runtime_that_refused_silently_still_gives_a_reason() {
        // An empty stderr would otherwise produce an empty explanation, which
        // reads as though nothing was wrong.
        assert!(!refusal_reason("").is_empty());
        assert!(!refusal_reason("   \n\n  \n").is_empty());
    }

    /// The distinction the whole check exists for. `NotRun` means nobody
    /// asked; `Absent` means the registry answered no. A check that could not
    /// run must never be readable as a check that passed, which is the defect
    /// that put an unreproducible measurement into a disclosure package.
    #[test]
    fn a_check_that_could_not_run_is_not_a_check_that_passed() {
        let could_not = Reach::NotRun {
            reason: "no container runtime: docker is not on PATH".into(),
        };
        let answered_no = Reach::Absent {
            reason: "denied: requested access to the resource is denied".into(),
        };
        assert_ne!(could_not, answered_no);
        assert_ne!(could_not, Reach::Fetchable);
        assert_ne!(answered_no, Reach::Fetchable);
    }

    /// These tests are about PRESENCE, not about where an adapter lives, so
    /// they ask with no roots. That falls back to the directory the test runs
    /// in, which is exactly what the signature without roots used to do, so
    /// every expectation below still means what it meant. Adapter resolution
    /// has its own tests in `crate::adapter`.
    fn check(entry: &Entry) -> Availability {
        super::check(entry, &[])
    }

    fn entry(toml_text: &str) -> Entry {
        toml::from_str(toml_text).expect("parses")
    }

    const SELFTEST: &str = "\n[selftest]\nmust_detect = \"a.png\"\nmust_clear = \"b.png\"\n";

    /// What `doctor` prints when the version probe answered with something
    /// that cannot be a version.
    ///
    /// The researcher's cheat script printed `0.010` for every input it was
    /// given, `--version` included, and `doctor` put that in the column a
    /// reader uses to tell one build from another. The tool is still present
    /// and still pinned by the hash of its bytes; what it says about itself is
    /// what is refused, and the refusal has to be visible where the claim was.
    #[cfg(unix)]
    #[test]
    fn a_version_probe_answered_with_a_score_says_so_in_the_pin() {
        use std::os::unix::fs::PermissionsExt;
        let dir = tempfile::tempdir().expect("tmp");
        let script = dir.path().join("cheat.sh");
        std::fs::write(&script, "#!/bin/sh\necho 0.010\n").expect("script");
        let mut perms = std::fs::metadata(&script).expect("meta").permissions();
        perms.set_mode(0o755);
        std::fs::set_permissions(&script, perms).expect("chmod");

        let e = entry(&format!(
            "name = \"cheat\"\nkind = \"detector\"\nlicence = \"X\"\n\
             [binary]\ncommand = [{:?}]\nversion_args = [\"--version\"]\n\
             [emits]\noutput = \"score\"\n\
             [invoke]\nargv = [\"{{file}}\"]\nparser = \"number\"{SELFTEST}",
            script.display().to_string()
        ));
        match check(&e).presence {
            Presence::Present { pin } => {
                assert!(pin.contains("not a version"), "got {pin}");
                assert!(pin.contains("sha256:"), "the hash still pins it: {pin}");
            }
            other => panic!("the program is on PATH, so it is present: {other:?}"),
        }
    }

    #[test]
    fn a_tool_that_cannot_run_here_is_not_reported_as_missing() {
        // "Not installed" is an instruction and "cannot run on this operating
        // system" is a fact about the machine. Reporting the second as the
        // first sends somebody looking for a package that does not exist for
        // them, which is the whole reason this is a separate answer.
        let elsewhere = match std::env::consts::OS {
            "linux" => "windows",
            _ => "linux",
        };
        let e = entry(&format!(
            "name = \"x\"\nkind = \"detector\"\nlicence = \"X\"\n\
             platforms = [\"{elsewhere}\"]\n\
             [binary]\ncommand = [\"definitely-not-installed\"]\n{SELFTEST}"
        ));
        let got = check(&e);
        match &got.presence {
            Presence::Unsupported { reason } => {
                assert!(reason.contains(elsewhere), "{reason}");
                assert!(reason.contains(std::env::consts::OS), "{reason}");
            }
            other => panic!("reported as {other:?} rather than unsupported"),
        }
        assert!(!got.presence.is_present());
    }

    #[test]
    fn a_tool_listing_this_platform_is_checked_normally() {
        let e = entry(&format!(
            "name = \"sh\"\nkind = \"detector\"\nlicence = \"X\"\n\
             platforms = [\"{}\"]\n\
             [binary]\ncommand = [\"sh\"]\nversion_args = [\"--version\"]\n{SELFTEST}",
            std::env::consts::OS
        ));
        assert!(
            !matches!(check(&e).presence, Presence::Unsupported { .. }),
            "a tool that names this platform was ruled out on it"
        );
    }

    #[test]
    fn a_platform_list_does_not_rule_out_a_container() {
        // A container is a Linux image wherever it runs, and on macOS and
        // Windows the runtime supplies the Linux to run it in. A platform list
        // on an image entry would describe the image's contents rather than
        // where it can be used, so it must not make the tool unavailable.
        let e = entry(
            "name = \"x\"\nkind = \"detector\"\nlicence = \"X\"\n\
             platforms = [\"plan9\"]\n\
             [image]\nreference = \"r@sha256:abc\"\nsize_mb = 1\nbundled = true\n",
        );
        assert!(!matches!(check(&e).presence, Presence::Unsupported { .. }));
    }

    #[test]
    fn a_binary_on_path_is_present_and_pinned_by_its_hash() {
        let e = entry(&format!(
            "name = \"sh\"\nkind = \"detector\"\nlicence = \"X\"\n\
             [binary]\ncommand = [\"sh\"]\nversion_args = [\"--version\"]\n{SELFTEST}"
        ));
        let a = check(&e);
        assert!(a.presence.is_present(), "got {:?}", a.presence);
        if let Presence::Present { pin } = &a.presence {
            assert!(pin.contains("sha256:"), "pin should hash the bytes: {pin}");
        }
    }

    #[test]
    fn a_missing_binary_says_what_is_missing() {
        let e = entry(&format!(
            "name = \"nope\"\nkind = \"detector\"\nlicence = \"X\"\n\
             [binary]\ncommand = [\"definitely-not-real-xyzzy\"]\nversion_args = [\"-v\"]\n{SELFTEST}"
        ));
        match check(&e).presence {
            Presence::Absent { reason } => assert!(reason.contains("not on PATH")),
            other => panic!("expected Absent, got {other:?}"),
        }
    }

    #[test]
    fn presence_never_claims_the_tool_was_verified() {
        // The distinction this module exists for. Being installed is not
        // being correct, and doctor must not let one stand for the other.
        let e = entry(&format!(
            "name = \"sh\"\nkind = \"detector\"\nlicence = \"X\"\n\
             [binary]\ncommand = [\"sh\"]\nversion_args = [\"--version\"]\n{SELFTEST}"
        ));
        let a = check(&e);
        assert_eq!(a.verified, None);
        assert!(a.summary().contains("not verified"));
    }

    #[test]
    fn an_unset_secret_is_reported_by_name_only() {
        let e = entry(&format!(
            "name = \"x\"\nkind = \"detector\"\nlicence = \"X\"\n\
             secrets = [\"STEGOBENCH_TEST_UNSET_VAR\"]\n\
             [binary]\ncommand = [\"sh\"]\nversion_args = [\"--version\"]\n{SELFTEST}"
        ));
        let a = check(&e);
        assert_eq!(a.missing_secrets, ["STEGOBENCH_TEST_UNSET_VAR"]);
        // The name appears; nothing else about it can, because the value was
        // never read.
        assert!(a.summary().contains("STEGOBENCH_TEST_UNSET_VAR"));
    }

    #[test]
    fn a_set_secret_is_not_reported_as_missing_and_its_value_never_appears() {
        std::env::set_var("STEGOBENCH_TEST_SET_VAR", "swordfish-do-not-print");
        let e = entry(&format!(
            "name = \"x\"\nkind = \"detector\"\nlicence = \"X\"\n\
             secrets = [\"STEGOBENCH_TEST_SET_VAR\"]\n\
             [binary]\ncommand = [\"sh\"]\nversion_args = [\"--version\"]\n{SELFTEST}"
        ));
        let a = check(&e);
        assert!(a.missing_secrets.is_empty());
        assert!(
            !format!("{a:?}").contains("swordfish"),
            "a secret value must never reach the output"
        );
        std::env::remove_var("STEGOBENCH_TEST_SET_VAR");
    }

    /// The StegaShield token-leak test named in the v0.1 shortlist (13-v0.1-
    /// scope.md section 2): "a test asserts that: run the plugin with a known
    /// token value and grep every artefact the run produced for it."
    ///
    /// This exercises the REAL registered entry (`plugins/registry/detectors/
    /// stegashield.toml`), not a synthetic one, on both paths the item asks
    /// for:
    ///
    /// - **Absent token**: `check()` must report `STEGASHIELD_LICENCE` as
    ///   missing rather than silently proceeding or panicking.
    /// - **Present token**: given a sentinel value, that value must not
    ///   appear anywhere in `Availability`'s Debug output, its `summary()`
    ///   line, or the JSON `stegobench describe stegashield` would emit
    ///   (`Entry` only ever carries the variable's NAME in `secrets`, never a
    ///   value, so this also guards against a future change to `Entry`
    ///   accidentally starting to carry one).
    ///
    /// **What this does NOT test, and why.** `score`/`run` do not exist yet
    /// (see `main.rs`'s `not_yet`), so there is no code path that actually
    /// starts the StegaShield container, and therefore nothing yet writes a
    /// log line, a manifest row or a `result-v1` document from a real
    /// invocation for a real run to grep. The full "run it and grep every
    /// artefact" version of this test has to wait for that command to exist;
    /// this test is written so it keeps passing unchanged once it does, and
    /// so the absent-token path (the one that must fail clearly) is checked
    /// today rather than left untested until then. No real
    /// `STEGASHIELD_LICENCE` token was available to this session and none
    /// was requested, per the instruction that the token is user-supplied
    /// and never hardcoded; the sentinel here stands in for it.
    #[test]
    fn the_stegashield_licence_token_never_leaks_on_either_path() {
        let registry_dir =
            std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../plugins/registry");
        let reg = stegobench_core::registry::Registry::load(&registry_dir)
            .expect("the real registry loads");
        let stegashield = reg
            .entries
            .get("stegashield")
            .expect("stegashield is registered");
        assert_eq!(stegashield.secret_names(), ["STEGASHIELD_LICENCE"]);

        // Absent-token path: must be reported missing, not silently ignored.
        std::env::remove_var("STEGASHIELD_LICENCE");
        let absent = check(stegashield);
        assert_eq!(absent.missing_secrets, ["STEGASHIELD_LICENCE"]);

        // Present-token path: a sentinel must never surface anywhere.
        const SENTINEL: &str = "sk-test-sentinel-do-not-print-9f31c2";
        std::env::set_var("STEGASHIELD_LICENCE", SENTINEL);
        let present = check(stegashield);
        std::env::remove_var("STEGASHIELD_LICENCE");

        assert!(present.missing_secrets.is_empty());
        let debug_repr = format!("{present:?}");
        assert!(
            !debug_repr.contains(SENTINEL),
            "the token leaked into Availability's Debug output: {debug_repr}"
        );
        assert!(
            !present.summary().contains(SENTINEL),
            "the token leaked into the doctor summary line"
        );
        let describe_json = serde_json::to_string(stegashield).expect("Entry serialises");
        assert!(
            !describe_json.contains(SENTINEL),
            "the token leaked into what `stegobench describe stegashield` would print"
        );
    }

    /// Everything a service entry needs on this machine, with the adapter and
    /// the interpreter both real so only the thing under test can fail.
    ///
    /// `sh` stands in for `python3`: what is being checked is that presence
    /// asks about the entrypoint the runner would launch, and an interpreter
    /// that is on every Unix machine keeps the test from depending on which
    /// Pythons happen to be installed.
    struct Service {
        _dir: tempfile::TempDir,
        adapter: std::path::PathBuf,
    }

    impl Service {
        fn new() -> Self {
            let dir = tempfile::tempdir().expect("a temporary directory");
            let adapter = dir.path().join("service_one.sh");
            std::fs::write(&adapter, b"#!/bin/sh\necho 0.9\n").expect("the adapter is written");
            Service { _dir: dir, adapter }
        }

        /// A host entry pointing at that adapter.
        ///
        /// `top` and `invoke_extra` are separate because TOML assigns a bare
        /// key to the table above it, so a `platforms` line written after
        /// `[invoke]` becomes an invoke field that nothing reads, and the test
        /// asserting on it passes for the wrong reason. `registry.rs`'s own
        /// helper carries the same warning for the same reason.
        fn entry(&self, top: &str, invoke_extra: &str) -> Entry {
            let e = entry(&format!(
                "name = \"svc\"\nkind = \"detector\"\nlicence = \"X\"\n{top}\
                 [image]\nreference = \"r@sha256:abc\"\nsize_mb = 1250\nbundled = false\n\
                 [invoke]\nhost = true\nentrypoint = \"sh\"\n\
                 adapter = \"{}\"\nargv = [\"{{adapter}}\", \"{{file}}\"]\n\
                 parser = \"number\"\n{invoke_extra}{SELFTEST}",
                self.adapter.display()
            ));
            assert!(e.invoke.as_ref().expect("an invoke block").host);
            e
        }

        /// The same entry with an endpoint variable declared.
        fn with_endpoint(&self, var: &str) -> Entry {
            let e = self.entry("", &format!("endpoint_env = \"{var}\"\n"));
            assert_eq!(
                e.invoke.as_ref().unwrap().endpoint_env.as_deref(),
                Some(var),
                "the fixture did not actually declare the variable"
            );
            e
        }
    }

    /// The bug this file was opened for. A service entry was answered by
    /// asking whether a container image was pulled, when the adapter never
    /// runs that image and the instance being scored is normally on another
    /// host entirely. `score` then refused with a pre-flight error and
    /// `doctor` skipped the one check that would have proved the service
    /// answers.
    #[test]
    fn a_service_entry_is_answered_by_its_adapter_and_not_by_its_image() {
        let svc = Service::new();
        let e = svc.entry("", "");
        // The image in that entry is a reference nothing has ever pulled, so
        // the old answer was a refusal and the new one must not be.
        assert!(
            !image_present(&e.image.as_ref().unwrap().reference).is_present(),
            "the fixture's image turned out to be pulled, so this proves nothing"
        );
        let got = check(&e);
        assert!(got.presence.is_present(), "got {:?}", got.presence);
    }

    #[test]
    fn a_ready_service_is_pinned_by_the_adapters_bytes_and_says_so() {
        let svc = Service::new();
        let a = check(&svc.entry("", "")).presence;
        let Presence::Present { pin } = &a else {
            panic!("expected Present, got {a:?}");
        };
        assert!(
            pin.starts_with("adapter sha256:"),
            "the pin must say what it pinned, or it reads as the image digest: {pin}"
        );
        assert_eq!(
            pin,
            &format!("adapter {}", hash_file(&svc.adapter).expect("hashes")),
            "the pin should be the bytes that actually run here"
        );
        // Truncated to 23 characters by `summary`, so the label has to survive
        // the truncation or the line is worse than no line.
        assert!(check(&svc.entry("", ""))
            .summary()
            .contains("adapter sha256"));
    }

    /// The other half of the situation the reader has to be told apart from a
    /// service that is down. Nobody has said where the instance is, so there
    /// is nothing to ask, and that is Unknown rather than a missing install:
    /// there is no package to go and fetch.
    #[test]
    fn a_service_whose_endpoint_variable_is_unset_says_which_variable_and_why() {
        const VAR: &str = "STEGOBENCH_TEST_UNSET_ENDPOINT_A";
        std::env::remove_var(VAR);
        let svc = Service::new();
        let e = svc.with_endpoint(VAR);
        match check(&e).presence {
            Presence::Unknown { reason } => {
                assert!(reason.contains(VAR), "the variable is not named: {reason}");
                assert!(
                    reason.contains("no default"),
                    "it should say why there is no default: {reason}"
                );
            }
            other => panic!("expected Unknown naming the variable, got {other:?}"),
        }
    }

    /// An exported but empty variable is the same situation as an unset one:
    /// `export FOO=` leaves the first behind, and a copied line with a stray
    /// space leaves the second. The adapter trims before deciding, so this has
    /// to agree with it or presence stops predicting what a run will do.
    #[test]
    fn an_empty_or_blank_endpoint_variable_counts_as_unset() {
        for (i, blank) in ["", "   ", "\t\n"].iter().enumerate() {
            let var = format!("STEGOBENCH_TEST_BLANK_ENDPOINT_{i}");
            std::env::set_var(&var, blank);
            let svc = Service::new();
            let got = check(&svc.with_endpoint(&var)).presence;
            std::env::remove_var(&var);
            assert!(
                matches!(got, Presence::Unknown { .. }),
                "{blank:?} was taken for an address: {got:?}"
            );
        }
    }

    /// Present, because the adapter can run and it has been told where to ask.
    /// Whether anything answers there is the self-test's question, and this
    /// module must not pretend to have asked it: no request is made, so a
    /// machine with no route to that address reaches the same answer, in the
    /// same time, as one sitting next to the service.
    #[test]
    fn a_service_with_an_endpoint_set_is_present_without_anything_being_contacted() {
        const VAR: &str = "STEGOBENCH_TEST_SET_ENDPOINT";
        // An address on a documentation range that is not routed anywhere, so
        // if this ever did reach out the test would stall rather than pass.
        std::env::set_var(VAR, "http://198.51.100.7:3000/api/analyze");
        let svc = Service::new();
        let started = std::time::Instant::now();
        let got = check(&svc.with_endpoint(VAR));
        std::env::remove_var(VAR);
        assert!(got.presence.is_present(), "got {:?}", got.presence);
        assert!(
            started.elapsed() < std::time::Duration::from_secs(1),
            "a presence check that takes a second is one that went and asked"
        );
        assert_eq!(
            got.verified, None,
            "present must never be allowed to stand in for working"
        );
        assert!(got.summary().contains("not verified"));
    }

    /// The value of the endpoint is read only to see whether there is one. It
    /// is not a secret, but it is one team's internal address and it has no
    /// business in output somebody pastes into a bug report.
    #[test]
    fn the_endpoints_value_never_reaches_the_output() {
        const VAR: &str = "STEGOBENCH_TEST_ENDPOINT_VALUE";
        const SENTINEL: &str = "http://internal-host-do-not-print.invalid:3000/api/analyze";
        std::env::set_var(VAR, SENTINEL);
        let svc = Service::new();
        let got = check(&svc.with_endpoint(VAR));
        std::env::remove_var(VAR);
        assert!(
            !format!("{got:?}").contains("internal-host-do-not-print"),
            "the address leaked into the output: {got:?}"
        );
    }

    /// The message a stranger meets. It used to end "run from the root of the
    /// clone", which is no advice at all to somebody who installed a package,
    /// and that reader is exactly who the built-in registry exists for.
    #[test]
    fn a_service_whose_adapter_is_missing_says_where_it_looked_and_not_which_clone() {
        let root = tempfile::tempdir().expect("tmp");
        let svc = Service::new();
        let mut e = svc.entry("", "");
        e.invoke.as_mut().unwrap().adapter = Some("plugins/adapters/not-here-xyzzy.py".into());
        match super::check(&e, &[root.path().to_path_buf()]).presence {
            Presence::Absent { reason } => {
                assert!(reason.contains("not-here-xyzzy.py"), "{reason}");
                assert!(
                    reason.contains(&root.path().display().to_string()),
                    "it does not say where it looked: {reason}"
                );
                assert!(
                    !reason.contains("clone"),
                    "a packaged install is still being sent to a clone: {reason}"
                );
            }
            other => panic!("expected Absent, got {other:?}"),
        }
    }

    /// The other half: an adapter that IS under the root is found, so the
    /// refusal above is a real finding rather than this path never working.
    #[test]
    fn a_service_whose_adapter_is_under_the_root_is_present() {
        let root = tempfile::tempdir().expect("tmp");
        let adapter = root.path().join("plugins").join("adapters").join("one.py");
        std::fs::create_dir_all(adapter.parent().expect("parent")).expect("dirs");
        std::fs::write(&adapter, b"#!/usr/bin/env python3\n").expect("written");

        let svc = Service::new();
        let mut e = svc.entry("", "");
        e.invoke.as_mut().unwrap().adapter = Some("plugins/adapters/one.py".into());
        // Nothing found it from the working directory, which is what the old
        // resolution had to rely on.
        assert!(matches!(
            check(&e).presence,
            Presence::Absent { .. } | Presence::Unknown { .. }
        ));
        match super::check(&e, &[root.path().to_path_buf()]).presence {
            Presence::Present { pin } => assert!(pin.starts_with("adapter "), "{pin}"),
            other => panic!("expected Present, got {other:?}"),
        }
    }

    #[test]
    fn a_service_whose_interpreter_is_not_installed_names_the_interpreter() {
        let svc = Service::new();
        let mut e = svc.entry("", "");
        e.invoke.as_mut().unwrap().entrypoint = Some("definitely-not-a-runtime-xyzzy".into());
        match check(&e).presence {
            Presence::Absent { reason } => {
                assert!(
                    reason.contains("definitely-not-a-runtime-xyzzy"),
                    "{reason}"
                );
                assert!(reason.contains("not on PATH"), "{reason}");
            }
            other => panic!("expected Absent, got {other:?}"),
        }
    }

    /// `Entry::validate` refuses this, so it can only arrive from an entry
    /// built in memory. It is an entry fault rather than a missing install,
    /// and reporting it as Absent would send somebody looking for a package.
    #[test]
    fn a_host_entry_with_no_adapter_at_all_is_unknown() {
        let svc = Service::new();
        let mut e = svc.entry("", "");
        e.invoke.as_mut().unwrap().adapter = None;
        match check(&e).presence {
            Presence::Unknown { reason } => assert!(reason.contains("no adapter"), "{reason}"),
            other => panic!("expected Unknown, got {other:?}"),
        }
    }

    /// A host adapter runs on THIS machine, so unlike a container a platform
    /// list on one is a statement about this machine and has to be honoured.
    #[test]
    fn a_platform_list_does_rule_out_a_host_adapter_even_though_it_names_an_image() {
        let elsewhere = match std::env::consts::OS {
            "linux" => "windows",
            _ => "linux",
        };
        let svc = Service::new();
        let e = svc.entry(&format!("platforms = [\"{elsewhere}\"]\n"), "");
        match check(&e).presence {
            Presence::Unsupported { reason } => assert!(reason.contains(elsewhere), "{reason}"),
            other => panic!("expected Unsupported, got {other:?}"),
        }
    }

    #[test]
    fn a_host_adapter_listing_this_platform_is_checked_normally() {
        let svc = Service::new();
        let e = svc.entry(&format!("platforms = [\"{}\"]\n", std::env::consts::OS), "");
        assert!(check(&e).presence.is_present(), "{:?}", check(&e).presence);
    }

    /// The regression guard. An ordinary container entry is still answered by
    /// asking the container runtime, and an ordinary binary entry by looking
    /// on PATH; neither goes anywhere near the host-adapter path.
    #[test]
    fn a_container_entry_without_host_is_unaffected() {
        let e = entry(
            "name = \"x\"\nkind = \"detector\"\nlicence = \"X\"\n\
             [image]\nreference = \"definitely-not-pulled-xyzzy@sha256:abc\"\n\
             size_mb = 1\nbundled = true\n\
             [invoke]\nadapter = \"plugins/adapters/x.py\"\nargv = [\"{file}\"]\n\
             parser = \"number\"\n",
        );
        // Either Absent (a runtime said no) or Unknown (there is no runtime).
        // Never Present, and never the adapter path, which would have found
        // that adapter missing and said so in its own words.
        match check(&e).presence {
            Presence::Absent { reason } => assert!(reason.contains("docker pull"), "{reason}"),
            Presence::Unknown { reason } => {
                assert!(reason.contains("no container runtime"), "{reason}")
            }
            other => panic!("a container entry took another route: {other:?}"),
        }
    }

    #[test]
    fn a_binary_entry_without_host_is_unaffected() {
        let e = entry(&format!(
            "name = \"sh\"\nkind = \"detector\"\nlicence = \"X\"\n\
             [binary]\ncommand = [\"sh\"]\nversion_args = [\"--version\"]\n\
             [invoke]\nargv = [\"{{file}}\"]\nparser = \"number\"\n{SELFTEST}"
        ));
        let a = check(&e).presence;
        assert!(a.is_present(), "got {a:?}");
        if let Presence::Present { pin } = &a {
            assert!(
                !pin.starts_with("adapter "),
                "a binary entry was pinned as an adapter: {pin}"
            );
        }
    }

    #[test]
    fn an_entry_with_neither_image_nor_binary_is_unknown_not_absent() {
        let mut e = entry(&format!(
            "name = \"x\"\nkind = \"detector\"\nlicence = \"X\"\n\
             [binary]\ncommand = [\"sh\"]\nversion_args = [\"-v\"]\n{SELFTEST}"
        ));
        e.binary = None;
        assert!(matches!(check(&e).presence, Presence::Unknown { .. }));
    }
}