@crvouga/atlas 1.10.0 → 1.11.0

package/packages/visualizer/src/app/router.tsx

@@ -31,7 +31,12 @@ const SpecSearch = RootSearch.extend({
   check: z.string().min(1).optional().catch(undefined),
   layer: z.string().min(1).optional().catch(undefined),
   view: z.enum(['recording']).optional().catch(undefined),
-  moment: z.coerce.number().int().positive().optional().catch(undefined)
+  moment: z.coerce.number().int().positive().optional().catch(undefined),
+  /** The release evidence is read against: its build, commit and platform, and the evidence filter (see `evidence/applicability.ts`). A build such as `90` is read from a typed link as a number: coerced back to its text. */
+  release: z.coerce.string().min(1).optional().catch(undefined),
+  releaseSha: z.coerce.string().min(1).optional().catch(undefined),
+  releasePlatform: z.coerce.string().min(1).optional().catch(undefined),
+  evidence: z.enum(['stale']).optional().catch(undefined)
 });
 export type SpecSearch = z.infer<typeof SpecSearch>;
 /** A fresh route tree per router, so a test can run its own viewer beside the page's. */

package/packages/visualizer/src/evidence/applicability-view.tsx

@@ -0,0 +1,233 @@
+/**
+ * @module Evidence applicability view
+ *
+ * Shows whether the evidence behind a behavior applies to it: a compact summary (verdict, when the checks ran, the
+ * promise, the release), the controls that name a release and filter to stale or unverified evidence, and the
+ * address state that keeps both shareable. A verdict is a reading of the evidence and never changes an outcome.
+ */
+import { Alert, Badge, Button, Group, List, Paper, SimpleGrid, Stack, Text, TextInput, Title } from '@mantine/core';
+import { useNavigate, useSearch } from '@tanstack/react-router';
+import { useCallback, useMemo } from 'react';
+
+import { hasRelease, VERDICTS, type Assessment, type ReleaseIdentity, type ReleaseMatch, type Verdict } from './applicability';
+import { exactTime, ago, plural, shortSha, useNow } from './format';
+
+/** The release and the evidence filter the address holds, with the ways to change them. */
+export type ApplicabilityState = {
+  readonly release: ReleaseIdentity;
+  /** True when only behaviors with stale or unverified evidence are listed. */
+  readonly onlyStale: boolean;
+  readonly setRelease: (next: ReleaseIdentity) => void;
+  readonly setOnlyStale: (on: boolean) => void;
+};
+
+/**
+ * The release (`release` build, `releaseSha`, `releasePlatform`) and evidence filter (`evidence=stale`) of the spec
+ * address. They are held in the address, so a shared link shows the same reading. Must be used under the spec route.
+ */
+export function useApplicabilityState(): ApplicabilityState {
+  const search = useSearch({ from: '/specs/$kind' });
+  const navigate = useNavigate({ from: '/specs/$kind' });
+  const release = useMemo<ReleaseIdentity>(
+    () => ({
+      ...(search.release ? { build: search.release } : {}),
+      ...(search.releaseSha ? { sha: search.releaseSha } : {}),
+      ...(search.releasePlatform ? { platform: search.releasePlatform } : {})
+    }),
+    [search.release, search.releaseSha, search.releasePlatform]
+  );
+  const setRelease = useCallback(
+    (next: ReleaseIdentity) =>
+      void navigate({
+        search: (prev) => ({
+          ...prev,
+          release: next.build || undefined,
+          releaseSha: next.sha || undefined,
+          releasePlatform: next.platform || undefined
+        }),
+        replace: true
+      }),
+    [navigate]
+  );
+  const setOnlyStale = useCallback(
+    (on: boolean) => void navigate({ search: (prev) => ({ ...prev, evidence: on ? ('stale' as const) : undefined }), replace: true }),
+    [navigate]
+  );
+  return { release, onlyStale: search.evidence === 'stale', setRelease, setOnlyStale };
+}
+
+/** A verdict in words, with its reason on hover. */
+export function VerdictBadge({ verdict }: { verdict: Verdict }) {
+  return (
+    <Badge data-applicability={verdict} color={VERDICTS[verdict].color} variant="light" title={VERDICTS[verdict].meaning}>
+      {VERDICTS[verdict].label}
+    </Badge>
+  );
+}
+
+const RELEASE_WORDS: Record<ReleaseMatch, string> = {
+  'not-selected': 'No release named',
+  exact: 'Exact match of the release',
+  asserted: 'Asserted to hold for the release',
+  other: 'Recorded against another build',
+  unknown: 'Not known to apply to the release'
+};
+
+/**
+ * A compact reading of one behavior's evidence: the verdict; when the checks ran (the age of the evidence, whatever
+ * was uploaded or enriched since); what it ran against; and why. Stale evidence is stated first and prominently, and
+ * the recorded outcome is never described as changed.
+ */
+export function ApplicabilitySummary({ assessment, release }: { assessment: Assessment; release: ReleaseIdentity }) {
+  const now = useNow();
+  const { verdict, facts, reasons } = assessment;
+  if (verdict === 'none' || !facts) {
+    return (
+      <Text component="div" c="dimmed" data-applicability="none">
+        No completed result, so there is no evidence to apply.
+      </Text>
+    );
+  }
+  const named = hasRelease(release);
+  return (
+    <Stack gap="xs" component="section" aria-label="Applicability of this evidence" data-applicability={verdict} data-release={assessment.release}>
+      <Group gap="sm" wrap="wrap">
+        <VerdictBadge verdict={verdict} />
+        <Text span inherit c="dimmed">
+          {VERDICTS[verdict].meaning}
+        </Text>
+      </Group>
+      {assessment.release === 'other' && (
+        <Alert color="orange" role="status">
+          This recording is not proof of the named release. Its recorded outcome is unchanged.
+        </Alert>
+      )}
+      <Group gap="md" wrap="wrap" c="dimmed">
+        <Text span inherit>
+          Checks ran:{' '}
+          <Text span inherit fw={600}>
+            <time dateTime={new Date(facts.executedAtMs).toISOString()} title={exactTime(facts.executedAtMs)}>
+              {exactTime(facts.executedAtMs)} ({ago(facts.executedAtMs, now)})
+            </time>
+          </Text>
+        </Text>
+        <Text span inherit>
+          Build:{' '}
+          <Text span inherit fw={600}>
+            {facts.build ?? 'not recorded'}
+          </Text>
+        </Text>
+        <Text span inherit>
+          Commit:{' '}
+          <Text span inherit fw={600}>
+            {shortSha(facts.sha) ?? 'not recorded'}
+            {facts.provenance === 'modified' ? ' with local changes' : facts.provenance === 'unknown' ? ' (origin not captured)' : ''}
+          </Text>
+        </Text>
+        <Text span inherit>
+          Platform:{' '}
+          <Text span inherit fw={600}>
+            {facts.platform ?? 'not recorded'}
+          </Text>
+        </Text>
+      </Group>
+      {named && (
+        <Text component="div" c="dimmed">
+          Release {[release.build && `build ${release.build}`, release.sha && `commit ${release.sha.slice(0, 7)}`, release.platform].filter(Boolean).join(', ')}:{' '}
+          <Text span inherit fw={600}>
+            {RELEASE_WORDS[assessment.release]}
+          </Text>
+        </Text>
+      )}
+      {assessment.assertion && (
+        <Text component="div" c="dimmed" data-assertion={assessment.assertion.by ? 'policy' : 'unattributed'}>
+          Asserts it still holds for {assessment.assertion.builds.join(', ')}
+          {assessment.assertion.by ? ` (by ${assessment.assertion.by})` : ', with no policy stated'}.
+        </Text>
+      )}
+      {reasons.length > 0 && (
+        <List spacing={4}>
+          {reasons.map((reason) => (
+            <List.Item key={reason}>{reason}</List.Item>
+          ))}
+        </List>
+      )}
+      <Text component="div" c="dimmed">
+        Its age counts from when the checks ran, not from when it was uploaded or annotated.
+        {assessment.others > 0 ? ` Best of ${plural(assessment.others + 1, 'completed result', 'completed results')}.` : ''}
+      </Text>
+    </Stack>
+  );
+}
+
+/**
+ * Names the release evidence is read against (build, commit and platform, each optional) and filters a feature to
+ * its behaviors with stale or unverified evidence. Both live in the address. A branch name or a passing run never
+ * names a release.
+ */
+export function ApplicabilityControls({
+  state,
+  stale,
+  total
+}: {
+  state: ApplicabilityState;
+  /** How many behaviors have stale or unverified evidence. */
+  stale: number;
+  total: number;
+}) {
+  const { release, setRelease, onlyStale, setOnlyStale } = state;
+  return (
+    <Paper component="section" aria-label="Evidence applicability" withBorder p="md" my="md">
+      <Stack gap="sm">
+        <Title order={2}>Evidence applicability</Title>
+        <Text component="div" c="dimmed">
+          Name the release you care about to see whether each recording was made against it. Without one, evidence is read against the current promise only.
+        </Text>
+        <SimpleGrid cols={{ base: 1, sm: 3 }}>
+          <TextInput
+            label="Release build"
+            description="Compared with each result's build label"
+            value={release.build ?? ''}
+            onChange={(event) => setRelease({ ...release, build: event.currentTarget.value })}
+          />
+          <TextInput
+            label="Release commit"
+            description="Compared with the commit the checks ran at"
+            value={release.sha ?? ''}
+            onChange={(event) => setRelease({ ...release, sha: event.currentTarget.value })}
+          />
+          <TextInput
+            label="Release platform"
+            description="For example ios, android or desktop-web"
+            value={release.platform ?? ''}
+            onChange={(event) => setRelease({ ...release, platform: event.currentTarget.value })}
+          />
+        </SimpleGrid>
+        {release.platform && !hasRelease(release) && (
+          <Text role="status" component="div" c="dimmed">
+            A platform alone does not name a release. Add its build or commit.
+          </Text>
+        )}
+        <Group role="group" aria-label="Evidence filter" gap="sm">
+          <Button type="button" aria-pressed={!onlyStale} onClick={() => setOnlyStale(false)} variant={onlyStale ? 'subtle' : 'light'}>
+            All evidence{' '}
+            <Text span inherit>
+              {total}
+            </Text>
+          </Button>
+          <Button type="button" aria-pressed={onlyStale} onClick={() => setOnlyStale(true)} variant={onlyStale ? 'light' : 'subtle'}>
+            Stale or unverified{' '}
+            <Text span inherit>
+              {stale}
+            </Text>
+          </Button>
+        </Group>
+        {onlyStale && stale === 0 && (
+          <Text role="status" component="div" c="dimmed">
+            Every behavior has evidence that applies.
+          </Text>
+        )}
+      </Stack>
+    </Paper>
+  );
+}

