mandrel-platform 0.27.1 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.27.1",
+  "version": "0.29.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {

package/scripts/osv-report-gate.test.mjs

@@ -0,0 +1,227 @@
+// Unit coverage for the OSV report severity-band gate (Story #310).
+//
+// This logic used to live as a heredoc inside pr-quality.yml and was
+// therefore untestable. The banding thresholds, the Story #145 allow-list
+// schema validation, and the `revisitBy` re-gating are the load-bearing
+// pieces — a silent regression in any of them either lets a real advisory
+// through or blocks a legitimately-suppressed one. These tests pin them.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  bandOf,
+  collectRows,
+  loadAllowlist,
+  classify,
+  findingsDigest,
+  renderSummary,
+  OsvGateError,
+} from "../.github/actions/osv-scan/osv-report-gate.mjs";
+
+// Build an OSV-scanner-shaped report for one grouped advisory.
+const reportWith = (groups) => ({
+  results: [
+    {
+      source: { path: "pnpm-lock.yaml" },
+      packages: groups.map((g) => ({
+        package: { name: g.name, version: g.version || "1.0.0", ecosystem: g.ecosystem || "npm" },
+        groups: [{ ids: g.ids, max_severity: g.score }],
+      })),
+    },
+  ],
+});
+
+test("bandOf buckets CVSS scores into the documented bands", () => {
+  assert.equal(bandOf(9.8), "critical");
+  assert.equal(bandOf(9.0), "critical");
+  assert.equal(bandOf(7.5), "high");
+  assert.equal(bandOf(7.0), "high");
+  assert.equal(bandOf(4.0), "medium");
+  assert.equal(bandOf(6.9), "medium");
+  assert.equal(bandOf(0.1), "low");
+  assert.equal(bandOf(0), "none");
+  assert.equal(bandOf(NaN), "none");
+});
+
+test("a high finding blocks at the default gate; a medium finding warns", () => {
+  const rows = collectRows(
+    reportWith([
+      { name: "brace-expansion", ids: ["GHSA-3jxr-9vmj-r5cp"], score: "7.5" },
+      { name: "some-medium", ids: ["GHSA-medium"], score: "5.0" },
+    ]),
+  );
+  const v = classify(rows, { failOn: "high" });
+  assert.equal(v.blocking.length, 1);
+  assert.equal(v.blocking[0].ids[0], "GHSA-3jxr-9vmj-r5cp");
+  assert.equal(v.warning.length, 1);
+  assert.equal(v.warning[0].ids[0], "GHSA-medium");
+});
+
+test("critical, high, medium, low, none all classify against a high gate", () => {
+  const rows = collectRows(
+    reportWith([
+      { name: "crit", ids: ["C"], score: "9.9" },
+      { name: "hi", ids: ["H"], score: "7.1" },
+      { name: "med", ids: ["M"], score: "4.5" },
+      { name: "lo", ids: ["L"], score: "1.0" },
+      { name: "un", ids: ["U"], score: "" }, // unscored → none
+    ]),
+  );
+  const v = classify(rows, { failOn: "high" });
+  assert.deepEqual(
+    v.blocking.map((r) => r.band),
+    ["critical", "high"],
+  );
+  assert.deepEqual(
+    v.warning.map((r) => r.band),
+    ["medium", "low", "none"],
+  );
+});
+
+test("an advisory with no group still counts as an unscored 'none' finding", () => {
+  const report = {
+    results: [
+      {
+        source: { path: "package-lock.json" },
+        packages: [
+          {
+            package: { name: "loner", version: "2.0.0", ecosystem: "npm" },
+            vulnerabilities: [{ id: "GHSA-ungrouped" }],
+          },
+        ],
+      },
+    ],
+  };
+  const rows = collectRows(report);
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].band, "none");
+  assert.equal(rows[0].ids[0], "GHSA-ungrouped");
+});
+
+test("a missing allow-list yields gating identical to no allow-list", () => {
+  // exists() returns false → empty list, no throw.
+  const allowlist = loadAllowlist(".osv-allowlist.json", { exists: () => false });
+  assert.deepEqual(allowlist, []);
+
+  const rows = collectRows(reportWith([{ name: "brace-expansion", ids: ["GHSA-x"], score: "7.5" }]));
+  const withMissing = classify(rows, { failOn: "high", allowlist });
+  const withNone = classify(rows, { failOn: "high", allowlist: [] });
+  assert.deepEqual(withMissing.blocking, withNone.blocking);
+  assert.equal(withMissing.blocking.length, 1);
+});
+
+test("a present-but-malformed allow-list is a hard error, not a silent match", () => {
+  const opts = { exists: () => true, readFile: () => "{ not json" };
+  assert.throws(() => loadAllowlist(".osv-allowlist.json", opts), OsvGateError);
+
+  const notArray = { exists: () => true, readFile: () => JSON.stringify({ nope: true }) };
+  assert.throws(() => loadAllowlist(".osv-allowlist.json", notArray), OsvGateError);
+
+  const missingReason = {
+    exists: () => true,
+    readFile: () => JSON.stringify([{ id: "GHSA-x", revisitBy: "2099-01-01" }]),
+  };
+  assert.throws(() => loadAllowlist(".osv-allowlist.json", missingReason), OsvGateError);
+
+  const badDate = {
+    exists: () => true,
+    readFile: () => JSON.stringify([{ id: "GHSA-x", reason: "triaged", revisitBy: "soon" }]),
+  };
+  assert.throws(() => loadAllowlist(".osv-allowlist.json", badDate), OsvGateError);
+});
+
+test("an unexpired suppression moves a blocking finding to suppressed", () => {
+  const rows = collectRows(
+    reportWith([{ name: "brace-expansion", ids: ["GHSA-3jxr-9vmj-r5cp"], score: "7.5" }]),
+  );
+  const allowlist = [
+    { id: "GHSA-3jxr-9vmj-r5cp", reason: "no reachable sink", revisitBy: "2099-12-31" },
+  ];
+  const v = classify(rows, { failOn: "high", allowlist, today: "2026-07-21" });
+  assert.equal(v.blocking.length, 0);
+  assert.equal(v.suppressed.length, 1);
+  assert.equal(v.expired.length, 0);
+});
+
+test("a suppression past revisitBy re-gates as blocking", () => {
+  const rows = collectRows(
+    reportWith([{ name: "brace-expansion", ids: ["GHSA-3jxr-9vmj-r5cp"], score: "7.5" }]),
+  );
+  const allowlist = [
+    { id: "GHSA-3jxr-9vmj-r5cp", reason: "stale triage", revisitBy: "2026-01-01" },
+  ];
+  const v = classify(rows, { failOn: "high", allowlist, today: "2026-07-21" });
+  assert.equal(v.blocking.length, 1);
+  assert.equal(v.expired.length, 1);
+  assert.equal(v.suppressed.length, 0);
+});
+
+test("a package/ecosystem-scoped suppression only matches its own package", () => {
+  const rows = collectRows(
+    reportWith([
+      { name: "brace-expansion", ids: ["GHSA-shared"], score: "7.5" },
+      { name: "other-pkg", ids: ["GHSA-shared"], score: "7.5" },
+    ]),
+  );
+  const allowlist = [
+    {
+      id: "GHSA-shared",
+      reason: "only brace-expansion is unreachable",
+      revisitBy: "2099-12-31",
+      package: "brace-expansion",
+      ecosystem: "npm",
+    },
+  ];
+  const v = classify(rows, { failOn: "high", allowlist, today: "2026-07-21" });
+  assert.equal(v.suppressed.length, 1);
+  assert.equal(v.suppressed[0].name, "brace-expansion");
+  assert.equal(v.blocking.length, 1);
+  assert.equal(v.blocking[0].name, "other-pkg");
+});
+
+test("an invalid fail-on band is a hard error", () => {
+  assert.throws(() => classify([], { failOn: "sky-high" }), OsvGateError);
+});
+
+test("findingsDigest is stable across row order and ignores below-gate rows", () => {
+  const a = collectRows(
+    reportWith([
+      { name: "p1", ids: ["GHSA-a"], score: "7.5" },
+      { name: "p2", ids: ["GHSA-b"], score: "9.1" },
+    ]),
+  );
+  const b = collectRows(
+    reportWith([
+      { name: "p2", ids: ["GHSA-b"], score: "9.1" },
+      { name: "p1", ids: ["GHSA-a"], score: "7.5" },
+    ]),
+  );
+  const va = classify(a, { failOn: "high" });
+  const vb = classify(b, { failOn: "high" });
+  assert.equal(findingsDigest(va.blocking), findingsDigest(vb.blocking));
+
+  // A new blocking advisory changes the digest.
+  const c = collectRows(
+    reportWith([
+      { name: "p1", ids: ["GHSA-a"], score: "7.5" },
+      { name: "p2", ids: ["GHSA-b"], score: "9.1" },
+      { name: "p3", ids: ["GHSA-c"], score: "8.0" },
+    ]),
+  );
+  const vc = classify(c, { failOn: "high" });
+  assert.notEqual(findingsDigest(va.blocking), findingsDigest(vc.blocking));
+});
+
+test("renderSummary reports a clean scan and a blocked scan distinctly", () => {
+  const clean = renderSummary(classify([], { failOn: "high" }));
+  assert.match(clean.join("\n"), /no known advisories/);
+
+  const blocked = renderSummary(
+    classify(collectRows(reportWith([{ name: "p", ids: ["GHSA-x"], score: "9.0" }])), {
+      failOn: "high",
+    }),
+  );
+  assert.match(blocked.join("\n"), /❌ BLOCKED/);
+  assert.match(blocked.join("\n"), /GHSA-x/);
+});

