vericify 1.0.2 → 1.1.0

package/src/projection/live-signal.js

@@ -0,0 +1,627 @@
+import { firstDefined } from "../core/util.js";
+
+const MINUTE_MS = 60 * 1000;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+
+const BASE_SIGNAL_SCORE = {
+  primary: 100,
+  secondary: 60,
+  continuity: 20,
+  background: 0,
+};
+
+const FRESHNESS_SCORE = {
+  fresh: 24,
+  aging: 8,
+  stale: -18,
+  stale_acknowledged: -18,
+  archival: -40,
+};
+
+const PROVENANCE_SCORE = {
+  native: 12,
+  partner: 4,
+  derived: -20,
+};
+
+const NARRATIVE_WINDOWS = {
+  blocker: 5 * MINUTE_MS,
+  handoff_note: 10 * MINUTE_MS,
+  completion: 10 * MINUTE_MS,
+  stale_ack: 5 * MINUTE_MS,
+  intervention: 10 * MINUTE_MS,
+  operator_note: 10 * MINUTE_MS,
+};
+
+const RUN_FRESHNESS = {
+  running: { fresh: 15 * MINUTE_MS, stale: 120 * MINUTE_MS, label: "running work" },
+  blocked: { fresh: 10 * MINUTE_MS, stale: 45 * MINUTE_MS, label: "blocked work" },
+  handoff_open: { fresh: 30 * MINUTE_MS, stale: 180 * MINUTE_MS, label: "open handoff" },
+  handoff_accepted: { fresh: 20 * MINUTE_MS, stale: 90 * MINUTE_MS, label: "accepted handoff" },
+  default: { fresh: 15 * MINUTE_MS, stale: 120 * MINUTE_MS, label: "active work" },
+};
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function parseTimestamp(value) {
+  if (!value) return Number.NaN;
+  const ms = Date.parse(value);
+  return Number.isNaN(ms) ? Number.NaN : ms;
+}
+
+function sortByTimestamp(items, accessor) {
+  return [...items].sort((left, right) => String(accessor(left)).localeCompare(String(accessor(right))));
+}
+
+function addDuration(timestamp, deltaMs) {
+  const ms = parseTimestamp(timestamp);
+  if (Number.isNaN(ms)) return undefined;
+  return new Date(ms + deltaMs).toISOString();
+}
+
+function durationLabel(deltaMs) {
+  const abs = Math.abs(deltaMs);
+  if (abs < MINUTE_MS) return "now";
+  if (abs < HOUR_MS) return `${Math.round(abs / MINUTE_MS)}m`;
+  if (abs < DAY_MS) return `${Math.round(abs / HOUR_MS)}h`;
+  return `${Math.round(abs / DAY_MS)}d`;
+}
+
+function humanize(value) {
+  return String(value ?? "")
+    .replace(/[-_]+/g, " ")
+    .trim();
+}
+
+function hasRecordSource(record, source) {
+  if (record?.record_source === source) return true;
+  return Array.isArray(record?.record_sources) && record.record_sources.some((entry) => entry?.source === source);
+}
+
+function primaryRecordSource(record) {
+  if (record?.record_source) return record.record_source;
+  const first = Array.isArray(record?.record_sources) ? record.record_sources[0]?.source : undefined;
+  return first ?? "derived";
+}
+
+function collapsePolicyForItem(item) {
+  if (item.source_kind === "lane_heartbeat") {
+    return {
+      collapse_key: `${item.run_id}:heartbeat:${item.lane_id ?? item.actor_id ?? "-"}`,
+      collapse_window_ms: 0,
+    };
+  }
+  if (item.signal_class === "background" || item.visible_by_default === false) {
+    return {
+      collapse_key: `${item.run_id}:observer:${item.source_kind}:${item.actor_id}:${item.label}:${item.status}`,
+      collapse_window_ms: 10 * MINUTE_MS,
+    };
+  }
+  if ((item.source_kind === "status_event" || item.source_kind === "run_ledger") && item.signal_class !== "primary") {
+    return {
+      collapse_key: `${item.run_id}:maintenance:${item.source_kind}:${item.actor_id}:${item.label}:${item.status}`,
+      collapse_window_ms: 5 * MINUTE_MS,
+    };
+  }
+  return {
+    collapse_key: `${item.run_id}:${item.activity_id}`,
+    collapse_window_ms: 0,
+  };
+}
+
+function collapseSummaryForGroup(items, representative) {
+  if (items.length <= 1) return undefined;
+  if (representative.signal_class === "background" || representative.visible_by_default === false) {
+    return `${items.length} observer updates hidden by default`;
+  }
+  const label = humanize(representative.label || representative.source_kind || "event");
+  return `${items.length} ${label} updates; latest ${representative.summary}`;
+}
+
+function scoreActivityItem(item, nowMs) {
+  const reasons = [];
+  let score = BASE_SIGNAL_SCORE[item.signal_class] ?? 0;
+  reasons.push(`signal_class=${item.signal_class}(${BASE_SIGNAL_SCORE[item.signal_class] ?? 0})`);
+
+  const source = primaryRecordSource(item);
+  const provenance = PROVENANCE_SCORE[source] ?? 0;
+  score += provenance;
+  reasons.push(`provenance=${source}(${provenance})`);
+
+  const itemMs = parseTimestamp(item.timestamp);
+  const ageMs = Number.isNaN(itemMs) ? DAY_MS + 1 : nowMs - itemMs;
+  let freshnessClass = "archival";
+  if (ageMs <= 10 * MINUTE_MS) freshnessClass = "fresh";
+  else if (ageMs <= 60 * MINUTE_MS) freshnessClass = "aging";
+  else if (ageMs <= DAY_MS) freshnessClass = "stale";
+  const freshness = FRESHNESS_SCORE[freshnessClass] ?? 0;
+  score += freshness;
+  reasons.push(`freshness=${freshnessClass}(${freshness})`);
+
+  const novelty = item.collapsed_event_count > 1 ? -12 : 16;
+  score += novelty;
+  reasons.push(`novelty=${item.collapsed_event_count > 1 ? "repeated" : "new"}(${novelty})`);
+
+  const lifecycle = item.status === "blocked" || item.status === "failed" ? 40 : item.status === "completed" ? 10 : 0;
+  score += lifecycle;
+  if (lifecycle) reasons.push(`lifecycle=${item.status}(${lifecycle})`);
+
+  const narrative = item.source_kind === "process_post" ? 10 : 0;
+  score += narrative;
+  if (narrative) reasons.push(`narrative=present(${narrative})`);
+
+  return {
+    ...item,
+    score: clamp(score, 0, 200),
+    score_reasons: reasons,
+    display_summary: item.collapse_summary ?? item.summary,
+  };
+}
+
+export function isMeaningfulActivity(item) {
+  return item?.signal_class === "primary" || item?.signal_class === "secondary";
+}
+
+export function collapseAndScoreActivityItems(items, { now = Date.now() } = {}) {
+  const nowMs = typeof now === "string" ? parseTimestamp(now) : now;
+  const sorted = sortByTimestamp(items ?? [], (item) => item.timestamp ?? "");
+  const groups = [];
+
+  for (const item of sorted) {
+    const policy = collapsePolicyForItem(item);
+    const itemMs = parseTimestamp(item.timestamp);
+    const previous = groups.at(-1);
+    if (
+      previous &&
+      previous.collapse_key === policy.collapse_key &&
+      policy.collapse_window_ms > 0 &&
+      !Number.isNaN(itemMs) &&
+      !Number.isNaN(previous.last_ms) &&
+      itemMs - previous.last_ms <= policy.collapse_window_ms
+    ) {
+      previous.items.push(item);
+      previous.last_ms = itemMs;
+      continue;
+    }
+    groups.push({
+      collapse_key: policy.collapse_key,
+      collapse_window_ms: policy.collapse_window_ms,
+      items: [item],
+      first_ms: itemMs,
+      last_ms: itemMs,
+    });
+  }
+
+  return groups.map((group) => {
+    const representative = { ...group.items[group.items.length - 1] };
+    representative.collapse_key = group.collapse_key;
+    representative.collapse_window_ms = group.collapse_window_ms;
+    representative.first_timestamp = group.items[0]?.timestamp;
+    representative.collapsed_event_count = group.items.length;
+    representative.suppressed_event_ids = group.items.slice(0, -1).map((item) => item.activity_id);
+    representative.collapse_summary = collapseSummaryForGroup(group.items, representative);
+    return scoreActivityItem(representative, nowMs);
+  });
+}
+
+function latest(items, accessor) {
+  return sortByTimestamp(items ?? [], accessor).at(-1);
+}
+
+function latestMatching(items, accessor, predicate) {
+  return sortByTimestamp((items ?? []).filter(predicate), accessor).at(-1);
+}
+
+function latestNativePost(posts, kind, triggerTimestamp) {
+  const triggerMs = parseTimestamp(triggerTimestamp);
+  return latestMatching(posts, (post) => post.timestamp ?? "", (post) =>
+    hasRecordSource(post, "native") &&
+    post.kind === kind &&
+    (Number.isNaN(triggerMs) || parseTimestamp(post.timestamp) >= triggerMs)
+  );
+}
+
+function inferPresence(runDetail, meaningfulItems, processPosts, activeHandoff) {
+  if (activeHandoff) {
+    return {
+      current_actor_id: activeHandoff.to_agent ?? activeHandoff.from_agent,
+      waiting_on_actor_id: activeHandoff.to_agent ?? activeHandoff.from_agent,
+      acknowledgement_state: activeHandoff.status,
+      last_response_at: activeHandoff.updated_at ?? activeHandoff.created_at,
+      presence_source: "handoff",
+    };
+  }
+  const latestPost = latest(processPosts, (post) => post.timestamp ?? "");
+  if (latestPost) {
+    return {
+      current_actor_id: latestPost.agent_id ?? "unknown",
+      waiting_on_actor_id: undefined,
+      acknowledgement_state: "not_required",
+      last_response_at: latestPost.timestamp,
+      presence_source: hasRecordSource(latestPost, "native") ? "native_post" : "partner_post",
+    };
+  }
+  const latestItem = latest(meaningfulItems, (item) => item.timestamp ?? "");
+  if (latestItem) {
+    return {
+      current_actor_id: latestItem.actor_id ?? "unknown",
+      waiting_on_actor_id: undefined,
+      acknowledgement_state: "not_required",
+      last_response_at: latestItem.timestamp,
+      presence_source: latestItem.source_kind,
+    };
+  }
+  const latestLane = latest(runDetail.lanes ?? [], (lane) => lane.updated_at ?? "");
+  return {
+    current_actor_id: latestLane?.agent_id,
+    waiting_on_actor_id: undefined,
+    acknowledgement_state: "unknown",
+    last_response_at: latestLane?.updated_at,
+    presence_source: latestLane ? "lane" : "none",
+  };
+}
+
+function freshnessProfile(runDetail, activeHandoff) {
+  if (activeHandoff?.status === "accepted") return RUN_FRESHNESS.handoff_accepted;
+  if (activeHandoff?.status === "open") return RUN_FRESHNESS.handoff_open;
+  if (runDetail.run.status === "blocked") return RUN_FRESHNESS.blocked;
+  if (runDetail.run.status === "running") return RUN_FRESHNESS.running;
+  return RUN_FRESHNESS.default;
+}
+
+function classifyFreshness(runDetail, lastMeaningfulUpdateAt, lastStaleAckAt, activeHandoff, nowMs) {
+  const profile = freshnessProfile(runDetail, activeHandoff);
+  const lastMeaningfulMs = parseTimestamp(lastMeaningfulUpdateAt);
+  if (Number.isNaN(lastMeaningfulMs)) {
+    return {
+      freshness_class: "archival",
+      freshness_reason: "No meaningful activity available.",
+      stale_since: undefined,
+      overdue_seconds: 0,
+      needs_stale_ack: false,
+      freshness_profile_label: profile.label,
+    };
+  }
+  const ageMs = nowMs - lastMeaningfulMs;
+  const staleSince = new Date(lastMeaningfulMs + profile.stale).toISOString();
+  const staleAckMs = parseTimestamp(lastStaleAckAt);
+  let freshnessClass = "fresh";
+  if (ageMs > DAY_MS) freshnessClass = "archival";
+  else if (ageMs > profile.stale) freshnessClass = !Number.isNaN(staleAckMs) && staleAckMs >= lastMeaningfulMs ? "stale_acknowledged" : "stale";
+  else if (ageMs > profile.fresh) freshnessClass = "aging";
+  const active = runDetail.run.status === "running" || runDetail.run.status === "blocked" || activeHandoff;
+  return {
+    freshness_class: freshnessClass,
+    freshness_reason: `${profile.label} silent for ${durationLabel(ageMs)}.`,
+    stale_since: staleSince,
+    overdue_seconds: ageMs > profile.stale ? Math.round((ageMs - profile.stale) / 1000) : 0,
+    needs_stale_ack: active && freshnessClass === "stale",
+    freshness_profile_label: profile.label,
+  };
+}
+
+function latestBlockedSignal(runDetail, meaningfulItems) {
+  const item = latestMatching(meaningfulItems, (entry) => entry.timestamp ?? "", (entry) => entry.status === "blocked" || entry.status === "failed");
+  if (item) return { timestamp: item.timestamp, source: "activity", summary: item.display_summary ?? item.summary };
+  const handoff = latestMatching(runDetail.handoff_timeline?.items ?? [], (entry) => entry.updated_at ?? entry.created_at ?? "", (entry) => entry.status === "blocked");
+  if (handoff) return { timestamp: handoff.updated_at ?? handoff.created_at, source: "handoff", summary: handoff.node_ref ?? handoff.handoff_id };
+  return undefined;
+}
+
+function latestCompletionSignal(runDetail, meaningfulItems) {
+  const item = latestMatching(meaningfulItems, (entry) => entry.timestamp ?? "", (entry) => entry.status === "completed");
+  if (item) return { timestamp: item.timestamp, source: "activity", summary: item.display_summary ?? item.summary };
+  const handoff = latestMatching(runDetail.handoff_timeline?.items ?? [], (entry) => entry.updated_at ?? entry.created_at ?? "", (entry) => entry.status === "completed");
+  if (handoff) return { timestamp: handoff.updated_at ?? handoff.created_at, source: "handoff", summary: handoff.node_ref ?? handoff.handoff_id };
+  return undefined;
+}
+
+function summarizeTemplate(kind, owner, nextTimestamp) {
+  if (kind === "blocker") return `Blocked on ${owner ?? "<owner>"}. Next check at ${nextTimestamp ?? "<time>"}.`;
+  if (kind === "handoff_note") return `Accepted handoff. Next action: ${owner ?? "<next step>"}.`;
+  if (kind === "completion") return `Completed <change>. New truth: <outcome>.`;
+  if (kind === "stale_ack") return `Silence is expected because ${owner ?? "<reason>"}. Re-check at ${nextTimestamp ?? "<time>"}.`;
+  if (kind === "operator_note") return `Changed <thing>. Next expected event: ${owner ?? "<event>"}.`;
+  return `Update ${owner ?? "<state>"}.`;
+}
+
+function deriveNarrativeState({
+  runDetail,
+  meaningfulItems,
+  processPosts,
+  activeHandoff,
+  freshness,
+  currentActorId,
+  lastMeaningfulUpdateAt,
+}) {
+  const nativeMeaningful = meaningfulItems.filter((item) => hasRecordSource(item, "native"));
+  const totalMeaningful = meaningfulItems.length;
+  const nativeSignalRatio = totalMeaningful ? nativeMeaningful.length / totalMeaningful : 0;
+  const partnerDependencyClass = nativeSignalRatio >= 0.6 ? "native-led" : nativeSignalRatio >= 0.25 ? "mixed" : "partner-led";
+  const nativeSignalGap = totalMeaningful > 0 && nativeSignalRatio < 0.35;
+
+  const blockedSignal = latestBlockedSignal(runDetail, meaningfulItems);
+  const acceptedHandoff = latestMatching(runDetail.handoff_timeline?.items ?? [], (entry) => entry.updated_at ?? entry.created_at ?? "", (entry) => entry.status === "accepted");
+  const completionSignal = latestCompletionSignal(runDetail, meaningfulItems);
+  const lastStaleAck = latestMatching(processPosts, (post) => post.timestamp ?? "", (post) => post.kind === "stale_ack");
+
+  const obligations = [];
+  if (blockedSignal && !latestNativePost(processPosts, "blocker", blockedSignal.timestamp)) {
+    obligations.push({
+      kind: "blocker",
+      due_at: addDuration(blockedSignal.timestamp, NARRATIVE_WINDOWS.blocker),
+      reason: "Blocked work lacks a native blocker explanation.",
+    });
+  }
+  if (acceptedHandoff && !latestNativePost(processPosts, "handoff_note", acceptedHandoff.updated_at ?? acceptedHandoff.created_at)) {
+    obligations.push({
+      kind: "handoff_note",
+      due_at: addDuration(acceptedHandoff.updated_at ?? acceptedHandoff.created_at, NARRATIVE_WINDOWS.handoff_note),
+      reason: "Accepted handoff lacks a native acknowledgement note.",
+    });
+  }
+  if (completionSignal && !latestNativePost(processPosts, "completion", completionSignal.timestamp)) {
+    obligations.push({
+      kind: "completion",
+      due_at: addDuration(completionSignal.timestamp, NARRATIVE_WINDOWS.completion),
+      reason: "Completed work lacks a native completion summary.",
+    });
+  }
+  if (freshness.needs_stale_ack && !latestNativePost(processPosts, "stale_ack", freshness.stale_since)) {
+    obligations.push({
+      kind: "stale_ack",
+      due_at: freshness.stale_since,
+      reason: "Stale work lacks a native silence acknowledgement.",
+    });
+  }
+  if (nativeSignalGap && !latestNativePost(processPosts, "operator_note", lastMeaningfulUpdateAt)) {
+    obligations.push({
+      kind: "operator_note",
+      due_at: addDuration(lastMeaningfulUpdateAt, NARRATIVE_WINDOWS.operator_note),
+      reason: "Meaningful movement is mostly partner-derived and lacks a native Vericify note.",
+    });
+  }
+
+  const obligation = obligations[0];
+  return {
+    needs_narrative: Boolean(obligation),
+    recommended_post_kind: obligation?.kind,
+    recommended_summary_template: obligation ? summarizeTemplate(obligation.kind, currentActorId, obligation.due_at) : undefined,
+    native_signal_gap: nativeSignalGap,
+    native_signal_gap_reason: nativeSignalGap ? `Native meaningful coverage is ${(nativeSignalRatio * 100).toFixed(0)}%.` : "Native meaningful coverage is healthy.",
+    native_signal_ratio: Number(nativeSignalRatio.toFixed(3)),
+    native_narrative_gap: Boolean(obligation),
+    partner_dependency_class: partnerDependencyClass,
+    narrative_reason: obligation?.reason,
+    narrative_due_at: obligation?.due_at,
+  };
+}
+
+function isHumanNote(post) {
+  if (post.kind === "operator_note") return true;
+  const agent = String(post.agent_id ?? "").toLowerCase();
+  return agent === "operator" || agent === "human" || agent === "vericify-hub";
+}
+
+function determineExpectedNextEvent(runDetail, activeHandoff, narrativeState, freshness, lastMeaningfulUpdateAt) {
+  if (activeHandoff?.status === "open") {
+    return {
+      expected_next_event: "accept_handoff",
+      overdue_at: addDuration(activeHandoff.updated_at ?? activeHandoff.created_at, RUN_FRESHNESS.handoff_open.fresh),
+      recommended_owner_action: "accept_handoff",
+    };
+  }
+  if (narrativeState.recommended_post_kind) {
+    return {
+      expected_next_event: narrativeState.recommended_post_kind,
+      overdue_at: narrativeState.narrative_due_at,
+      recommended_owner_action: narrativeState.recommended_post_kind === "stale_ack" ? "ack_stale" : "write_note",
+    };
+  }
+  if (runDetail.run.status === "blocked") {
+    return {
+      expected_next_event: "resolve_blocker",
+      overdue_at: freshness.stale_since,
+      recommended_owner_action: "resolve_blocker",
+    };
+  }
+  if (runDetail.run.status === "running") {
+    return {
+      expected_next_event: "state_update",
+      overdue_at: freshness.stale_since ?? addDuration(lastMeaningfulUpdateAt, RUN_FRESHNESS.running.stale),
+      recommended_owner_action: "update_state",
+    };
+  }
+  if (runDetail.run.status === "planned") {
+    return {
+      expected_next_event: "clarify_owner",
+      overdue_at: addDuration(lastMeaningfulUpdateAt, RUN_FRESHNESS.default.stale),
+      recommended_owner_action: "clarify_owner",
+    };
+  }
+  return {
+    expected_next_event: null,
+    overdue_at: null,
+    recommended_owner_action: "observe_only",
+  };
+}
+
+function attentionClassForRun(runDetail, freshness, expected, narrativeState, overdueSeconds, activeHandoff) {
+  if (activeHandoff && overdueSeconds > 0) return "overdue_handoff";
+  if (runDetail.run.status === "blocked") return "blocked";
+  if (runDetail.run.status === "running" && (freshness.freshness_class === "stale" || freshness.freshness_class === "stale_acknowledged" || freshness.freshness_class === "archival")) {
+    return "stale_running";
+  }
+  if (narrativeState.needs_narrative) return "missing_narrative";
+  if (narrativeState.native_signal_gap) return "native_signal_gap";
+  if (expected.expected_next_event) return "active";
+  return "observe_only";
+}
+
+function baseSignalClassForAttention(attentionClass) {
+  if (["blocked", "overdue_handoff", "stale_running", "missing_narrative"].includes(attentionClass)) return "primary";
+  if (["active", "native_signal_gap"].includes(attentionClass)) return "secondary";
+  return "continuity";
+}
+
+function buildAttentionReason(runDetail, attentionClass, narrativeState, freshness, expected, overdueSeconds, currentActorId) {
+  if (attentionClass === "blocked") return narrativeState.narrative_reason ?? "Blocked work needs movement.";
+  if (attentionClass === "overdue_handoff") return `Handoff is overdue for ${currentActorId ?? "the recipient"}.`;
+  if (attentionClass === "stale_running") return `Running work has gone ${freshness.freshness_class.replace(/_/g, " ")} without meaningful updates.`;
+  if (attentionClass === "missing_narrative") return narrativeState.narrative_reason ?? "Native narrative is missing.";
+  if (attentionClass === "native_signal_gap") return narrativeState.native_signal_gap_reason;
+  if (expected.expected_next_event) return `Awaiting ${humanize(expected.expected_next_event)}.`;
+  if (runDetail.run.status === "completed") return "Completed; observe for follow-up only.";
+  return "No immediate action required.";
+}
+
+function buildWhyNow(attentionReason, overdueSeconds, latestMeaningful) {
+  if (overdueSeconds > 0) return `${attentionReason} Late by ${durationLabel(overdueSeconds * 1000)}.`;
+  if (latestMeaningful) return latestMeaningful.display_summary ?? latestMeaningful.summary ?? attentionReason;
+  return attentionReason;
+}
+
+function signalConfidence({ latestMeaningful, currentActorId, expectedNextEvent, narrativeState, source }) {
+  let confidence = 0.5;
+  if (latestMeaningful) confidence += 0.15;
+  if (currentActorId) confidence += 0.1;
+  if (expectedNextEvent) confidence += 0.1;
+  if (!narrativeState.needs_narrative) confidence += 0.05;
+  if (source === "native") confidence += 0.05;
+  if (source === "derived") confidence -= 0.2;
+  if (narrativeState.native_signal_gap) confidence -= 0.1;
+  return clamp(Number(confidence.toFixed(2)), 0.1, 0.99);
+}
+
+export function deriveRunLiveSignal(runDetail, { now = Date.now() } = {}) {
+  const nowMs = typeof now === "string" ? parseTimestamp(now) : now;
+  const activityItems = sortByTimestamp(runDetail.activity_items ?? [], (item) => item.timestamp ?? "");
+  const meaningfulItems = activityItems.filter(isMeaningfulActivity);
+  const processPosts = sortByTimestamp(runDetail.process_posts ?? [], (post) => post.timestamp ?? "");
+  const activeHandoff = latestMatching(
+    runDetail.handoff_timeline?.items ?? [],
+    (item) => item.updated_at ?? item.created_at ?? "",
+    (item) => item.status === "open" || item.status === "accepted" || item.status === "blocked"
+  );
+  const latestMeaningful = meaningfulItems.at(-1);
+  const latestNativeMeaningful = meaningfulItems.filter((item) => hasRecordSource(item, "native")).at(-1);
+  const latestPartnerMeaningful = meaningfulItems.filter((item) => hasRecordSource(item, "partner")).at(-1);
+  const latestNativePost = latestMatching(processPosts, (post) => post.timestamp ?? "", (post) => hasRecordSource(post, "native"));
+  const lastStaleAck = latestMatching(processPosts, (post) => post.timestamp ?? "", (post) => post.kind === "stale_ack");
+  const lastMeaningfulUpdateAt = latestMeaningful?.timestamp ?? runDetail.run.updated_at;
+  const presence = inferPresence(runDetail, meaningfulItems, processPosts, activeHandoff);
+  const freshness = classifyFreshness(runDetail, lastMeaningfulUpdateAt, lastStaleAck?.timestamp, activeHandoff, nowMs);
+  const narrativeState = deriveNarrativeState({
+    runDetail,
+    meaningfulItems,
+    processPosts,
+    activeHandoff,
+    freshness,
+    currentActorId: presence.current_actor_id,
+    lastMeaningfulUpdateAt,
+  });
+  const expected = determineExpectedNextEvent(runDetail, activeHandoff, narrativeState, freshness, lastMeaningfulUpdateAt);
+  const overdueAtMs = parseTimestamp(expected.overdue_at);
+  const overdueSeconds = !Number.isNaN(overdueAtMs) && nowMs > overdueAtMs ? Math.round((nowMs - overdueAtMs) / 1000) : 0;
+  const attentionClass = attentionClassForRun(runDetail, freshness, expected, narrativeState, overdueSeconds, activeHandoff);
+  const baseSignalClass = baseSignalClassForAttention(attentionClass);
+  const source = primaryRecordSource(latestMeaningful ?? latestNativePost ?? { record_source: "derived" });
+  const reasons = [];
+  let attentionScore = BASE_SIGNAL_SCORE[baseSignalClass] ?? 0;
+  reasons.push(`signal_class=${baseSignalClass}(${BASE_SIGNAL_SCORE[baseSignalClass] ?? 0})`);
+
+  const severity = attentionClass === "blocked" || attentionClass === "overdue_handoff" ? 40 : 0;
+  attentionScore += severity;
+  if (severity) reasons.push(`severity=${attentionClass}(${severity})`);
+
+  const freshnessModifier = FRESHNESS_SCORE[freshness.freshness_class] ?? 0;
+  attentionScore += freshnessModifier;
+  reasons.push(`freshness=${freshness.freshness_class}(${freshnessModifier})`);
+
+  const provenanceModifier = PROVENANCE_SCORE[source] ?? 0;
+  attentionScore += provenanceModifier;
+  reasons.push(`provenance=${source}(${provenanceModifier})`);
+
+  const noveltyModifier = latestMeaningful?.collapsed_event_count > 1 ? -12 : 16;
+  attentionScore += noveltyModifier;
+  reasons.push(`novelty=${latestMeaningful?.collapsed_event_count > 1 ? "repeated" : "new"}(${noveltyModifier})`);
+
+  const narrativeModifier = narrativeState.needs_narrative ? -14 : latestNativePost ? 10 : 0;
+  attentionScore += narrativeModifier;
+  reasons.push(`narrative=${narrativeState.needs_narrative ? "missing" : latestNativePost ? "present" : "none"}(${narrativeModifier})`);
+
+  const ownershipModifier = presence.current_actor_id && expected.expected_next_event ? 8 : -10;
+  attentionScore += ownershipModifier;
+  reasons.push(`ownership=${presence.current_actor_id && expected.expected_next_event ? "clear" : "missing"}(${ownershipModifier})`);
+
+  const attentionReason = buildAttentionReason(runDetail, attentionClass, narrativeState, freshness, expected, overdueSeconds, presence.current_actor_id);
+  const whyNow = buildWhyNow(attentionReason, overdueSeconds, latestMeaningful);
+  const lastHumanNote = latestMatching(processPosts, (post) => post.timestamp ?? "", (post) => isHumanNote(post));
+  const lastAgentNote = latestMatching(processPosts, (post) => post.timestamp ?? "", (post) => !isHumanNote(post));
+
+  return {
+    attention_class: attentionClass,
+    attention_reason: attentionReason,
+    attention_score: clamp(attentionScore, 0, 200),
+    attention_rank: 0,
+    why_now: whyNow,
+    expected_next_event: expected.expected_next_event,
+    overdue_at: expected.overdue_at,
+    overdue_seconds: overdueSeconds,
+    escalation_state: overdueSeconds > 0 ? "late" : freshness.freshness_class === "aging" ? "watch" : "clear",
+    highlight_reason: attentionReason,
+    recommended_owner_action: expected.recommended_owner_action,
+    recommended_post_kind: narrativeState.recommended_post_kind,
+    recommended_summary_template: narrativeState.recommended_summary_template,
+    next_best_update_kind: firstDefined(narrativeState.recommended_post_kind, expected.expected_next_event, "observe_only"),
+    needs_narrative: narrativeState.needs_narrative,
+    native_signal_gap: narrativeState.native_signal_gap,
+    native_signal_gap_reason: narrativeState.native_signal_gap_reason,
+    native_signal_ratio: narrativeState.native_signal_ratio,
+    native_narrative_gap: narrativeState.native_narrative_gap,
+    partner_dependency_class: narrativeState.partner_dependency_class,
+    freshness_class: freshness.freshness_class,
+    freshness_reason: freshness.freshness_reason,
+    stale_since: freshness.stale_since,
+    needs_stale_ack: freshness.needs_stale_ack,
+    silence_owner: presence.waiting_on_actor_id ?? presence.current_actor_id,
+    silence_explainer: overdueSeconds > 0 ? `Expected ${humanize(expected.expected_next_event)} is late.` : freshness.freshness_reason,
+    current_actor_id: presence.current_actor_id,
+    waiting_on_actor_id: presence.waiting_on_actor_id,
+    acknowledgement_state: freshness.freshness_class === "stale_acknowledged" ? "stale_acknowledged" : presence.acknowledgement_state,
+    last_response_at: presence.last_response_at,
+    presence_source: presence.presence_source,
+    last_meaningful_update_at: lastMeaningfulUpdateAt,
+    last_native_update_at: firstDefined(latestNativeMeaningful?.timestamp, latestNativePost?.timestamp),
+    last_partner_update_at: latestPartnerMeaningful?.timestamp,
+    last_human_note_at: lastHumanNote?.timestamp,
+    last_agent_note_at: lastAgentNote?.timestamp,
+    signal_confidence: signalConfidence({
+      latestMeaningful,
+      currentActorId: presence.current_actor_id,
+      expectedNextEvent: expected.expected_next_event,
+      narrativeState,
+      source,
+    }),
+    score_reasons: reasons,
+    should_interrupt_agent: clamp(attentionScore, 0, 200) >= 140 || attentionClass === "overdue_handoff",
+  };
+}
+
+export function compareRunsByAttention(left, right) {
+  const leftSignal = left.live_signal ?? {};
+  const rightSignal = right.live_signal ?? {};
+  const leftScore = leftSignal.attention_score ?? 0;
+  const rightScore = rightSignal.attention_score ?? 0;
+  if (leftScore !== rightScore) return rightScore - leftScore;
+  const leftMeaningful = parseTimestamp(leftSignal.last_meaningful_update_at ?? left.run.updated_at);
+  const rightMeaningful = parseTimestamp(rightSignal.last_meaningful_update_at ?? right.run.updated_at);
+  if (leftMeaningful !== rightMeaningful) return rightMeaningful - leftMeaningful;
+  const provenanceDelta = (PROVENANCE_SCORE[primaryRecordSource({ record_source: rightSignal.last_native_update_at ? "native" : rightSignal.last_partner_update_at ? "partner" : "derived" })] ?? 0) -
+    (PROVENANCE_SCORE[primaryRecordSource({ record_source: leftSignal.last_native_update_at ? "native" : leftSignal.last_partner_update_at ? "partner" : "derived" })] ?? 0);
+  if (provenanceDelta !== 0) return provenanceDelta;
+  return String(left.run.run_id).localeCompare(String(right.run.run_id));
+}