{"slug":"binary-check","title":"A check that can fail","description":"An eval a stranger can run: a bead check that exits non-zero when the how_checked field is missing or empty. A file that merely exists is not a pass.","body":"# A check that can fail\n\nThis file is an eval: a check a stranger can run that exits non-zero on a broken copy.\n\n## When to use\n\nUse this eval when you have a bead written as four labeled lines and you need a command that exits 0 on a good bead and exits non-zero on a broken one. The broken cases include a bead that omits its check, a bead whose check line is empty, and a file that exists and says nothing.\n\nThe script is the observation. You can run it without the author.\n\n## When not to\n\nDo not use \"the file is present\" as this eval. Presence is a precondition for reading the file. It is not the check.\n\nDo not edit the script so that a missing field prints a warning and exits 0. A check that cannot fail will accept the known-bad envelope, and then it is not this eval.\n\n## The specimen\n\nThe artifact is this check.\n\n```bash\n#!/bin/bash\n# check-bead.sh - exit 0 only when a bead names four non-empty fields.\n# Usage: check-bead.sh FILE\n# A file that merely exists is not a pass.\nset -euo pipefail\n\nif [ \"${1:-}\" = \"\" ]; then\n  echo \"usage: check-bead.sh FILE\"\n  exit 2\nfi\nfile=\"$1\"\nif [ ! -f \"$file\" ]; then\n  echo \"missing file: $file\"\n  exit 2\nfi\n\nrequire() {\n  label=\"$1\"\n  message=\"$2\"\n  if ! grep -Eq \"^${label}:[[:space:]]*[^[:space:]]\" \"$file\"; then\n    echo \"$message\"\n    exit 1\n  fi\n}\n\nrequire how_checked \"fail: bead has no how_checked observation\"\nrequire deliverable \"fail: bead has no deliverable\"\nrequire may_change \"fail: bead has no writable scope\"\nrequire must_not_touch \"fail: bead has no protected scope\"\necho \"pass\"\n```\n\nSave it as `check-bead.sh`. It requires one argument, the path of the bead file. If the argument is missing, or the path is not a file, it exits 2. If the file exists, it still has to earn a pass.\n\nThe pass condition is four labels, each at the start of a line, each followed by a non-empty value, in this order of judgment: `how_checked`, then `deliverable`, then `may_change`, then `must_not_touch`. The first missing label is the failure the script prints. `how_checked` is first so that a bead which omits its check fails on that omission even when the other fields are present.\n\nA good bead, the one in \"The four-field envelope,\" looks like this:\n\n```text\ndeliverable: One specimen file a stranger can reuse without the author present.\nhow_checked: check-bead.sh on this file exits 0.\nmay_change: The single specimen file this bead names.\nmust_not_touch: The roster, the seed files, and every other specimen.\n```\n\nThe known-bad pair is in \"An envelope that goes red.\" This script is the eval that must reject it.\n\n## How a stranger checks it\n\nRun three observations. All three are required.\n\n1. Create an empty file named `empty.txt`. Run `bash check-bead.sh empty.txt`. It exits 1 and prints `fail: bead has no how_checked observation`. The file exists. The check still fails. That is the point.\n2. Save the known-bad bead from \"An envelope that goes red\" and run the script on it. It exits 1 and prints the same line.\n3. Save the good bead and run the script on it. It exits 0 and prints `pass`.\n\nA copy of the script that exits 0 on the empty file fails this eval. A copy that checks only `deliverable` and ignores `how_checked` fails this eval, because the known-bad bead has a deliverable and must still go red.\n","kind":"eval","stratum":"proof","license":"CC-BY-4.0","shot":"na","tags":["eval","check","exit-code","bead"],"author_name":"Campaign Hub","author_url":"https://campaignhub.fyi/about","source_url":null,"provenance":"Original teaching specimen written for the Campaign Hub library. Not a transcript of a private run.","maturity":"practiced","audience_role":"reviewer","safety_class":"public_teaching","harness":["generic"],"use_when":"Use this check when a bead claims to be finished and you need an observation that goes red on a broken copy, including a copy that is only an empty file.","avoid_when":"Do not replace this check with a test that the file exists. Do not soften a red result into a warning that still exits 0.","eval_checks":[{"id":"EVAL-1","text":"check-bead.sh exits 1 on a file that exists but has no how_checked value, and exits 0 on a four-field bead.","how_checked":"Run the script on an empty file and on the known-bad envelope. Both exit 1 with the how_checked failure line. Run it on the good bead. It exits 0 and prints pass."}],"published_at":"2026-09-24T21:59:21.000Z","updated_at":"2026-09-24T21:59:21.000Z","sensor":null,"edges":[{"from":"binary-check","to":"four-field-envelope","kind":"checks","title":"The four-field envelope"},{"from":"defect-pass","to":"binary-check","kind":"cites","title":"Defect pass"},{"from":"four-field-envelope","to":"binary-check","kind":"requires","title":"The four-field envelope"},{"from":"read-only-verifier","to":"binary-check","kind":"requires","title":"Read-only verifier"}]}