package/scripts/osv-track-issue.test.mjs

@@ -0,0 +1,91 @@
+// Unit coverage for the OSV tracking-issue upsert verdict (Story #310).
+//
+// The whole point of the scheduled advisory workflow is a SINGLE tracking
+// issue that does not spam: it must open once, stay quiet while the finding
+// set is unchanged, update only on a real change, and close when the set
+// clears. That contract is the pure `decideVerdict` function — these tests
+// pin every branch of it, plus the marker round-trip and the gh-driven
+// lookup, without any network access.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  decideVerdict,
+  extractDigest,
+  digestMarker,
+  buildIssueBody,
+  findTrackingIssue,
+  TRACKER_MARKER,
+} from "../.github/actions/osv-track-issue/osv-track-issue.mjs";
+
+const issueWithDigest = (number, digest) => ({
+  number,
+  body: buildIssueBody({ digest, summary: "…", repo: "acme/app", branch: "main" }),
+});
+
+test("CREATE when blocking findings exist and no tracking issue is open", () => {
+  const v = decideVerdict(null, { blockingCount: 2, digest: "abcd1234-2" });
+  assert.equal(v.action, "create");
+});
+
+test("NOOP when the open issue already reflects this exact finding set", () => {
+  const existing = issueWithDigest(42, "abcd1234-2");
+  const v = decideVerdict(existing, { blockingCount: 2, digest: "abcd1234-2" });
+  assert.equal(v.action, "noop");
+});
+
+test("UPDATE when the finding-set digest changed since the issue was written", () => {
+  const existing = issueWithDigest(42, "abcd1234-2");
+  const v = decideVerdict(existing, { blockingCount: 3, digest: " zzzz9999-3".trim() });
+  assert.equal(v.action, "update");
+});
+
+test("CLOSE when the blocking set is now empty but an issue is still open", () => {
+  const existing = issueWithDigest(42, "abcd1234-2");
+  const v = decideVerdict(existing, { blockingCount: 0, digest: "empty-0" });
+  assert.equal(v.action, "close");
+});
+
+test("NOOP when there are no blocking findings and no issue to close", () => {
+  const v = decideVerdict(null, { blockingCount: 0, digest: "empty-0" });
+  assert.equal(v.action, "noop");
+});
+
+test("a finding set of only allow-list-suppressed advisories never opens an issue", () => {
+  // Suppressed / below-gate findings do not count toward blockingCount, so the
+  // gate hands this path blockingCount: 0 — verdict must be close/noop, not create.
+  assert.equal(decideVerdict(null, { blockingCount: 0, digest: "empty-0" }).action, "noop");
+  const existing = issueWithDigest(7, "abcd1234-1");
+  assert.equal(decideVerdict(existing, { blockingCount: 0, digest: "empty-0" }).action, "close");
+});
+
+test("the digest marker round-trips through a rendered issue body", () => {
+  assert.match(digestMarker("deadbeef-4"), /mandrel:osv-advisory-digest: deadbeef-4/);
+  const body = buildIssueBody({ digest: "deadbeef-4", summary: "s", repo: "a/b", branch: "main" });
+  assert.ok(body.includes(TRACKER_MARKER));
+  assert.equal(extractDigest(body), "deadbeef-4");
+  assert.equal(extractDigest("no markers here"), null);
+});
+
+test("findTrackingIssue confirms the marker rather than trusting the search hint", () => {
+  const calls = [];
+  const runner = (args, opts) => {
+    calls.push({ args, opts });
+    // gh's `in:body` search is fuzzy — return one true match and one false positive.
+    return JSON.stringify([
+      { number: 99, body: "unrelated issue mentioning osv-advisory in prose" },
+      { number: 100, body: `${TRACKER_MARKER}\n${digestMarker("x-1")}\nbody` },
+    ]);
+  };
+  const found = findTrackingIssue({ repo: "acme/app", labels: ["security"] }, runner);
+  assert.equal(found.number, 100);
+  // The label scope is forwarded to gh.
+  assert.ok(calls[0].args.includes("--label"));
+  assert.ok(calls[0].args.includes("security"));
+});
+
+test("findTrackingIssue returns null when nothing carries the marker", () => {
+  const runner = () => JSON.stringify([{ number: 1, body: "no marker" }]);
+  assert.equal(findTrackingIssue({ repo: "acme/app", labels: [] }, runner), null);
+});

