mandrel-platform 1.5.0 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,7 @@
     "provenance": true
   },
   "dependencies": {
-    "mandrel": "^2.35.0"
+    "mandrel": "^2.38.0"
   },
   "scripts": {
     "typecheck": "node --input-type=module --eval 'process.exit(0)'",

package/scripts/check-runner-runs-on.test.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * check-runner-runs-on.test.mjs — regression guard for the `runner` input's
+ * two documented shapes (Story #421).
+ *
+ * The bug this pins: every `runs-on:` site consumed the input raw as
+ * `${{ inputs.runner }}`. GitHub does not parse a JSON-array *string* in that
+ * position — it takes the entire text as ONE label name. A caller passing the
+ * documented `'["self-hosted","my-runner"]'` therefore targeted a label no
+ * runner carries, and every tier sat `queued` until the 24-hour timeout.
+ *
+ * It was silent. Nothing went red, no job started, so there were no logs, and
+ * `gh pr checks` reported `pending 0` — indistinguishable from a busy fleet.
+ * The tell was that caller-owned jobs went green while every reusable-workflow
+ * tier reported `pending 0`.
+ *
+ * Why this is not a grep. A `grep` cannot tell a resolvable `runs-on`
+ * expression from an unresolvable one — that is precisely how this shipped,
+ * past static checks that all passed. Asserting the expression's spelling
+ * would pin the wording and not the behaviour. So this EXTRACTS each real
+ * expression from the workflow and EVALUATES it under Actions semantics, the
+ * same read-then-execute approach as check-toolchain-cache-default.test.mjs.
+ *
+ * Run: node --test scripts/check-runner-runs-on.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readFileSync, readdirSync } from "node:fs";
+import { evaluate } from "./lib/actions-expression.mjs";
+
+const WORKFLOW_DIR = ".github/workflows";
+
+/** Every workflow that declares a `runner` workflow_call input. */
+function runnerWorkflows() {
+  return readdirSync(WORKFLOW_DIR)
+    .filter((f) => f.endsWith(".yml"))
+    .map((f) => ({ file: `${WORKFLOW_DIR}/${f}`, text: readFileSync(`${WORKFLOW_DIR}/${f}`, "utf8") }))
+    .filter(({ text }) => /^\s{6}runner:$/m.test(text));
+}
+
+/**
+ * The `${{ … }}` bodies of every `runs-on:` value that reads `inputs.runner`.
+ * Scans lines rather than building a regex around the file — the block
+ * boundary is a single line, and a dynamically-constructed regex is a SAST
+ * finding that buys nothing here.
+ */
+function runsOnExpressions(text) {
+  const out = [];
+  for (const [idx, line] of text.split("\n").entries()) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("runs-on:")) continue;
+    if (!trimmed.includes("inputs.runner")) continue;
+    const m = trimmed.match(/^runs-on:\s*\$\{\{(.+)\}\}\s*$/);
+    assert.ok(m, `line ${idx + 1}: runs-on reads inputs.runner but is not a single expression: ${trimmed}`);
+    out.push({ line: idx + 1, expr: m[1].trim() });
+  }
+  return out;
+}
+
+const WORKFLOWS = runnerWorkflows();
+
+test("every workflow taking a `runner` input is covered by this guard", () => {
+  // A new reusable workflow with a `runner` input must not slip past unseen.
+  const names = WORKFLOWS.map(({ file }) => file.split("/").pop()).sort();
+  assert.deepEqual(names, [
+    "advisory-scan.yml",
+    "deploy-cloudflare.yml",
+    "pr-quality.yml",
+    "release-automation.yml",
+    "secret-scan-push.yml",
+    "uptime-apply.yml",
+  ]);
+});
+
+test("no `runs-on:` consumes `inputs.runner` raw", () => {
+  // The exact shape that shipped the bug. Kept as a cheap, legible tripwire
+  // alongside the behavioural assertions below.
+  for (const { file, text } of WORKFLOWS) {
+    for (const { line, expr } of runsOnExpressions(text)) {
+      assert.notEqual(
+        expr,
+        "inputs.runner",
+        `${file}:${line}: \`runs-on\` consumes the input raw — a JSON-array ` +
+          `string resolves to one unmatchable label name and the job queues forever`,
+      );
+    }
+  }
+});
+
+for (const { file, text } of WORKFLOWS) {
+  const sites = runsOnExpressions(text);
+
+  test(`${file}: has at least one runner-driven runs-on site`, () => {
+    assert.ok(sites.length > 0, "expected this workflow to drive runs-on from inputs.runner");
+  });
+
+  test(`${file}: a bare label resolves to that same string`, () => {
+    for (const { line, expr } of sites) {
+      assert.equal(evaluate(expr, { runner: "ubuntu-latest" }), "ubuntu-latest", `${file}:${line}`);
+      assert.equal(evaluate(expr, { runner: "beestera-runner" }), "beestera-runner", `${file}:${line}`);
+    }
+  });
+
+  test(`${file}: the documented JSON-array string resolves to a label ARRAY`, () => {
+    for (const { line, expr } of sites) {
+      assert.deepEqual(
+        evaluate(expr, { runner: '["self-hosted","beestera-runner"]' }),
+        ["self-hosted", "beestera-runner"],
+        `${file}:${line}: the documented array form must yield real labels, ` +
+          `not one label named after the whole JSON text`,
+      );
+    }
+  });
+
+  test(`${file}: a malformed array-shaped value fails loudly, not into the label branch`, () => {
+    // A silent fallback to the raw string would rebuild the original failure
+    // mode — an unmatchable label, queued until the 24-hour timeout — behind a
+    // fix that claims to have removed it.
+    for (const { line, expr } of sites) {
+      assert.throws(
+        () => evaluate(expr, { runner: '["unterminated' }),
+        /could not parse/,
+        `${file}:${line}: a '['-leading value that is not valid JSON must be a hard error`,
+      );
+    }
+  });
+
+  test(`${file}: every runs-on site resolves identically`, () => {
+    // One workflow must not drift into two dialects of the same decision.
+    const rendered = sites.map(({ expr }) =>
+      JSON.stringify(evaluate(expr, { runner: '["self-hosted","x"]' })),
+    );
+    assert.equal(new Set(rendered).size, 1, `${file}: runs-on sites disagree: ${rendered.join(" | ")}`);
+  });
+}
+
+test("the documented array form resolves AND derives toolchain-cache 'false'", () => {
+  // The coupling the gap report found: before this fix the only `runner` value
+  // that derived the correct cache posture was the one that never reached a
+  // runner, and the only value that reached a runner derived the wrong posture.
+  // A self-hosted caller could not get both right from the documented
+  // interface. Assert the pairing is now reachable in a single value.
+  const quality = readFileSync(`${WORKFLOW_DIR}/pr-quality.yml`, "utf8");
+  const runner = '["self-hosted","beestera-runner"]';
+
+  const [runsOn] = runsOnExpressions(quality);
+  assert.deepEqual(evaluate(runsOn.expr, { runner }), ["self-hosted", "beestera-runner"]);
+
+  const cache = quality.match(/^\s*cache:\s*\$\{\{(.+)\}\}\s*$/m);
+  assert.ok(cache, "no `cache: ${{ … }}` value found at the setup-toolchain call site");
+  assert.equal(evaluate(cache[1].trim(), { runner, "toolchain-cache": "auto" }), "false");
+});

