@startsimpli/ui 0.4.134 → 0.4.136

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.134",
+  "version": "0.4.136",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -20,6 +20,7 @@
     "./blog": "./src/components/blog/index.ts",
     "./blog/resolve": "./src/components/blog/resolveArticle.ts",
     "./activity": "./src/components/activity/index.ts",
+    "./history": "./src/components/history/index.ts",
     "./collection": "./src/components/collection/index.ts",
     "./scope": "./src/components/scope/index.ts",
     "./facet-tree": "./src/components/facet-tree/index.ts",
@@ -47,8 +48,8 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/auth": "^0.4.38",
     "@startsimpli/api": "^0.5.66",
+    "@startsimpli/auth": "^0.4.38",
     "@startsimpli/i18n": "^0.1.3"
   },
   "peerDependenciesMeta": {
@@ -123,8 +124,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/i18n": "0.1.3",
-    "@startsimpli/realtime": "0.0.2"
+    "@startsimpli/realtime": "0.0.2",
+    "@startsimpli/i18n": "0.1.3"
   },
   "keywords": [
     "ui",

package/src/components/ActivityTimeline.tsx

@@ -17,7 +17,7 @@ import { formatDistanceToNow } from 'date-fns';
 import { Clock, User } from 'lucide-react';
 import { EmptyState } from './states';
 import { ActorIdentity, actorInitials, actorLabel } from './ActorIdentity';
-import type { ActorIdentityValue } from './ActorIdentity';
+import type { ActorIdentityValue, ActorKind, ActorKindSource } from './ActorIdentity';
 
 /** Severity of an entry, for the marker. Presentation only — never a gate. */
 export type ActivityTone = 'ok' | 'warn' | 'error' | 'muted';
@@ -37,6 +37,12 @@ export interface ActivityTimelineItem {
   // --- event-stream shape -------------------------------------------------
   /** Identity of the person behind the event (preferred over `createdBy`). */
   actor?: ActivityTimelineActor;
+  /** Whether a person or a MACHINE did it, where the stream records it
+   *  (bd startsim-g4rwo). Forwarded straight to `ActorIdentity`, so a stream
+   *  that does not record it renders exactly as before — and so a stream that
+   *  does cannot show a robot's write as a colleague's. */
+  actorKind?: ActorKind;
+  actorKindSource?: ActorKindSource;
   /** Colours the marker; `activityColors[type]` still wins when supplied. */
   tone?: ActivityTone;
   /** Muted inline qualifier after the title, e.g. "from provisioning". */
@@ -192,9 +198,16 @@ function TimelineEntry({
               <p className="mt-1 text-sm text-muted-foreground">{activity.description}</p>
             )}
             {activity.detail && (
-              <p className={`mt-1 break-words text-xs ${TONE_TEXT[activity.detailTone ?? 'muted']}`}>
+              // A DIV, NOT A P. `detail` is typed ReactNode and the record
+              // history panel passes a field LIST into it — and a <ul> or a
+              // <div> inside a <p> is invalid HTML, which React resolves by
+              // reparenting during hydration. That produces a hydration
+              // mismatch on every row, and neither tsc nor jsdom reports it:
+              // only a real browser does (bd startsim-g4rwo). The classes are
+              // unchanged, so every existing caller renders identically.
+              <div className={`mt-1 break-words text-xs ${TONE_TEXT[activity.detailTone ?? 'muted']}`}>
                 {activity.detail}
-              </p>
+              </div>
             )}
           </div>
           <div className="ml-4 whitespace-nowrap text-xs text-muted-foreground">
@@ -203,7 +216,12 @@ function TimelineEntry({
         </div>
 
         <div className="flex flex-wrap items-center gap-x-4 gap-y-1 text-sm text-muted-foreground">
-          <ActorIdentity actor={activity.actor} showInitials={!markerIsAvatar} />
+          <ActorIdentity
+            actor={activity.actor}
+            showInitials={!markerIsAvatar}
+            kind={activity.actorKind}
+            kindSource={activity.actorKindSource}
+          />
 
           {!who && activity.createdBy && (
             <span className="flex items-center gap-1">

package/src/components/ActorIdentity.tsx

@@ -16,7 +16,33 @@
  * the address echoed back. Every surface that attributes something to a person
  * renders this component rather than its own arrangement of the same two
  * fields (rule #9).
+ *
+ * AND SINCE bd startsim-g4rwo, ONE WAY TO SAY "A MACHINE DID THIS" — the same
+ * component, because the question a reader asks is the same question and the
+ * answer has to be comparable. Pass `kind`/`kindSource`; see {@link kindMarker}
+ * for which states are decorated and the inversion that decides it. Both props
+ * are optional and omitting them renders exactly what this component rendered
+ * before they existed, which is what lets the surfaces already using it stay
+ * untouched.
+ */
+import { Bot } from 'lucide-react';
+
+/**
+ * WHAT the actor is — and the third value is NOT a defect (bd startsim-g4rwo,
+ * claim bd startsim-jkkn7.2).
+ *
+ * `unknown` means CENTRAL DID NOT SAY. The claim is minted at LOGIN and
+ * inherited across refreshes, so for up to the 14-day refresh expiry after
+ * rollout a GENUINE HUMAN EDIT carries no kind at all. Note precisely what is
+ * missing: the KIND, never the actor — the name and email are still there — so
+ * an unknown row can still say who, and only has to stay quiet about what.
  */
+export type ActorKind = 'person' | 'machine' | 'unknown';
+
+/** Whether {@link ActorKind} came from a verified claim or from an inference
+ *  ladder over naming conventions. `inferred` is a GUESS, and a surface that
+ *  says so is what makes a later cleanup possible instead of a second guess. */
+export type ActorKindSource = 'claim' | 'inferred';
 
 export interface ActorIdentityValue {
   id?: string;
@@ -54,33 +80,147 @@ export function actorHandle(actor?: ActorIdentityValue): string {
   return email && email !== actorLabel(actor) ? email : '';
 }
 
+/**
+ * Whether this kind earns a visible marker, and what it should say.
+ *
+ * ── THE RULE, AND IT IS AN INVERSION OF THE OBVIOUS DESIGN ──────────────────
+ *
+ * The obvious design is three badges, one per state. It FAILS the requirement
+ * even though it renders all three states, because during the rollout window
+ * `unknown` is the COMMON case for real human edits — so a badge on every
+ * unknown row makes the whole panel look broken for two weeks on every tenant,
+ * and a reader who has been trained that the badges mean trouble stops reading
+ * the one badge that matters.
+ *
+ * So ABSENCE OF A MARKER IS THE CORRECT RENDERING FOR THE CALM CASES, and only
+ * the cases that genuinely carry information are decorated:
+ *
+ * - `machine`          → ALWAYS marked, with an icon, and visually distinct
+ *                        from any person. This is the single most valuable
+ *                        thing in the epic: the repeated live failure was a
+ *                        machine overwriting a human, and 41 machine-written
+ *                        notes that could not be cleaned up afterwards
+ *                        "precisely because the data cannot say retrospectively
+ *                        which were human".
+ * - `person`/`claim`   → NOTHING. A colleague edited the record; that is the
+ *                        unremarkable default and decorating it adds noise to
+ *                        the good case.
+ * - `person`/`inferred`→ marked, lightly, because the tenant GUESSED and the
+ *                        guess should be visible to whoever might act on it.
+ * - `unknown`          → NOTHING on the row. The kind is unrecorded, which is
+ *                        not a fact about this edit worth shouting once per
+ *                        row; `RecordHistoryPanel` says it ONCE for the whole
+ *                        panel instead, and only when some loaded row is
+ *                        actually unknown.
+ *
+ * The truth is never *lost* in the quiet cases — it goes into the element's
+ * accessible title, so hover and assistive tech still report it.
+ */
+function kindMarker(
+  kind: ActorKind | undefined,
+  source: ActorKindSource | undefined,
+): { label: string; icon: 'bot' | null; inferred: boolean } | null {
+  if (kind === 'machine') {
+    return { label: 'machine', icon: 'bot', inferred: source === 'inferred' };
+  }
+  if (kind === 'person' && source === 'inferred') {
+    return { label: 'person, inferred', icon: null, inferred: true };
+  }
+  return null;
+}
+
+/** The full truth about the kind, for `title`/screen readers — including in the
+ *  cases that render no marker, so "quiet" never means "undiscoverable". */
+export function actorKindTitle(
+  kind: ActorKind | undefined,
+  source: ActorKindSource | undefined,
+): string {
+  if (kind === 'machine') {
+    return source === 'claim'
+      ? 'A machine made this change (declared by the sign-in service).'
+      : 'A machine made this change (inferred from the account, not declared).';
+  }
+  if (kind === 'person') {
+    return source === 'claim'
+      ? 'A person made this change (declared by the sign-in service).'
+      : 'A person made this change (inferred from the account, not declared).';
+  }
+  return 'Whether a person or a machine made this change was not recorded.';
+}
+
 export interface ActorIdentityProps {
   actor?: ActorIdentityValue;
   /** Show the initials avatar. Off for a compact one-line attribution, or where
    *  the surrounding row already paints the same initials. */
   showInitials?: boolean;
+  /** Person, machine, or not recorded. Omitted on every surface that predates
+   *  the revision trail, which is why it is optional and why omitting it
+   *  renders byte-identically to before. */
+  kind?: ActorKind;
+  /** Whether {@link kind} was claimed or guessed. */
+  kindSource?: ActorKindSource;
   className?: string;
   initialsClassName?: string;
   handleClassName?: string;
+  kindClassName?: string;
 }
 
 export function ActorIdentity({
   actor,
   showInitials = true,
+  kind,
+  kindSource,
   className = 'flex flex-wrap items-center gap-x-1.5',
   initialsClassName = 'flex h-5 w-5 items-center justify-center rounded-full bg-muted text-[10px] font-medium text-muted-foreground',
   handleClassName = 'text-xs text-muted-foreground/80',
+  kindClassName,
 }: ActorIdentityProps) {
   const label = actorLabel(actor);
-  if (!label) return null;
-  const initials = showInitials ? actorInitials(actor) : '';
+  const marker = kindMarker(kind, kindSource);
+  // An empty label used to be the signal to render nothing at all, rather than
+  // a dangling "by" — and it still is, UNLESS there is a kind worth marking. A
+  // service token can carry no email whatsoever, and dropping that row's actor
+  // entirely would hide the one fact the actor axis exists to record: that a
+  // machine, not a colleague, wrote here.
+  if (!label && !marker) return null;
+  const initials = showInitials && label ? actorInitials(actor) : '';
   const handle = actorHandle(actor);
 
   return (
-    <span data-testid="actor-identity" className={className}>
+    <span
+      data-testid="actor-identity"
+      data-actor-kind={kind ?? undefined}
+      data-actor-kind-source={kindSource ?? undefined}
+      className={className}
+    >
       {initials && <span className={initialsClassName}>{initials}</span>}
-      <span>{label}</span>
+      {label && <span>{label}</span>}
       {handle && <span className={handleClassName}>{handle}</span>}
+      {marker && (
+        <span
+          data-testid="actor-kind"
+          // NOT a warning colour. This is a statement of fact about who typed,
+          // and the dark-tenant palette reserves red for failure; a machine
+          // edit is routine and must not read as an incident. The icon, not a
+          // colour, is what makes it scannable — and `inferred` is drawn with a
+          // DASHED border and no fill, so "we guessed" is lighter on the page
+          // than "we were told" without needing a second colour.
+          className={
+            kindClassName ??
+            [
+              'inline-flex items-center gap-1 rounded border px-1.5 py-px',
+              'text-[10px] font-medium uppercase tracking-wide',
+              marker.inferred
+                ? 'border-dashed border-border text-muted-foreground'
+                : 'border-border bg-secondary text-secondary-foreground',
+            ].join(' ')
+          }
+          title={actorKindTitle(kind, kindSource)}
+        >
+          {marker.icon === 'bot' && <Bot className="h-3 w-3" aria-hidden="true" />}
+          {marker.label}
+        </span>
+      )}
     </span>
   );
 }

package/src/components/collection/InlineReviewActions.tsx

@@ -5,13 +5,16 @@
  * startsim-768w.18.15). Renders the (up to) three decisions from the schema as
  * compact icon buttons ✕ reject · ✓ good · ✎ edit; a click writes status AND
  * team_verdict together (the coherent pair, same as ReviewDrawer) IN PLACE —
- * optimistic, no drawer. The current verdict shows as the active button.
+ * optimistic, no drawer.
  *
  * The ✎ "edit / needs work" decision opens a small popover with a note box so the
  * reviewer says HOW it should change — saved to the note attr alongside the
  * status+verdict move. Meant to live in a table's trailing "Actions" column; it
  * stops click propagation so acting never triggers the row's drawer-open.
  *
+ * THE ACTIVE BUTTON REPORTS STATUS, NOT THE VERDICT (bd startsim-m7fdm.12) — see
+ * `activeDecisionKey` in review.ts for why, and for what that costs.
+ *
  * Generic + client-injected: pass a CollectionClient + the record; defaults match
  * the OGMC content schema but everything routes through resolveReviewConfig.
  */
@@ -26,6 +29,7 @@ import { cn } from '../../lib/utils';
 import type { CollectionClient, EntityRecord, EntityTypeDef } from './types';
 import { writeData } from './data';
 import {
+  activeDecisionKey,
   applyDecisionToData,
   fieldStr,
   resolveReviewConfig,
@@ -69,26 +73,37 @@ export function InlineReviewActions({ client, type, record, config, onSaved }: I
     () => [...reviewDecisions(cfg)].sort((a, b) => ORDER.indexOf(a.key) - ORDER.indexOf(b.key)),
     [cfg],
   );
-  // Which decision the record currently reflects — by verdict when the type has
-  // one (topics), else by status (news: acceptable→approve, rejected→reject). The
-  // matching button shows active. Optimistically updated on click.
-  const initialKey = useMemo(() => {
-    const v = fieldStr(record.data, cfg.verdictAttr);
-    const s = fieldStr(record.data, cfg.statusName);
-    return (
-      decisions.find((d) => (d.verdict ? d.verdict === v : d.status ? d.status === s : false))?.key ??
-      null
-    );
-  }, [record.data, cfg, decisions]);
-  const [appliedKey, setAppliedKey] = useState<string | null>(initialKey);
+  /**
+   * Which decision the record's STATE reflects — the button that renders active.
+   * Resolved by the shared `activeDecisionKey`, which answers off STATUS wherever
+   * the type has a status pipeline, so the AI's `team_verdict` can no longer
+   * render as a human's approval (bd startsim-m7fdm.12).
+   */
+  const storedKey = useMemo(
+    () => activeDecisionKey(record.data, cfg, decisions),
+    [record.data, cfg, decisions],
+  );
+  /**
+   * Optimistic override, remembered against the exact record snapshot it was made
+   * on, so it DROPS the moment a refetch hands this row a new one and the buttons
+   * go back to reporting stored state.
+   *
+   * It used to be `useState(initialKey)` — an initialiser that runs once per
+   * mounted component. A table cell's component instance outlives the record in
+   * it (a refetch, a re-sort, a page change hands the same cell a different row),
+   * and the old state then showed the PREVIOUS row's decision with nothing to
+   * correct it. Deriving from the record and overlaying the click is what makes
+   * the active state follow the data it claims to describe.
+   */
+  const [override, setOverride] = useState<{ on: unknown; key: string } | null>(null);
+  const appliedKey = override && override.on === record.data ? override.key : storedKey;
   const [busy, setBusy] = useState<string | null>(null);
   const [noteOpen, setNoteOpen] = useState(false);
   const [note, setNote] = useState('');
 
   /** Apply a decision (status + verdict), optionally attaching a note. Optimistic. */
   async function apply(d: ReviewDecision, noteText?: string) {
-    const prev = appliedKey;
-    setAppliedKey(d.key); // optimistic
+    setOverride({ on: record.data, key: d.key }); // optimistic
     setBusy(d.key);
     try {
       // Declared names re-key the whole outgoing blob, so a decision here cannot
@@ -99,7 +114,7 @@ export function InlineReviewActions({ client, type, record, config, onSaved }: I
       onSaved?.();
       return true;
     } catch (err) {
-      setAppliedKey(prev); // roll back
+      setOverride(null); // roll back to what is stored
       notify.error(err instanceof Error ? err.message : 'Could not save.');
       return false;
     } finally {

package/src/components/collection/ReviewDrawer.tsx

@@ -45,6 +45,7 @@ import type { CollectionClient, EntityRecord, EntityTypeDef } from './types';
 import { declaredBlob, readData, writeData } from './data';
 import { parseSources } from './drafts';
 import {
+  activeDecisionKey,
   resolveReviewConfig,
   reviewDecisions,
   shouldIgnoreShortcut,
@@ -125,7 +126,19 @@ function ReviewDrawerInner({
   const next = index >= 0 && index + 1 < records.length ? records[index + 1] : null;
 
   const status = fieldStr(data, cfg.statusName);
-  const verdict = fieldStr(data, cfg.verdictAttr);
+  /**
+   * Which decision the record's STATE reflects — the ringed button in the sticky
+   * bar. Off STATUS, not the verdict, for the reason `activeDecisionKey` sets out
+   * (bd startsim-m7fdm.12): the drawer's ring had the same defect as the table's
+   * tick, so a reviewer opening one of the twenty topics the re-rank agent had
+   * marked `good` saw Approve ringed over a record still sitting at `suggested`.
+   *
+   * Fed the drawer's own optimistic `data`, so a decision rings instantly; and
+   * because it reads status, the manual state override below (`overrideStatus`
+   * writes status alone, no verdict) now rings the decision it amounts to
+   * instead of ringing nothing.
+   */
+  const activeKey = useMemo(() => activeDecisionKey(data, cfg, decisions), [data, cfg, decisions]);
   const title = fieldStr(data, cfg.titleAttr) || record.name || `#${record.id}`;
   const summary = fieldStr(data, cfg.summaryAttr);
   const rank = fieldStr(data, cfg.rankAttr);
@@ -339,7 +352,7 @@ function ReviewDrawerInner({
                     <DecisionButton
                       key={d.key}
                       decision={d}
-                      active={verdict !== '' && d.verdict === verdict}
+                      active={d.key === activeKey}
                       busy={busy === `decision:${d.key}`}
                       onClick={() => applyDecision(d)}
                     />

package/src/components/collection/__tests__/review.test.ts

@@ -1,4 +1,6 @@
 import {
+  activeDecisionKey,
+  isTerminalStatus,
   deriveReviewTransitions,
   resolveReviewConfig,
   reviewDecisions,
@@ -10,6 +12,7 @@ import {
   fieldStr,
   DEFAULT_VERDICTS,
 } from '../review';
+import type { ReviewDecision } from '../review';
 import type { AttributeDef, EntityTypeDef } from '../types';
 
 function enumAttr(name: string, choices: string[]): AttributeDef {
@@ -343,3 +346,149 @@ describe('holdAfter — decisions that stay on the record', () => {
     expect(resolveReviewConfig(type, { holdAfter: ['approve'] }).holdAfter).toEqual(['approve']);
   });
 });
+
+/**
+ * The green tick must report the HUMAN's decision, not the AI's verdict (bd
+ * startsim-m7fdm.12).
+ *
+ * The cases are the live OGMC distribution, measured on 171 topics: suggested/-
+ * 100, written/good 31, **suggested/good 20**, rejected/bad 16, written/bad 2,
+ * written/- 1, suggested/edit 1, and ZERO at `ready`. The twenty at
+ * suggested/good are the defect — the n8n re-rank agent wrote `team_verdict`
+ * without touching status, and the table drew a darkened green tick over every
+ * one of them.
+ */
+describe('activeDecisionKey', () => {
+  const topicType = type([
+    enumAttr('status', ['suggested', 'ready', 'rejected', 'written']),
+    textAttr('team_verdict'),
+    textAttr('team_notes'),
+  ]);
+  const topicCfg = resolveReviewConfig(topicType);
+  const topicDecisions = reviewDecisions(topicCfg);
+  const key = (data: Record<string, unknown>) => activeDecisionKey(data, topicCfg, topicDecisions);
+
+  it('a machine-set verdict alone lights NOTHING — the defect, 20 live rows', () => {
+    expect(key({ status: 'suggested', team_verdict: 'good' })).toBeNull();
+  });
+
+  it('and nothing lights on the amber one either — the agent writes `edit` too', () => {
+    // The same lie one button over: "RESOLVED from edit -> good" is the agent's
+    // own prose. Needs work writes status BACK to the entry stage, so it leaves
+    // no trace status can tell apart from untouched.
+    expect(key({ status: 'suggested', team_verdict: 'edit' })).toBeNull();
+  });
+
+  it('an untouched topic lights nothing — 100 live rows, unchanged', () => {
+    expect(key({ status: 'suggested' })).toBeNull();
+  });
+
+  it('approved lights Approve — the state the fix makes reachable', () => {
+    expect(key({ status: 'ready' })).toBe('approve');
+    // and it does NOT depend on the verdict agreeing, or being present at all.
+    expect(key({ status: 'ready', team_verdict: 'bad' })).toBe('approve');
+  });
+
+  it('rejected lights Reject — 16 live rows, unchanged', () => {
+    expect(key({ status: 'rejected', team_verdict: 'bad' })).toBe('reject');
+  });
+
+  it('written still lights Approve — forward past approval, 34 live rows', () => {
+    // A written topic was approved; rendering it undecided would be the same lie
+    // pointing the other way, and with the State column off by default the tick
+    // is the only state a row shows.
+    expect(key({ status: 'written', team_verdict: 'good' })).toBe('approve');
+    expect(key({ status: 'written' })).toBe('approve');
+  });
+
+  it('written/bad lights GREEN where it used to light red — 2 live rows', () => {
+    // A DELIBERATE, surprising-direction change. The agent re-marked two
+    // already-written topics `bad` ("RE-MARKED (was unset, and it was
+    // WRITTEN)"); status says a human approved them and the writer wrote them,
+    // and status is the fact the tick reports.
+    expect(key({ status: 'written', team_verdict: 'bad' })).toBe('approve');
+  });
+
+  it('is independent of the order the caller holds its decisions in', () => {
+    const shuffled = [...topicDecisions].reverse();
+    for (const data of [
+      { status: 'suggested', team_verdict: 'good' },
+      { status: 'ready' },
+      { status: 'rejected' },
+      { status: 'written' },
+    ]) {
+      expect(activeDecisionKey(data, topicCfg, shuffled)).toBe(key(data));
+    }
+  });
+
+  it('ignores an undeclared status rather than guessing', () => {
+    expect(key({ status: 'queued_for_mars' })).toBeNull();
+    expect(key({})).toBeNull();
+  });
+
+  /**
+   * News Item is the path this must not break: it declares NO team_verdict and
+   * passes `verdicts: []`, so it has always resolved by status and must go on
+   * doing exactly that. Its enum runs past `acceptable` into outcomes that are
+   * NOT consequences of accepting — which is why only TERMINAL stages count
+   * forward.
+   */
+  describe('news_item (no verdict vocabulary) is untouched', () => {
+    const newsType = type([
+      enumAttr('status', [
+        'new', 'surfaced', 'acceptable', 'cited', 'ignored', 'rejected', 'preview_only',
+      ]),
+    ]);
+    const newsCfg = resolveReviewConfig(newsType, {
+      approveStatus: 'acceptable',
+      rejectStatus: 'rejected',
+      verdicts: [],
+      omitNeedsWork: true,
+    });
+    const newsDecisions = reviewDecisions(newsCfg);
+    const nk = (status: string) => activeDecisionKey({ status }, newsCfg, newsDecisions);
+
+    it('acceptable → Accept, rejected → Reject', () => {
+      expect(nk('acceptable')).toBe('approve');
+      expect(nk('rejected')).toBe('reject');
+    });
+
+    it('the entry stage and the pre-decision stages light nothing', () => {
+      expect(nk('new')).toBeNull();
+      expect(nk('surfaced')).toBeNull();
+    });
+
+    it('`ignored` / `preview_only` sit AFTER acceptable and still light nothing', () => {
+      // The forward rule is gated on a TERMINAL-reading status for exactly this:
+      // being ignored is a different outcome, not a consequence of accepting.
+      expect(nk('ignored')).toBeNull();
+      expect(nk('preview_only')).toBeNull();
+      expect(nk('cited')).toBeNull();
+    });
+  });
+
+  it('a type with no status enum at all still resolves by verdict', () => {
+    // There, nothing but the buttons themselves writes a verdict, so the verdict
+    // IS the decision. `reviewDecisions` yields none without a status pipeline,
+    // so this asserts the branch directly.
+    const cfg = resolveReviewConfig(type([textAttr('team_verdict')]));
+    const decisions: ReviewDecision[] = [
+      { key: 'approve', label: 'Approve', status: null, verdict: 'good', tone: 'good', advance: true, shortcut: 'a', promptNote: false },
+      { key: 'reject', label: 'Reject', status: null, verdict: 'bad', tone: 'bad', advance: true, shortcut: 'x', promptNote: false },
+    ];
+    expect(activeDecisionKey({ team_verdict: 'good' }, cfg, decisions)).toBe('approve');
+    expect(activeDecisionKey({ team_verdict: 'bad' }, cfg, decisions)).toBe('reject');
+    expect(activeDecisionKey({}, cfg, decisions)).toBeNull();
+  });
+});
+
+describe('isTerminalStatus', () => {
+  it('names the end-of-pipeline stages the forward rule keys off', () => {
+    for (const s of ['written', 'published', 'sent', 'live', 'closed']) {
+      expect(isTerminalStatus(s)).toBe(true);
+    }
+    for (const s of ['suggested', 'ready', 'rejected', 'ignored', 'preview_only', 'cited']) {
+      expect(isTerminalStatus(s)).toBe(false);
+    }
+  });
+});

package/src/components/collection/index.ts

@@ -13,6 +13,8 @@ export {
   resolveReviewConfig,
   deriveReviewTransitions,
   reviewDecisions,
+  activeDecisionKey,
+  isTerminalStatus,
   decisionLabel,
   DEFAULT_DECISION_LABELS,
   applyDecisionToData,