package/scripts/resolve-diff-range.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# resolve-diff-range.sh — the SINGLE, event-agnostic base/head SHA derivation
+# shared by every diff-scoped tier of pr-quality.yml (Story #314).
+#
+# WHY THIS EXISTS
+# ---------------
+# The diff-scoped security tiers (gitleaks secret scan + Semgrep SAST) must
+# scope their scan to the commits the triggering event INTRODUCED, so a
+# pre-existing finding never blocks. Each event exposes that base/head pair
+# under a different context path:
+#
+#   pull_request → github.event.pull_request.base.sha / .head.sha
+#   merge_group  → github.event.merge_group.base_sha  / .head_sha
+#   push         → github.event.before                / github.sha
+#
+# Under a `merge_group` (merge-queue) event `github.event.pull_request.*` is
+# empty, so without this derivation the tiers degrade to a FULL-TREE scan and
+# surface pre-existing findings unrelated to the queued commits — bouncing the
+# whole queue batch. Deriving base/head from the merge_group context instead
+# keeps the queue diff-scoped. This file is the one place that classification
+# lives, so gitleaks and SAST cannot drift apart.
+#
+# CONTRACT
+# --------
+# SOURCE this file (do NOT exec it) from a `shell: bash` step, after the repo
+# has been checked out with `fetch-depth: 0`. It reads the env vars below (all
+# optional; an absent context evaluates to the empty string in a GitHub
+# expression, so nothing here can `startup_failure` on a missing context) and
+# sets three variables in the CALLER's shell:
+#
+#   Inputs (wire each to the matching context in the step's `env:` block):
+#     PR_BASE_SHA          = github.event.pull_request.base.sha
+#     PR_HEAD_SHA          = github.event.pull_request.head.sha
+#     MERGE_GROUP_BASE_SHA = github.event.merge_group.base_sha
+#     MERGE_GROUP_HEAD_SHA = github.event.merge_group.head_sha
+#     EVENT_NAME           = github.event_name
+#     PUSH_BEFORE_SHA      = github.event.before
+#     PUSH_HEAD_SHA        = github.sha
+#
+#   Outputs (set on the caller's shell):
+#     RESOLVED_EVENT_MODE = pull_request | merge_group | push | none
+#     RESOLVED_BASE_SHA   = <base commit>   (empty when mode = none)
+#     RESOLVED_HEAD_SHA   = <head commit>   (empty when mode = none)
+#
+# Each consumer applies its own shaping to the raw pair: gitleaks builds a
+# `base..head` git-log range (`..` already excludes base-branch drift, so no
+# explicit merge-base is needed); SAST needs a single `--baseline-commit`, and
+# for pull_request derives the merge base of base..head (M8: base.sha is the
+# live base-branch tip and drifts past the fork point once main advances),
+# while for merge_group / push the base is already the exact fork point.
+#
+# `mode = none` means "no ranged base is resolvable" → the consumer falls back
+# to a full-tree scan. This is reached by an absent context (queue no-op, or a
+# branch-creation push whose `before` is the zero SHA / an unreachable commit).
+
+resolve_diff_range() {
+  local zero_sha="0000000000000000000000000000000000000000"
+  RESOLVED_EVENT_MODE="none"
+  RESOLVED_BASE_SHA=""
+  RESOLVED_HEAD_SHA=""
+
+  if [ -n "${PR_BASE_SHA:-}" ] && [ -n "${PR_HEAD_SHA:-}" ]; then
+    # pull_request — the base-branch tip / PR head. Highest precedence so a
+    # caller that (unusually) exposes both PR and push context stays PR-scoped.
+    RESOLVED_EVENT_MODE="pull_request"
+    RESOLVED_BASE_SHA="${PR_BASE_SHA}"
+    RESOLVED_HEAD_SHA="${PR_HEAD_SHA}"
+  elif [ -n "${MERGE_GROUP_BASE_SHA:-}" ] && [ -n "${MERGE_GROUP_HEAD_SHA:-}" ]; then
+    # merge_group — the merge queue built base_sha..head_sha; head_sha is the
+    # temporary merge commit of the queued PR(s) on top of base_sha (the exact
+    # fork point, so no drift to correct for).
+    RESOLVED_EVENT_MODE="merge_group"
+    RESOLVED_BASE_SHA="${MERGE_GROUP_BASE_SHA}"
+    RESOLVED_HEAD_SHA="${MERGE_GROUP_HEAD_SHA}"
+  elif [ "${EVENT_NAME:-}" = "push" ] && [ -n "${PUSH_BEFORE_SHA:-}" ] && \
+       [ "${PUSH_BEFORE_SHA}" != "${zero_sha}" ] && \
+       git cat-file -e "${PUSH_BEFORE_SHA}^{commit}" 2>/dev/null; then
+    # push — the commits this push added (before..sha). `before` is the zero
+    # SHA on a branch-creation push, and may be unreachable after a
+    # force-push / shallow fetch; either case falls through to `none`.
+    RESOLVED_EVENT_MODE="push"
+    RESOLVED_BASE_SHA="${PUSH_BEFORE_SHA}"
+    RESOLVED_HEAD_SHA="${PUSH_HEAD_SHA}"
+  fi
+}
+
+resolve_diff_range
+
+# When EXECUTED directly (not sourced) — e.g. by the unit test — echo the
+# resolution as `KEY=value` lines so the truth table is assertable without a
+# GitHub runner. `BASH_SOURCE[0] == $0` iff the file was run, not sourced.
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  printf 'RESOLVED_EVENT_MODE=%s\n' "${RESOLVED_EVENT_MODE}"
+  printf 'RESOLVED_BASE_SHA=%s\n' "${RESOLVED_BASE_SHA}"
+  printf 'RESOLVED_HEAD_SHA=%s\n' "${RESOLVED_HEAD_SHA}"
+fi