package/scripts/check-toolchain-cache-default.test.mjs

@@ -31,6 +31,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import { readFileSync } from "node:fs";
+import { evaluate } from "./lib/actions-expression.mjs";
 
 const QUALITY = ".github/workflows/pr-quality.yml";
 const ADVISORY = ".github/workflows/advisory-scan.yml";
@@ -68,146 +69,13 @@ function inputDefault(text, name, file) {
 }
 
 // ---------------------------------------------------------------------------
-// A minimal GitHub Actions expression evaluator
-//
-// Only the surface this expression uses: string literals, `inputs.<name>` /
-// `inputs['<name>']` context reads, `==`/`!=`, `&&`/`||`, parentheses, and
-// `contains()`. The semantics that matter and that a hand-read gets wrong:
-//
-//   - `a && b` yields `b` when `a` is truthy, else `a`.
-//   - `a || b` yields `a` when `a` is truthy, else `b`.
-//   - EVERY non-empty string is truthy — including the string `'false'`.
-//   - String comparison is case-insensitive.
+// The Actions expression evaluator now lives in scripts/lib/actions-expression.mjs
+// (extracted by Story #421, when check-runner-runs-on.test.mjs needed the same
+// read-then-execute approach). Its own semantics are covered by
+// scripts/lib/actions-expression.test.mjs, so this file asserts only the
+// toolchain-cache contract.
 // ---------------------------------------------------------------------------
 