package/packages/visualizer/src/evidence/applicability.test.ts

@@ -0,0 +1,131 @@
+import type { LayerHeader, LayerRow } from '@crvouga/atlas/reports/evidence-types';
+import type { CheckSlot } from '@crvouga/atlas/reports/evidence-view';
+import type { EvidenceResult } from '@crvouga/atlas/reports/layer-merge';
+import { expect, test } from 'bun:test';
+
+import { assessBehavior, assessResult, hasRelease, needsAttention } from './applicability';
+import { behaviorOf, type RevisionSource } from './behavior';
+import { featureModel } from './gherkin';
+
+const FEATURE = featureModel('Feature: Lists\n  Scenario: Add\n    When adding tea\n')!;
+const ADD = FEATURE.rules[0]!.scenarios[0]!;
+
+type Extra = { layer?: Partial<LayerHeader>; labels?: Record<string, string>; layerLabels?: Record<string, string> };
+function result(id: string, { layer = {}, labels, layerLabels }: Extra = {}, status: LayerRow['status'] = 'passed'): EvidenceResult {
+  const evidence = (record: Record<string, string> | undefined) =>
+    record ? { attachments: 0, steps: 0, annotations: 0, attempts: 0, links: 0, tags: [], labels: record, roles: [] } : undefined;
+  return {
+    key: id,
+    slot: 's',
+    layer: {
+      id, backend: 'b', producer: 'p', packageDir: null, recordedAtMs: 1_000, sha: null, branch: 'main', environment: 'desktop-web', runUrl: null, parameters: {},
+      recording: null, live: false, counts: { passed: 0, failed: 0, running: 0, 'not-run': 0 }, execution: id,
+      ...(layerLabels ? { evidence: evidence(layerLabels) } : {}),
+      ...layer
+    },
+    parameters: {},
+    warning: null,
+    row: { kind: 'behavior', id: 'x', title: 'Lists: Add', status, specPath: 'specs/a.feature', detail: '', measurements: [], testId: null, variant: {}, durationMs: null, ...(labels ? { evidence: evidence(labels) } : {}) }
+  };
+}
+const revisions = (current: string | null, recorded: Record<string, string> = {}): RevisionSource => ({ current, recorded: (id) => recorded[id] });
+const same = revisions('f1', { l1: 'f1', l2: 'f1', l3: 'f1' });
+const slot = (outcomes: EvidenceResult[], status: CheckSlot['status'] = 'passed'): CheckSlot => ({
+  key: 'k', id: 'k', title: 'Lists: Add', specPath: 'specs/a.feature', status, outcomes, diagnostics: [], latestAtMs: 1, live: false
+});
+
+test('a changed promise makes the only recording stale, whatever the release', () => {
+  const old = assessResult(result('l1'), revisions('f2', { l1: 'f1' }), {});
+  expect(old.verdict).toBe('stale');
+  expect(old.promise).toBe('different');
+  expect(old.reasons[0]).toContain('not proof of the current promise');
+  expect(assessResult(result('l1'), revisions('f1', { l1: 'f1' }), {}).verdict).toBe('applies');
+});
+
+test('a missing revision is unknown, never a match', () => {
+  expect(assessResult(result('l1'), revisions('f1'), {}).verdict).toBe('unknown');
+  expect(assessResult(result('l1'), revisions(null, { l1: 'f1' }), {}).verdict).toBe('unknown');
+});
+
+test('the age of evidence is when the checks ran, not when it was published or enriched', () => {
+  const facts = assessResult(result('l1', { layer: { recordedAtMs: 123_456 } }), same, {}).facts!;
+  expect(facts.executedAtMs).toBe(123_456);
+});
+
+test('a desktop recording says nothing about a phone release', () => {
+  const phone = { build: '90', platform: 'ios' };
+  const got = assessResult(result('l1', { labels: { build: '90' } }), same, phone);
+  expect(got.release).toBe('unknown');
+  expect(got.verdict).toBe('unknown');
+  expect(got.reasons.join(' ')).toContain('desktop-web');
+  // The same build on the release's platform is an exact match.
+  expect(assessResult(result('l1', { layer: { environment: 'ios' }, labels: { build: '90' } }), same, phone).release).toBe('exact');
+  // The platform label overrides the environment name.
+  expect(assessResult(result('l1', { labels: { build: '90', platform: 'ios' } }), same, phone).release).toBe('exact');
+});
+
+test('a mapped release marks evidence for another build, and a branch name or green check never supplies one', () => {
+  const release = { build: '91' };
+  const other = assessResult(result('l1', { labels: { build: '90' } }), same, release);
+  expect(other.release).toBe('other');
+  expect(other.verdict).toBe('stale');
+  expect(assessResult(result('l1', { labels: { build: '91' } }), same, release).verdict).toBe('applies');
+  // Evidence that does not say which build it ran against is unknown, even on the "release" branch with a passing result.
+  const unlabelled = assessResult(result('l1', { layer: { branch: 'release/91' } }), same, release);
+  expect(unlabelled.release).toBe('unknown');
+  expect(unlabelled.verdict).toBe('unknown');
+  // A commit is compared when one is named, abbreviated or not.
+  const sha = 'a'.repeat(40);
+  expect(assessResult(result('l1', { layer: { sha } }), same, { sha: 'aaaaaaa' }).release).toBe('exact');
+  expect(assessResult(result('l1', { layer: { sha } }), same, { sha: 'b'.repeat(40) }).release).toBe('other');
+  expect(assessResult(result('l1'), same, { sha }).release).toBe('unknown');
+});
+
+test('local changes or incomplete provenance can never be an exact build match', () => {
+  const sha = 'a'.repeat(40);
+  const dirty = assessResult(result('l1', { layer: { sha, freshness: 'modified' }, labels: { build: '91' } }), same, { build: '91', sha });
+  expect(dirty.release).toBe('unknown');
+  expect(dirty.reasons.join(' ')).toContain('uncommitted changes');
+  const unknown = assessResult(result('l1', { layer: { sha, freshness: 'unknown' } }), same, { sha });
+  expect(unknown.release).toBe('unknown');
+  expect(unknown.reasons.join(' ')).toContain('not captured');
+});
+
+test('an assertion of compatibility is accepted only with a stated policy and an unchanged promise', () => {
+  const release = { build: '91' };
+  const asserted = (labels: Record<string, string>, revs = same) => assessResult(result('l1', { labels: { build: '90', ...labels } }), revs, release);
+  const accepted = asserted({ 'applies-to': '91, 92', 'applies-to-by': 'release-policy-7' });
+  expect(accepted.release).toBe('asserted');
+  expect(accepted.verdict).toBe('applies');
+  expect(accepted.assertion).toEqual({ builds: ['91', '92'], by: 'release-policy-7' });
+  // No policy: not accepted, and not described as a match either.
+  expect(asserted({ 'applies-to': '91' }).release).toBe('unknown');
+  // A different promise wins over any assertion.
+  expect(asserted({ 'applies-to': '91', 'applies-to-by': 'p' }, revisions('f2', { l1: 'f1' })).verdict).toBe('stale');
+  // An assertion about other builds does not cover this one.
+  expect(asserted({ 'applies-to': '95', 'applies-to-by': 'p' }).release).toBe('other');
+});
+
+test('a platform alone names no release', () => {
+  expect(hasRelease({ platform: 'ios' })).toBe(false);
+  expect(assessResult(result('l1'), same, { platform: 'ios' }).release).toBe('not-selected');
+});
+
+test('a behavior is read by its best completed result and its status is untouched', () => {
+  const failing = result('l1', { labels: { build: '91' } }, 'failed');
+  const old = result('l2', { layer: { recordedAtMs: 5 }, labels: { build: '90' } });
+  const behavior = behaviorOf(ADD, slot([old, failing], 'failed'), null, same, 'k');
+  const got = assessBehavior(behavior, same, { build: '91' });
+  expect(got.verdict).toBe('applies');
+  expect(got.others).toBe(1);
+  expect(got.result).toBe(failing);
+  expect(behavior.state).toBe('failed');
+  // No completed result: no evidence, which is not a failure and is found with the stale ones.
+  const none = assessBehavior(behaviorOf(ADD, null, null, same, 'k'), same, {});
+  expect(none.verdict).toBe('none');
+  expect(needsAttention(none)).toBe(true);
+  expect(needsAttention(got)).toBe(false);
+  // A running result is not evidence.
+  const running = assessBehavior(behaviorOf(ADD, slot([result('l1', {}, 'running')]), null, same, 'k'), same, {});
+  expect(running.verdict).toBe('none');
+});