package/scripts/resolve-diff-range.test.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * resolve-diff-range.test.mjs — node:test suite for the single, event-agnostic
+ * base/head SHA derivation shared by every diff-scoped tier of pr-quality.yml
+ * (Story #314).
+ *
+ * The workflow's gitleaks and SAST resolvers both `source` this shell script,
+ * so its truth table IS the derived range each tier scans. This suite executes
+ * the script directly (it echoes `RESOLVED_*=…` lines when run rather than
+ * sourced) with per-event env fixtures and asserts the derived base/head for
+ * each of the three events plus the full-tree fallbacks — the "self-test
+ * showing the derived range for each event" half of the Story's Verify.
+ *
+ * Run: node scripts/resolve-diff-range.test.mjs  (or `node --test scripts/`)
+ */
+
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = join(HERE, "resolve-diff-range.sh");
+// The repo root is a git repo, so the push-mode reachability guard
+// (`git cat-file -e <before>`) can resolve a real ancestor commit.
+const REPO_ROOT = join(HERE, "..");
+
+// A real, reachable commit for exercising the push reachability guard, and its
+// parent (also reachable) to stand in as the "before" SHA.
+const HEAD_SHA = execFileSync("git", ["rev-parse", "HEAD"], {
+  cwd: REPO_ROOT,
+  encoding: "utf8",
+}).trim();
+const PARENT_SHA = execFileSync("git", ["rev-parse", "HEAD~1"], {
+  cwd: REPO_ROOT,
+  encoding: "utf8",
+}).trim();
+
+const ZERO_SHA = "0000000000000000000000000000000000000000";
+// A syntactically-valid 40-hex SHA that is not an object in this repo.
+const UNREACHABLE_SHA = "dead0000dead0000dead0000dead0000dead0000";
+
+// Run the derivation with the given env and parse its `KEY=value` output.
+function resolve(env) {
+  const out = execFileSync("bash", [SCRIPT], {
+    cwd: REPO_ROOT,
+    encoding: "utf8",
+    // Start from a clean slate so the ambient CI env (which may itself set
+    // GITHUB_* / EVENT_NAME) cannot leak into the fixture.
+    env: { PATH: process.env.PATH, ...env },
+  });
+  const parsed = {};
+  for (const line of out.split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    parsed[line.slice(0, eq)] = line.slice(eq + 1);
+  }
+  return parsed;
+}
+
+test("pull_request: derives base.sha/head.sha directly", () => {
+  const r = resolve({
+    PR_BASE_SHA: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    PR_HEAD_SHA: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    EVENT_NAME: "pull_request",
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "pull_request");
+  assert.equal(r.RESOLVED_BASE_SHA, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+  assert.equal(r.RESOLVED_HEAD_SHA, "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");
+});
+
+test("merge_group: derives merge_group.base_sha/head_sha", () => {
+  const r = resolve({
+    MERGE_GROUP_BASE_SHA: "cccccccccccccccccccccccccccccccccccccccc",
+    MERGE_GROUP_HEAD_SHA: "dddddddddddddddddddddddddddddddddddddddd",
+    EVENT_NAME: "merge_group",
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "merge_group");
+  assert.equal(r.RESOLVED_BASE_SHA, "cccccccccccccccccccccccccccccccccccccccc");
+  assert.equal(r.RESOLVED_HEAD_SHA, "dddddddddddddddddddddddddddddddddddddddd");
+});
+
+test("pull_request takes precedence over a co-present merge_group context", () => {
+  const r = resolve({
+    PR_BASE_SHA: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    PR_HEAD_SHA: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    MERGE_GROUP_BASE_SHA: "cccccccccccccccccccccccccccccccccccccccc",
+    MERGE_GROUP_HEAD_SHA: "dddddddddddddddddddddddddddddddddddddddd",
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "pull_request");
+  assert.equal(r.RESOLVED_BASE_SHA, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+});
+
+test("merge_group takes precedence over a co-present push context", () => {
+  const r = resolve({
+    MERGE_GROUP_BASE_SHA: "cccccccccccccccccccccccccccccccccccccccc",
+    MERGE_GROUP_HEAD_SHA: "dddddddddddddddddddddddddddddddddddddddd",
+    EVENT_NAME: "push",
+    PUSH_BEFORE_SHA: PARENT_SHA,
+    PUSH_HEAD_SHA: HEAD_SHA,
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "merge_group");
+  assert.equal(r.RESOLVED_BASE_SHA, "cccccccccccccccccccccccccccccccccccccccc");
+});
+
+test("push: derives event.before/sha when before is a reachable commit", () => {
+  const r = resolve({
+    EVENT_NAME: "push",
+    PUSH_BEFORE_SHA: PARENT_SHA,
+    PUSH_HEAD_SHA: HEAD_SHA,
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "push");
+  assert.equal(r.RESOLVED_BASE_SHA, PARENT_SHA);
+  assert.equal(r.RESOLVED_HEAD_SHA, HEAD_SHA);
+});
+
+test("push with zero before (branch creation) → none/full-tree", () => {
+  const r = resolve({
+    EVENT_NAME: "push",
+    PUSH_BEFORE_SHA: ZERO_SHA,
+    PUSH_HEAD_SHA: HEAD_SHA,
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "none");
+  assert.equal(r.RESOLVED_BASE_SHA, "");
+  assert.equal(r.RESOLVED_HEAD_SHA, "");
+});
+
+test("push with an unreachable before (force-push/shallow) → none/full-tree", () => {
+  const r = resolve({
+    EVENT_NAME: "push",
+    PUSH_BEFORE_SHA: UNREACHABLE_SHA,
+    PUSH_HEAD_SHA: HEAD_SHA,
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "none");
+});
+
+test("no event context at all → none/full-tree (never a startup_failure)", () => {
+  const r = resolve({});
+  assert.equal(r.RESOLVED_EVENT_MODE, "none");
+  assert.equal(r.RESOLVED_BASE_SHA, "");
+  assert.equal(r.RESOLVED_HEAD_SHA, "");
+});
+
+test("merge_group with only base_sha (partial context) → none", () => {
+  const r = resolve({
+    MERGE_GROUP_BASE_SHA: "cccccccccccccccccccccccccccccccccccccccc",
+    EVENT_NAME: "merge_group",
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "none");
+});