-function truthy(v) {
-  if (typeof v === "boolean") return v;
-  if (typeof v === "number") return v !== 0;
-  if (typeof v === "string") return v !== "";
-  return v !== null && v !== undefined;
-}
-
-function looseEqual(a, b) {
-  if (typeof a === "string" && typeof b === "string") {
-    return a.toLowerCase() === b.toLowerCase();
-  }
-  return a === b;
-}
-
-function evaluate(expr, inputs) {
-  let i = 0;
-
-  const ws = () => {
-    while (i < expr.length && /\s/.test(expr[i])) i++;
-  };
-  const eat = (token) => {
-    ws();
-    if (expr.startsWith(token, i)) {
-      i += token.length;
-      return true;
-    }
-    return false;
-  };
-
-  function parseOr() {
-    let left = parseAnd();
-    for (;;) {
-      ws();
-      if (!eat("||")) return left;
-      const right = parseAnd();
-      left = truthy(left) ? left : right;
-    }
-  }
-
-  function parseAnd() {
-    let left = parseCompare();
-    for (;;) {
-      ws();
-      if (!eat("&&")) return left;
-      const right = parseCompare();
-      left = truthy(left) ? right : left;
-    }
-  }
-
-  function parseCompare() {
-    const left = parsePrimary();
-    ws();
-    if (eat("!=")) return !looseEqual(left, parsePrimary());
-    if (eat("==")) return looseEqual(left, parsePrimary());
-    return left;
-  }
-
-  function parsePrimary() {
-    ws();
-    if (eat("(")) {
-      const v = parseOr();
-      ws();
-      assert.ok(eat(")"), `unbalanced parenthesis at ${i} in: ${expr}`);
-      return v;
-    }
-    if (expr[i] === "'") {
-      i++;
-      let out = "";
-      while (i < expr.length) {
-        if (expr[i] === "'" && expr[i + 1] === "'") {
-          out += "'";
-          i += 2;
-          continue;
-        }
-        if (expr[i] === "'") {
-          i++;
-          return out;
-        }
-        out += expr[i++];
-      }
-      assert.fail(`unterminated string literal in: ${expr}`);
-    }
-    if (expr.startsWith("contains(", i)) {
-      i += "contains(".length;
-      const hay = parseOr();
-      ws();
-      assert.ok(eat(","), `contains() expects two arguments in: ${expr}`);
-      const needle = parseOr();
-      ws();
-      assert.ok(eat(")"), `unclosed contains() in: ${expr}`);
-      return String(hay).toLowerCase().includes(String(needle).toLowerCase());
-    }
-    const ident = expr.slice(i).match(/^[A-Za-z_][A-Za-z0-9_.\-]*(\['[^']*'\])?/);
-    assert.ok(ident, `unparseable token at ${i} in: ${expr}`);
-    i += ident[0].length;
-    const raw = ident[0];
-    if (raw === "true") return true;
-    if (raw === "false") return false;
-    const bracket = raw.match(/^inputs\['([^']*)'\]$/);
-    const dotted = raw.match(/^inputs\.(.+)$/);
-    const key = bracket ? bracket[1] : dotted ? dotted[1] : null;
-    assert.ok(key !== null, `unsupported context read \`${raw}\` in: ${expr}`);
-    assert.ok(key in inputs, `expression reads \`inputs.${key}\`, not provided by the test case`);
-    return inputs[key];
-  }
-
-  const value = parseOr();
-  ws();
-  assert.equal(i, expr.length, `trailing tokens at ${i} in: ${expr}`);
-  return value;
-}
-
-// ---------------------------------------------------------------------------
-// The evaluator itself must be trustworthy before it can judge the workflow.
-// ---------------------------------------------------------------------------
-
-test("the expression evaluator models Actions truthiness, not JavaScript's", () => {
-  // The trap the real expression depends on: the STRING 'false' is truthy, so
-  // an explicitly-pinned 'false' survives the first arm of the ternary.
-  assert.equal(evaluate("'false' && 'yes' || 'no'", {}), "yes");
-  // `&&`/`||` yield operands, not booleans.
-  assert.equal(evaluate("true && 'kept'", {}), "kept");
-  assert.equal(evaluate("'' || 'fallback'", {}), "fallback");
-  // Comparison is case-insensitive.
-  assert.equal(evaluate("'AUTO' == 'auto'", {}), true);
-  assert.equal(evaluate("contains('[\"self-hosted\",\"x\"]', 'self-hosted')", {}), true);
-});
-
 // ---------------------------------------------------------------------------
 // The contract
 // ---------------------------------------------------------------------------

package/scripts/check-workflow-portability.mjs

@@ -39,6 +39,20 @@
  *      job". Requires git history (run CI checkout with fetch-depth: 0); the
  *      check degrades to a skipped NOTE when the pinned blob is unreachable.
  *
+ *   4. `runs-on: ${{ inputs.runner }}` — consuming a `runner` input RAW is
+ *      PROHIBITED. GitHub does not parse a JSON-array *string* in that
+ *      position: it takes the entire text as ONE label name, so the
+ *      documented `'["self-hosted","my-runner"]'` form matches no runner and
+ *      every job sits `queued` until the 24-hour timeout. This one is worse
+ *      than the others because it is not even loud — no job starts, so there
+ *      are no logs, and `gh pr checks` reports `pending 0`, indistinguishable
+ *      from a busy fleet. Normalize to
+ *      `fromJSON(startsWith(inputs.runner, '[') && inputs.runner ||
+ *      format('"{0}"', inputs.runner))`, which accepts both documented
+ *      shapes. (Caused #419 / v1.5.0; behaviour is covered by
+ *      check-runner-runs-on.test.mjs, which evaluates the real expression
+ *      rather than matching its spelling.)
+ *
  * What this lint deliberately does NOT flag: `${{ }}` in `runs.steps[].with`
  * (e.g. `dest: ${{ inputs['pnpm-dest'] || format('{0}/pnpm', runner.temp) }}`)
  * is a VALID runtime expression. The lint only inspects `description` and
@@ -266,6 +280,31 @@ export function checkWorkflowContent(content) {
     }
   }
 
+
+  // Rule 4: no `runs-on` that consumes a `runner` input raw. GitHub does not
+  // parse a JSON-array STRING in that position — it takes the whole text as one
+  // label name — so the documented `'["self-hosted","my-runner"]'` form matches
+  // no runner and every job sits `queued` until the 24-hour timeout. The failure
+  // is silent (no job starts, so no logs, and `gh pr checks` shows `pending 0`),
+  // which is why it needs a static tripwire as well as the behavioural guard in
+  // check-runner-runs-on.test.mjs.
+  content.split("\n").forEach((raw, idx) => {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("runs-on:")) return;
+    const m = trimmed.match(/^runs-on:\s*\$\{\{(.+)\}\}\s*$/);
+    if (!m) return;
+    if (m[1].trim() !== "inputs.runner") return;
+    violations.push({
+      line: idx + 1,
+      message:
+        `\`runs-on: \${{ inputs.runner }}\` consumes the input raw — a ` +
+        `JSON-encoded label-array string resolves to ONE unmatchable label ` +
+        `name and the job queues until the 24-hour timeout, silently. ` +
+        `Normalize it: \`fromJSON(startsWith(inputs.runner, '[') && ` +
+        `inputs.runner || format('"{0}"', inputs.runner))\`.`,
+    });
+  });
+
   return violations;
 }
 