package/packages/visualizer/src/evidence/applicability.ts

@@ -0,0 +1,241 @@
+/**
+ * @module Evidence applicability
+ *
+ * Whether recorded evidence applies to a behavior as it is written now and, when a release is named, to that
+ * release. Four facts stay apart: the promise's revision (the spec now) against the revision the evidence recorded,
+ * when the checks ran (never when they were published or enriched), what the evidence ran against (build, commit,
+ * platform, and whether the checkout was clean), and the release a reader named. Nothing here decides an outcome:
+ * statuses and winners come from the combined report, and a verdict is a reading of them that never turns a pass
+ * into a failure. What cannot be compared is `unknown`, never `applies`. A branch name, a green check or a run's
+ * recency never supply deployment state.
+ *
+ * Producers state what they know with the open vocabulary of `labels` (see docs/extending.md): `build` (the build
+ * the app under test was), `platform` (the client family; the environment when absent), `applies-to` (a comma
+ * separated list of builds or commits the producer asserts the evidence is still good for) and `applies-to-by`
+ * (the policy, person or tool that makes the assertion). An assertion without `applies-to-by` is not accepted.
+ */
+import type { LayerHeader } from '@crvouga/atlas/reports/evidence-types';
+import type { EvidenceResult } from '@crvouga/atlas/reports/layer-merge';
+
+import { compareRevisions, type Behavior, type Revision, type RevisionSource } from './behavior';
+
+/** The release a reader names: the build and/or commit that was deployed, on a platform. Every part is optional. */
+export type ReleaseIdentity = {
+  /** The deployed build (`4821`, `2.4.1`), compared with the `build` label of the evidence. */
+  readonly build?: string;
+  /** The deployed commit, full or abbreviated, compared with the layer's commit. */
+  readonly sha?: string;
+  /** The platform of the release (`ios`, `android`, `desktop-web`), compared with the evidence's `platform` label or environment. */
+  readonly platform?: string;
+};
+
+/** Whether a release is named: a build or a commit is needed to compare against, a platform alone selects nothing. */
+export function hasRelease(release: ReleaseIdentity): boolean {
+  return Boolean(release.build?.trim() || release.sha?.trim());
+}
+
+/**
+ * Where evidence stands against the release.
+ * `not-selected`: no release was named. `exact`: the build and/or commit match and the checkout was clean.
+ * `asserted`: a different build, with an explicit stated policy that the evidence still holds.
+ * `other`: a known different build or commit. `unknown`: it cannot be compared (another platform, no build recorded,
+ * a modified checkout, an assertion with no policy).
+ */
+export type ReleaseMatch = 'not-selected' | 'exact' | 'asserted' | 'other' | 'unknown';
+
+/** What a reader should take from the evidence: it applies, it does not (stale), it cannot be told, or there is none. */
+export type Verdict = 'applies' | 'stale' | 'unknown' | 'none';
+
+/** What each verdict is called, and why. */
+export const VERDICTS: Readonly<Record<Verdict, { readonly label: string; readonly meaning: string; readonly color: string }>> = {
+  applies: { label: 'Applies', meaning: 'The evidence was recorded against the current promise and, when a release is named, against that release.', color: 'green' },
+  stale: { label: 'Stale', meaning: 'The evidence is of an earlier promise or of another build. It is not proof of what is shown now. The recorded outcome is unchanged.', color: 'orange' },
+  unknown: { label: 'Applicability unknown', meaning: 'The evidence cannot be tied to the current promise or the named release. That is not a failure.', color: 'gray' },
+  none: { label: 'No evidence', meaning: 'Nothing was recorded for this behavior.', color: 'gray' }
+};
+
+/** What the evidence of one result says about what it ran against. Absent facts are null: unknown, never assumed. */
+export type EvidenceFacts = {
+  /** When the checks ran, epoch milliseconds. The age of evidence counts from here, not from publication or enrichment. */
+  readonly executedAtMs: number;
+  readonly build: string | null;
+  readonly sha: string | null;
+  /** The `platform` label, else the layer's environment. */
+  readonly platform: string | null;
+  readonly environment: string | null;
+  /** `modified` or `unknown` when the checkout was not a clean commit, else null. */
+  readonly provenance: 'modified' | 'unknown' | null;
+};
+
+/** An assertion by the producer that evidence still holds for other builds, and who stands behind it. */
+export type Assertion = {
+  readonly builds: readonly string[];
+  /** The stated policy or author; null when none was stated (the assertion is then not accepted). */
+  readonly by: string | null;
+};
+
+/** The reading of one result's evidence against the promise and the named release. */
+export type Assessment = {
+  readonly verdict: Verdict;
+  readonly promise: Revision['match'];
+  readonly release: ReleaseMatch;
+  readonly facts: EvidenceFacts | null;
+  readonly assertion: Assertion | null;
+  /** Sentences saying why, in the order a reader needs them. Empty when there is nothing to add. */
+  readonly reasons: readonly string[];
+  /** The result this reading is of, or null when there is none. */
+  readonly result: EvidenceResult | null;
+  /** How many other completed results were read and set aside for this one. */
+  readonly others: number;
+};
+
+const norm = (value: string | null | undefined): string | null => {
+  const trimmed = value?.trim().toLowerCase();
+  return trimmed ? trimmed : null;
+};
+
+/** Whether two commits name the same one, allowing either to be abbreviated (at least seven characters). */
+function sameCommit(a: string, b: string): boolean {
+  const [left, right] = [a.toLowerCase(), b.toLowerCase()];
+  const short = left.length <= right.length ? left : right;
+  const long = left.length <= right.length ? right : left;
+  return short.length >= 7 && long.startsWith(short);
+}
+
+/** The labels that apply to a result: the layer's, then the check's own. */
+function labelsOf(result: EvidenceResult): Readonly<Record<string, string>> {
+  return { ...(result.layer.evidence?.labels ?? {}), ...(result.row.evidence?.labels ?? {}) };
+}
+
+/** What a result's layer and labels say it ran against. */
+export function evidenceFacts(result: EvidenceResult): EvidenceFacts {
+  const labels = labelsOf(result);
+  const layer: LayerHeader = result.layer;
+  return {
+    executedAtMs: layer.recordedAtMs,
+    build: labels.build?.trim() || null,
+    sha: layer.sha,
+    platform: labels.platform?.trim() || layer.environment,
+    environment: layer.environment,
+    provenance: layer.freshness ?? null
+  };
+}
+
+/** The assertion a result's labels make, or null when it makes none. */
+export function assertionOf(result: EvidenceResult): Assertion | null {
+  const labels = labelsOf(result);
+  const builds = (labels['applies-to'] ?? '')
+    .split(',')
+    .map((each) => each.trim())
+    .filter(Boolean);
+  return builds.length ? { builds, by: labels['applies-to-by']?.trim() || null } : null;
+}
+
+const RANK: Readonly<Record<Verdict, number>> = { applies: 0, unknown: 1, stale: 2, none: 3 };
+
+/** How one result's evidence stands against the release. Never reads a branch or a status. */
+function matchRelease(facts: EvidenceFacts, release: ReleaseIdentity, promise: Revision['match'], assertion: Assertion | null): { match: ReleaseMatch; reasons: string[] } {
+  if (!hasRelease(release)) return { match: 'not-selected', reasons: [] };
+  const wanted = { build: release.build?.trim() || null, sha: release.sha?.trim() || null, platform: norm(release.platform) };
+  const reasons: string[] = [];
+  const platform = norm(facts.platform);
+  if (wanted.platform && platform !== wanted.platform) {
+    reasons.push(
+      platform
+        ? `Recorded on ${facts.platform}, the release is on ${release.platform}, so it is not known to apply.`
+        : `The platform it ran on was not recorded, so it is not known to apply to ${release.platform}.`
+    );
+    return { match: 'unknown', reasons };
+  }
+  // Each part of the release is compared where the evidence has an answer; a part it cannot answer is unknown.
+  const parts: ('same' | 'different' | 'unknown')[] = [];
+  if (wanted.build) {
+    if (!facts.build) {
+      parts.push('unknown');
+      reasons.push(`The build it ran against was not recorded, so it cannot be compared with build ${wanted.build}.`);
+    } else if (norm(facts.build) === norm(wanted.build)) parts.push('same');
+    else {
+      parts.push('different');
+      reasons.push(`Recorded against build ${facts.build}, not build ${wanted.build}.`);
+    }
+  }
+  if (wanted.sha) {
+    if (!facts.sha) {
+      parts.push('unknown');
+      reasons.push(`The commit it ran against was not recorded, so it cannot be compared with ${wanted.sha.slice(0, 7)}.`);
+    } else if (sameCommit(facts.sha, wanted.sha)) parts.push('same');
+    else {
+      parts.push('different');
+      reasons.push(`Recorded at commit ${facts.sha.slice(0, 7)}, not ${wanted.sha.slice(0, 7)}.`);
+    }
+  }
+  if (parts.includes('different')) {
+    const named = [wanted.build, wanted.sha].filter((each): each is string => each !== null);
+    const covered = assertion?.builds.some((each) => named.some((name) => norm(each) === norm(name) || sameCommit(each, name))) ?? false;
+    if (covered && promise === 'same') {
+      if (assertion!.by) {
+        return { match: 'asserted', reasons: [`${assertion!.by} asserts this evidence still holds for the release. That is a stated policy, not a match of builds.`] };
+      }
+      reasons.push('It is asserted to hold for this release, but no policy or author stands behind the assertion, so it is not accepted.');
+      return { match: 'unknown', reasons };
+    }
+    return { match: 'other', reasons };
+  }
+  if (parts.includes('unknown')) return { match: 'unknown', reasons };
+  if (facts.provenance) {
+    reasons.push(
+      facts.provenance === 'modified'
+        ? 'It was recorded from a checkout with uncommitted changes, so it cannot be an exact match of the release.'
+        : 'Where it was recorded from was not captured, so it cannot be an exact match of the release.'
+    );
+    return { match: 'unknown', reasons };
+  }
+  return { match: 'exact', reasons };
+}
+
+/** One result against the promise and the release. */
+export function assessResult(result: EvidenceResult, revisions: RevisionSource, release: ReleaseIdentity): Assessment {
+  const facts = evidenceFacts(result);
+  const revision = compareRevisions(revisions.current, revisions.recorded(result.layer.id));
+  const assertion = assertionOf(result);
+  const { match, reasons } = matchRelease(facts, release, revision.match, assertion);
+  const promiseReason =
+    revision.match === 'different'
+      ? 'The promise changed after this evidence was recorded. It is not proof of the current promise.'
+      : revision.match === 'unknown'
+        ? 'The revision of the promise it was recorded against was not captured, so it is not tied to the current promise.'
+        : null;
+  const stale = revision.match === 'different' || match === 'other';
+  const unknown = revision.match === 'unknown' || match === 'unknown';
+  return {
+    verdict: stale ? 'stale' : unknown ? 'unknown' : 'applies',
+    promise: revision.match,
+    release: match,
+    facts,
+    assertion,
+    reasons: [...(promiseReason ? [promiseReason] : []), ...reasons],
+    result,
+    others: 0
+  };
+}
+
+/**
+ * The reading of a behavior's evidence: every completed result is read and the one that best applies is kept
+ * (applies, then unknown, then stale; the newest execution among equals), so a recording on the release's platform is
+ * not hidden by a newer one elsewhere. A behavior with no completed result has `none`. The behavior's coverage state
+ * and its results' statuses are unchanged by this.
+ */
+export function assessBehavior(behavior: Behavior, revisions: RevisionSource, release: ReleaseIdentity): Assessment {
+  const completed = (behavior.slot?.outcomes ?? []).filter((result) => result.row.status === 'passed' || result.row.status === 'failed');
+  if (completed.length === 0) {
+    return { verdict: 'none', promise: 'unknown', release: hasRelease(release) ? 'unknown' : 'not-selected', facts: null, assertion: null, reasons: [], result: null, others: 0 };
+  }
+  const readings = completed.map((result) => assessResult(result, revisions, release));
+  readings.sort((a, b) => RANK[a.verdict] - RANK[b.verdict] || b.facts!.executedAtMs - a.facts!.executedAtMs);
+  return { ...readings[0]!, others: readings.length - 1 };
+}
+
+/** Whether a behavior belongs under "stale or unverified": anything but evidence that applies. */
+export function needsAttention(assessment: Assessment): boolean {
+  return assessment.verdict !== 'applies';
+}

package/packages/visualizer/src/evidence/artifact-tags.tsx

@@ -60,7 +60,8 @@ export function everyAttachment(holder: EvidenceHolder): Attachment[] {
   return out;
 }
 
-async function readProblem(response: Response): Promise<string> {
+/** The reason a server gave for refusing a change (its problem document's `detail`), or a sentence naming the status. */
+export async function readProblem(response: Response): Promise<string> {
   try {
     const body = (await response.json()) as { detail?: string; error?: string };
     return body.detail ?? body.error ?? `The server refused the change (${response.status}).`;