package/scripts/check-workflow-portability.test.mjs

@@ -197,3 +197,69 @@ test("parseArgs: --no-pin-check, dir overrides, and --help are parsed", () => {
     help: true,
   });
 });
+
+// ---------------------------------------------------------------------------
+// Rule 4 — `runs-on` must not consume a `runner` input raw (Story #421)
+// ---------------------------------------------------------------------------
+
+/** A minimal reusable workflow whose single job's `runs-on` is `value`. */
+function runnerWorkflow(value) {
+  return [
+    "on:",
+    "  workflow_call:",
+    "    inputs:",
+    "      runner:",
+    "        required: false",
+    "        type: string",
+    "        default: 'ubuntu-latest'",
+    "jobs:",
+    "  build:",
+    `    runs-on: ${value}`,
+    "    steps:",
+    "      - run: echo hi",
+    "",
+  ].join("\n");
+}
+
+const NORMALIZED =
+  "${{ fromJSON(startsWith(inputs.runner, '[') && inputs.runner " +
+  "|| format('\"{0}\"', inputs.runner)) }}";
+
+test("Rule 4: a raw `runs-on: ${{ inputs.runner }}` is a violation", () => {
+  const violations = checkWorkflowContent(runnerWorkflow("${{ inputs.runner }}"));
+  assert.equal(violations.length, 1);
+  assert.equal(violations[0].line, 10);
+  assert.match(violations[0].message, /consumes the input raw/);
+  // The message must name the failure mode, not just the rule — a silent
+  // 24-hour queue is not something a reader infers from "normalize this".
+  assert.match(violations[0].message, /queues until the 24-hour timeout/);
+});
+
+test("Rule 4: the normalized form is clean", () => {
+  assert.deepEqual(checkWorkflowContent(runnerWorkflow(NORMALIZED)), []);
+});
+
+test("Rule 4: a hardcoded `runs-on` is untouched", () => {
+  assert.deepEqual(checkWorkflowContent(runnerWorkflow("ubuntu-latest")), []);
+});
+
+test("Rule 4: an unrelated expression in `runs-on` is untouched", () => {
+  // Only the exact raw-input read is flagged; a caller doing its own
+  // normalization or reading a different context is none of this rule's business.
+  assert.deepEqual(checkWorkflowContent(runnerWorkflow("${{ fromJSON(vars.CI_RUNNER) }}")), []);
+  assert.deepEqual(checkWorkflowContent(runnerWorkflow("${{ inputs.runner-label }}")), []);
+});
+
+test("Rule 4: only reusable workflows are checked", () => {
+  // A `push`-triggered workflow has no workflow_call interface to break.
+  const plain = [
+    "on:",
+    "  push:",
+    "    branches: [main]",
+    "jobs:",
+    "  build:",
+    "    runs-on: ${{ inputs.runner }}",
+    "",
+  ].join("\n");
+  assert.deepEqual(checkWorkflowContent(plain), []);
+});

package/scripts/lib/actions-expression.mjs

@@ -0,0 +1,271 @@
+/**
+ * actions-expression.mjs — a minimal GitHub Actions expression evaluator.
+ *
+ * Extracted from check-toolchain-cache-default.test.mjs (Story #364) when a
+ * second guard needed it (Story #421). It exists because **a `grep` is not an
+ * acceptance criterion for a workflow expression**: string-matching pins the
+ * spelling, not the behaviour, and both expression defects this repo has
+ * shipped read correctly and evaluated wrong. Extract the real expression from
+ * the YAML and RUN it.
+ *
+ * Supported surface — only what the guarded expressions use: string literals,
+ * `inputs.<name>` / `inputs['<name>']` reads, `==`/`!=`, `&&`/`||`,
+ * parentheses, and `contains()`, `startsWith()`, `format()`, `fromJSON()`.
+ *
+ * The semantics that matter, and that a hand-read gets wrong:
+ *
+ *   - `a && b` yields `b` when `a` is truthy, else `a`.
+ *   - `a || b` yields `a` when `a` is truthy, else `b`.
+ *     Both yield OPERANDS, not booleans.
+ *   - EVERY non-empty string is truthy — including the string `'false'`.
+ *   - Arrays and objects are truthy. GitHub documents the falsy set as exactly
+ *     `false`, `0`, `-0`, `''`, `null`; an array is not in it.
+ *   - String comparison is case-insensitive.
+ *
+ * ## On short-circuiting
+ *
+ * This evaluator parses to an AST first and evaluates `&&`/`||` lazily, which
+ * is the standard semantic. GitHub does NOT document whether its own evaluator
+ * short-circuits, so a guarded expression **must not depend on it** — never
+ * place a throwing call (`fromJSON` on caller-controlled text) in a branch that
+ * is only conditionally reached. Wrap the conditional instead:
+ *
+ *     fromJSON(cond && '<json>' || '<json>')     ← safe under either semantic
+ *     cond && fromJSON(x) || x                   ← safe ONLY if lazy
+ *
+ * Evaluating lazily here while requiring the safe shape in the workflows means
+ * the guard cannot bless an expression whose correctness rests on an
+ * unverified assumption about GitHub's evaluator.
+ *
+ * Errors are thrown as plain `Error`s; nothing here depends on a test framework.
+ */
+
+/** Actions truthiness — NOT JavaScript's. */
+export function truthy(v) {
+  if (typeof v === "boolean") return v;
+  if (typeof v === "number") return v !== 0;
+  if (typeof v === "string") return v !== "";
+  return v !== null && v !== undefined;
+}
+
+/** Actions comparison: case-insensitive for strings. */
+export function looseEqual(a, b) {
+  if (typeof a === "string" && typeof b === "string") {
+    return a.toLowerCase() === b.toLowerCase();
+  }
+  return a === b;
+}
+
+function fail(message) {
+  throw new Error(`[actions-expression] ${message}`);
+}
+
+const FUNCTIONS = new Map([
+  ["contains", 2],
+  ["startsWith", 2],
+  ["endsWith", 2],
+  ["fromJSON", 1],
+]);
+
+/** Parse `expr` into an AST. Exported for tests that assert on shape. */
+export function parse(expr) {
+  let i = 0;
+
+  const ws = () => {
+    while (i < expr.length && /\s/.test(expr[i])) i++;
+  };
+  const eat = (token) => {
+    ws();
+    if (expr.startsWith(token, i)) {
+      i += token.length;
+      return true;
+    }
+    return false;
+  };
+
+  function parseOr() {
+    let left = parseAnd();
+    for (;;) {
+      ws();
+      if (!eat("||")) return left;
+      left = { kind: "or", left, right: parseAnd() };
+    }
+  }
+
+  function parseAnd() {
+    let left = parseCompare();
+    for (;;) {
+      ws();
+      if (!eat("&&")) return left;
+      left = { kind: "and", left, right: parseCompare() };
+    }
+  }
+
+  function parseCompare() {
+    const left = parsePrimary();
+    ws();
+    if (eat("!=")) return { kind: "ne", left, right: parsePrimary() };
+    if (eat("==")) return { kind: "eq", left, right: parsePrimary() };
+    return left;
+  }
+
+  function parsePrimary() {
+    ws();
+    if (eat("(")) {
+      const node = parseOr();
+      ws();
+      if (!eat(")")) fail(`unbalanced parenthesis at ${i} in: ${expr}`);
+      return node;
+    }
+    if (expr[i] === "'") {
+      i++;
+      let out = "";
+      while (i < expr.length) {
+        if (expr[i] === "'" && expr[i + 1] === "'") {
+          out += "'";
+          i += 2;
+          continue;
+        }
+        if (expr[i] === "'") {
+          i++;
+          return { kind: "literal", value: out };
+        }
+        out += expr[i++];
+      }
+      fail(`unterminated string literal in: ${expr}`);
+    }
+    for (const [name, arity] of FUNCTIONS) {
+      if (!expr.startsWith(`${name}(`, i)) continue;
+      i += `${name}(`.length;
+      const args = [parseOr()];
+      while (args.length < arity) {
+        ws();
+        if (!eat(",")) fail(`${name}() expects ${arity} arguments in: ${expr}`);
+        args.push(parseOr());
+      }
+      ws();
+      if (!eat(")")) fail(`unclosed ${name}() in: ${expr}`);
+      return { kind: "call", name, args };
+    }
+    // `format()` is variadic, so it is parsed separately from the fixed-arity table.
+    if (expr.startsWith("format(", i)) {
+      i += "format(".length;
+      const args = [parseOr()];
+      for (;;) {
+        ws();
+        if (!eat(",")) break;
+        args.push(parseOr());
+      }
+      ws();
+      if (!eat(")")) fail(`unclosed format() in: ${expr}`);
+      return { kind: "call", name: "format", args };
+    }
+    const ident = expr.slice(i).match(/^[A-Za-z_][A-Za-z0-9_.\-]*(\['[^']*'\])?/);
+    if (!ident) fail(`unparseable token at ${i} in: ${expr}`);
+    i += ident[0].length;
+    const raw = ident[0];
+    if (raw === "true") return { kind: "literal", value: true };
+    if (raw === "false") return { kind: "literal", value: false };
+    const bracket = raw.match(/^inputs\['([^']*)'\]$/);
+    const dotted = raw.match(/^inputs\.(.+)$/);
+    const key = bracket ? bracket[1] : dotted ? dotted[1] : null;
+    if (key === null) fail(`unsupported context read \`${raw}\` in: ${expr}`);
+    return { kind: "input", key };
+  }
+
+  const ast = parseOr();
+  ws();
+  if (i !== expr.length) fail(`trailing tokens at ${i} in: ${expr}`);
+  return ast;
+}
+
+function applyFormat(args) {
+  const template = String(args[0]);
+  const rest = args.slice(1);
+  let out = "";
+  for (let k = 0; k < template.length; k++) {
+    const ch = template[k];
+    if (ch === "{" && template[k + 1] === "{") {
+      out += "{";
+      k++;
+    } else if (ch === "}" && template[k + 1] === "}") {
+      out += "}";
+      k++;
+    } else if (ch === "{") {
+      const close = template.indexOf("}", k);
+      if (close === -1) fail(`unclosed format placeholder in: ${template}`);
+      const idx = Number(template.slice(k + 1, close));
+      if (!Number.isInteger(idx)) fail(`non-numeric format placeholder in: ${template}`);
+      out += rest[idx] === undefined ? "" : String(rest[idx]);
+      k = close;
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+
+function evalNode(node, inputs) {
+  switch (node.kind) {
+    case "literal":
+      return node.value;
+    case "input":
+      if (!(node.key in inputs)) {
+        fail(`expression reads \`inputs.${node.key}\`, not provided by the caller`);
+      }
+      return inputs[node.key];
+    case "and": {
+      // Lazy on purpose — see the module header's note on short-circuiting.
+      const left = evalNode(node.left, inputs);
+      return truthy(left) ? evalNode(node.right, inputs) : left;
+    }
+    case "or": {
+      const left = evalNode(node.left, inputs);
+      return truthy(left) ? left : evalNode(node.right, inputs);
+    }
+    case "eq":
+      return looseEqual(evalNode(node.left, inputs), evalNode(node.right, inputs));
+    case "ne":
+      return !looseEqual(evalNode(node.left, inputs), evalNode(node.right, inputs));
+    case "call": {
+      const args = node.args.map((a) => evalNode(a, inputs));
+      if (node.name === "format") return applyFormat(args);
+      const [a, b] = args;
+      if (node.name === "contains") {
+        // Substring on a string haystack; exact-item match on an array one.
+        if (Array.isArray(a)) return a.some((item) => looseEqual(item, b));
+        return String(a).toLowerCase().includes(String(b).toLowerCase());
+      }
+      if (node.name === "startsWith") {
+        return String(a).toLowerCase().startsWith(String(b).toLowerCase());
+      }
+      if (node.name === "endsWith") {
+        return String(a).toLowerCase().endsWith(String(b).toLowerCase());
+      }
+      if (node.name === "fromJSON") {
+        try {
+          return JSON.parse(String(a));
+        } catch {
+          // A parse failure is a HARD expression error in Actions — the run
+          // fails rather than yielding null, which is what makes a malformed
+          // `runner` value loud instead of silently unmatchable.
+          fail(`fromJSON() could not parse ${JSON.stringify(String(a))} in this expression`);
+        }
+      }
+      return fail(`unsupported function \`${node.name}\``);
+    }
+    default:
+      return fail(`unsupported node kind \`${node.kind}\``);
+  }
+}
+
+/**
+ * Evaluate `expr` (the body BETWEEN `${{` and `}}`) against `inputs`.
+ *
+ * @param {string} expr
+ * @param {Record<string, unknown>} inputs values for `inputs.*` reads
+ * @returns {unknown} the resulting operand — a string, boolean, or array
+ */
+export function evaluate(expr, inputs) {
+  return evalNode(parse(expr), inputs);
+}

package/scripts/lib/actions-expression.test.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * actions-expression.test.mjs — the evaluator must be trustworthy before it
+ * can judge a workflow (Story #421).
+ *
+ * These assertions are the reason the evaluator exists: every one of them is a
+ * place where Actions semantics diverge from JavaScript's, and where a
+ * hand-read of an expression gets the wrong answer.
+ *
+ * Run: node --test scripts/lib/actions-expression.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { evaluate, truthy } from "./actions-expression.mjs";
+
+test("`&&` and `||` yield OPERANDS, not booleans", () => {
+  assert.equal(evaluate("true && 'kept'", {}), "kept");
+  assert.equal(evaluate("'' || 'fallback'", {}), "fallback");
+  assert.equal(evaluate("'a' || 'b'", {}), "a");
+});
+
+test("every non-empty string is truthy — including the string 'false'", () => {
+  // The trap the toolchain-cache expression depends on: an explicitly-pinned
+  // 'false' must survive the first arm of the ternary rather than falling
+  // through to the derivation.
+  assert.equal(evaluate("'false' && 'yes' || 'no'", {}), "yes");
+  assert.equal(truthy("false"), true);
+  assert.equal(truthy(""), false);
+});
+
+test("arrays are truthy — the property the runs-on normalization rests on", () => {
+  // GitHub documents the falsy set as exactly false, 0, -0, '', null. An array
+  // is not in it, so a parsed label array carries through `&&` / `||`.
+  assert.equal(truthy([]), true);
+  assert.equal(truthy(["self-hosted"]), true);
+});
+
+test("comparison is case-insensitive", () => {
+  assert.equal(evaluate("'AUTO' == 'auto'", {}), true);
+  assert.equal(evaluate("'AUTO' != 'auto'", {}), false);
+});
+
+test("contains() is substring on a string and exact-item on an array", () => {
+  assert.equal(evaluate("contains('[\"self-hosted\",\"x\"]', 'self-hosted')", {}), true);
+  assert.equal(evaluate("contains(inputs.r, 'self-hosted')", { r: ["self-hosted", "x"] }), true);
+  // Exact-item, NOT substring, once the haystack is an array.
+  assert.equal(evaluate("contains(inputs.r, 'self')", { r: ["self-hosted"] }), false);
+});
+
+test("startsWith() casts to string and is case-insensitive", () => {
+  assert.equal(evaluate("startsWith('[\"a\"]', '[')", {}), true);
+  assert.equal(evaluate("startsWith('ubuntu-latest', '[')", {}), false);
+  assert.equal(evaluate("startsWith('UBUNTU', 'ub')", {}), true);
+});
+
+test("format() substitutes positionally and unescapes doubled braces", () => {
+  assert.equal(evaluate("format('\"{0}\"', inputs.r)", { r: "my-runner" }), '"my-runner"');
+  assert.equal(evaluate("format('{{{0}}}', inputs.r)", { r: "x" }), "{x}");
+});
+
+test("fromJSON() parses arrays and scalars", () => {
+  assert.deepEqual(evaluate("fromJSON('[\"self-hosted\",\"x\"]')", {}), ["self-hosted", "x"]);
+  assert.equal(evaluate("fromJSON('\"bare-label\"')", {}), "bare-label");
+});
+
+test("fromJSON() on malformed input THROWS — it does not yield null", () => {
+  // Load-bearing: in Actions a fromJSON parse failure fails the run. If it
+  // degraded to null here, a malformed `runner` would look like a clean
+  // fallback in the guard while hanging forever in production.
+  assert.throws(() => evaluate("fromJSON('[\"unterminated')", {}), /could not parse/);
+});
+
+test("`&&` / `||` short-circuit, so an unreached branch is never evaluated", () => {
+  // The evaluator is lazy. Guarded workflow expressions must NOT rely on that
+  // (GitHub does not document its own behaviour here) — but modelling it
+  // faithfully keeps the guard honest about what it is asserting.
+  assert.equal(evaluate("false && fromJSON('nonsense') || 'safe'", {}), "safe");
+});
+
+test("an unknown input read is an error, not a silent undefined", () => {
+  assert.throws(() => evaluate("inputs.missing", {}), /not provided by the caller/);
+});