@poetic-ai/poetic 1.42.0

package/integrations/bb-plugin-poetic/src/judge-operations-view.ts

@@ -0,0 +1,459 @@
+/**
+ * Pure BB cockpit presentation for Poetic's judge-operations projection.
+ *
+ * This module is presentation only. It maps one already-canonical projection
+ * record to bounded, plain-language rows suitable for the existing panel visual
+ * language (`label: value` lines rendered as `<small>`/`<span>` text). It holds
+ * the same authority boundary the rest of this plugin holds:
+ *
+ *   - Poetic is authoritative. Nothing here selects, recomputes, re-ranks, or
+ *     re-labels a judge winner, score, confidence, Matrix decision, synthesis
+ *     result, or delivery result.
+ *   - Absent upstream evidence renders as an explicit `unavailable`. A missing
+ *     field is never replaced by a default, a guess, or an empty success state.
+ *   - The immutable judge winner is rendered on its own row, separately from the
+ *     synthesized and delivered artifact identity, even when they agree.
+ *   - Matrix escalation is reported as status plus Poetic's own reasons. It does
+ *     not change which winner this view presents.
+ *
+ * The projection input is declared structurally, mirroring
+ * `run-progress-projection.ts`, so this presentation seam compiles without
+ * importing Poetic internals or a transport module. Threading the projection
+ * through the RPC contract and adapter is a separate slice.
+ */
+
+export const JUDGE_OPERATIONS_VIEW_VERSION = '1.0.0' as const;
+
+/** Bound on any single emitted line, mirroring the run-progress projection. */
+export const JUDGE_OPERATIONS_MAX_LINE_CHARS = 160;
+
+/** Bound on how many judge, reason, or criterion names one row lists. */
+export const JUDGE_OPERATIONS_LIST_LIMIT = 8;
+
+/** Plain label for evidence Poetic did not publish. */
+const UNAVAILABLE = 'unavailable';
+
+/**
+ * Whether judging applies at all, and the run's own judge lifecycle position.
+ * `unknown` is emitted rather than guessing, exactly as the progress projection
+ * does for run phase.
+ */
+export type JudgeOperationsStatus = 'not_started' | 'running' | 'complete' | 'unknown';
+
+/** Poetic's own outcome label for the primary judge verdict. */
+export type JudgeVerdictOutcome = 'decisive' | 'inconclusive' | 'unknown';
+
+/** Matrix escalation status as Poetic published it. */
+export type MatrixEscalationStatus = 'escalated' | 'not_escalated' | 'unknown';
+
+/**
+ * How complete the underlying record is. `historical` and `partial` records are
+ * rendered with explicit caveats instead of being presented as clean results.
+ */
+export type JudgeEvidenceState = 'complete' | 'partial' | 'historical' | 'unavailable';
+
+/**
+ * Identity of a synthesized or delivered artifact. Deliberately separate from
+ * the judge winner: an artifact can share the winner's identity or diverge from
+ * it, and this view must never collapse the two.
+ */
+export interface JudgeArtifactIdentity {
+  /** Identity label Poetic published (artifact id, variant id, or path). */
+  id: string;
+  /** Variant identity when Poetic published one; null when unavailable. */
+  variantId: string | null;
+}
+
+/** The primary judge's verdict facts, copied from the projection. */
+export interface JudgePrimaryVerdictFacts {
+  /** Which judge produced the primary verdict; null when unavailable. */
+  judge: string | null;
+  outcome: JudgeVerdictOutcome;
+  /** Confidence on a 0-1 scale when Poetic published one. */
+  confidence: number | null;
+}
+
+/** Matrix escalation facts, copied from the projection. */
+export interface JudgeMatrixFacts {
+  status: MatrixEscalationStatus;
+  /** Poetic's own escalation reasons; null when unavailable. */
+  reasons: readonly string[] | null;
+}
+
+/** One criterion assessment with its evidence provenance, when available. */
+export interface JudgeCriterionAssessmentFacts {
+  criterion: string;
+  assessment: string;
+  /** Where the assessment's evidence came from; null when unavailable. */
+  evidenceProvenance: string | null;
+}
+
+/**
+ * Structural view of the judge-operations projection fields this presentation
+ * reads. `null` means Poetic published no value for that field, which renders as
+ * an explicit `unavailable`; an empty array means Poetic published "none".
+ */
+export interface JudgeOperationsProjectionFacts {
+  /** Version of the canonical projection contract that produced this record. */
+  contractVersion: string;
+  runId: string;
+  /** False for runs where judging does not apply, such as Fusion. */
+  applies: boolean;
+  /** Poetic's reason code when judging does not apply. */
+  notApplicableReason: string | null;
+  requestedJudges: readonly string[] | null;
+  executedJudges: readonly string[] | null;
+  phase: string | null;
+  status: JudgeOperationsStatus;
+  primaryVerdict: JudgePrimaryVerdictFacts | null;
+  matrix: JudgeMatrixFacts | null;
+  disagreements: readonly string[] | null;
+  humanChecks: readonly string[] | null;
+  criterionAssessments: readonly JudgeCriterionAssessmentFacts[] | null;
+  /** The immutable judge winner. Never re-derived here. */
+  judgeWinner: string | null;
+  synthesis: JudgeArtifactIdentity | null;
+  delivery: JudgeArtifactIdentity | null;
+  evidenceState: JudgeEvidenceState;
+}
+
+/**
+ * Cockpit state. It classifies what the operator is looking at; it does not
+ * decide any judge outcome.
+ */
+export type JudgeOperationsViewState =
+  | 'not_applicable'
+  | 'escalated'
+  | 'decisive'
+  | 'inconclusive'
+  | 'in_progress'
+  | 'unavailable';
+
+export interface JudgeOperationsRow {
+  /** Stable row id, usable as a render key. */
+  id: string;
+  label: string;
+  value: string;
+}
+
+export interface JudgeOperationsView {
+  viewVersion: typeof JUDGE_OPERATIONS_VIEW_VERSION;
+  /** Projection contract version this view rendered, carried through as-is. */
+  contractVersion: string;
+  runId: string;
+  state: JudgeOperationsViewState;
+  /** One bounded plain-language summary line. */
+  headline: string;
+  rows: readonly JudgeOperationsRow[];
+  /** Explicit caveats: missing evidence, escalation, winner/artifact divergence. */
+  notes: readonly string[];
+  /**
+   * True only when evidence Poetic would normally publish is missing or partial.
+   * A run where judging does not apply is never degraded.
+   */
+  degraded: boolean;
+}
+
+/** Reason codes rendered with a fixed plain-language phrase. */
+const NOT_APPLICABLE_REASON_LABELS: Readonly<Record<string, string>> = {
+  no_judge_by_design: 'No judge by design',
+};
+
+function truncateLine(text: string): string {
+  const normalized = text.replace(/\s+/g, ' ').trim();
+  if (normalized.length <= JUDGE_OPERATIONS_MAX_LINE_CHARS) return normalized;
+  return `${normalized.slice(0, JUDGE_OPERATIONS_MAX_LINE_CHARS - 3)}...`;
+}
+
+function normalizeReasonLabel(value: string): string {
+  return value.replace(/_/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Render a list Poetic published. `null` is unavailable evidence; an empty array
+ * is a published "none". The two are never conflated.
+ */
+function formatList(values: readonly string[] | null, emptyLabel = 'none'): string {
+  if (values === null) return UNAVAILABLE;
+  const present = values.map((value) => value.trim()).filter((value) => value.length > 0);
+  if (present.length === 0) return emptyLabel;
+  const shown = present.slice(0, JUDGE_OPERATIONS_LIST_LIMIT);
+  const remaining = present.length - shown.length;
+  return remaining > 0 ? `${shown.join(', ')} (+${remaining} more)` : shown.join(', ');
+}
+
+function formatIdentity(value: string | null): string {
+  const trimmed = value?.trim() ?? '';
+  return trimmed.length > 0 ? trimmed : UNAVAILABLE;
+}
+
+/**
+ * Confidence is rendered only when it is a usable 0-1 value. An out-of-range or
+ * non-finite number is reported unavailable rather than clamped, because
+ * clamping would present a value Poetic never declared.
+ */
+function formatConfidence(confidence: number | null): string {
+  if (confidence === null || !Number.isFinite(confidence)) return UNAVAILABLE;
+  if (confidence < 0 || confidence > 1) return UNAVAILABLE;
+  return confidence.toFixed(2);
+}
+
+function formatNotApplicableReason(reason: string | null): string | null {
+  const trimmed = reason?.trim() ?? '';
+  if (trimmed.length === 0) return null;
+  return NOT_APPLICABLE_REASON_LABELS[trimmed] ?? normalizeReasonLabel(trimmed);
+}
+
+function formatArtifact(artifact: JudgeArtifactIdentity | null): string {
+  if (artifact === null) return UNAVAILABLE;
+  const id = formatIdentity(artifact.id);
+  const variantId = artifact.variantId?.trim() ?? '';
+  if (variantId.length === 0 || variantId === id) return id;
+  return `${id} (variant ${variantId})`;
+}
+
+/** The identity an artifact should be compared against for divergence notes. */
+function artifactIdentity(artifact: JudgeArtifactIdentity | null): string | null {
+  if (artifact === null) return null;
+  const variantId = artifact.variantId?.trim() ?? '';
+  if (variantId.length > 0) return variantId;
+  const id = artifact.id.trim();
+  return id.length > 0 ? id : null;
+}
+
+function formatStatus(facts: JudgeOperationsProjectionFacts): string {
+  const status = facts.status === 'not_started' ? 'not started' : facts.status;
+  const phase = facts.phase?.trim() ?? '';
+  return phase.length > 0 ? `${status} (phase ${phase})` : status;
+}
+
+function formatCriterionAssessments(
+  assessments: readonly JudgeCriterionAssessmentFacts[] | null
+): string {
+  if (assessments === null) return UNAVAILABLE;
+  return formatList(
+    assessments.map((entry) => `${entry.criterion} ${entry.assessment}`),
+    'none recorded'
+  );
+}
+
+function formatEvidenceProvenance(
+  assessments: readonly JudgeCriterionAssessmentFacts[] | null
+): string {
+  if (assessments === null) return UNAVAILABLE;
+  if (assessments.length === 0) return 'none recorded';
+  const provenance = assessments
+    .map((entry) => entry.evidenceProvenance?.trim() ?? '')
+    .filter((entry) => entry.length > 0);
+  if (provenance.length === 0) return UNAVAILABLE;
+  const distinct = [...new Set(provenance)];
+  const coverage = `${provenance.length} of ${assessments.length} assessments`;
+  return `${formatList(distinct)} (${coverage})`;
+}
+
+function deriveState(facts: JudgeOperationsProjectionFacts): JudgeOperationsViewState {
+  if (!facts.applies) return 'not_applicable';
+  // Escalation is reported before verdict decisiveness so an escalated run is
+  // visible as escalated. It does not change which winner is presented.
+  if (facts.matrix?.status === 'escalated') return 'escalated';
+  if (facts.primaryVerdict?.outcome === 'decisive') return 'decisive';
+  if (facts.primaryVerdict?.outcome === 'inconclusive') return 'inconclusive';
+  if (facts.status === 'running' || facts.status === 'not_started') return 'in_progress';
+  return 'unavailable';
+}
+
+function deriveHeadline(
+  facts: JudgeOperationsProjectionFacts,
+  state: JudgeOperationsViewState
+): string {
+  switch (state) {
+    case 'not_applicable': {
+      const reason = formatNotApplicableReason(facts.notApplicableReason);
+      return reason === null
+        ? 'Judging not applicable; Poetic published no reason'
+        : `Judging not applicable: ${reason}`;
+    }
+    case 'escalated': {
+      const reasons = facts.matrix?.reasons ?? null;
+      const verdict =
+        facts.primaryVerdict?.outcome === 'inconclusive'
+          ? 'Matrix escalated; judge verdict inconclusive'
+          : 'Matrix escalated';
+      return `${verdict}: ${formatList(reasons, 'no reasons published')}`;
+    }
+    case 'decisive':
+      return `Judge verdict decisive: winner ${formatIdentity(facts.judgeWinner)}`;
+    case 'inconclusive':
+      return 'Judge verdict inconclusive';
+    case 'in_progress':
+      return `Judging ${formatStatus(facts)}`;
+    default:
+      return 'Judge operations evidence unavailable';
+  }
+}
+
+function buildRows(facts: JudgeOperationsProjectionFacts): JudgeOperationsRow[] {
+  const rows: JudgeOperationsRow[] = [];
+  const push = (id: string, label: string, value: string) => {
+    rows.push({ id, label, value: truncateLine(value) });
+  };
+
+  if (!facts.applies) {
+    const reason = formatNotApplicableReason(facts.notApplicableReason);
+    push('judging', 'Judging', `not applicable${reason === null ? '' : ` - ${reason}`}`);
+    push('judge-winner', 'Judge winner (immutable)', 'not applicable');
+    push('synthesized-artifact', 'Synthesized artifact', formatArtifact(facts.synthesis));
+    push('delivered-artifact', 'Delivered artifact', formatArtifact(facts.delivery));
+    return rows;
+  }
+
+  push('judges-requested', 'Judges requested', formatList(facts.requestedJudges));
+  push('judges-executed', 'Judges executed', formatList(facts.executedJudges));
+  push('judging-status', 'Judging status', formatStatus(facts));
+  push(
+    'primary-verdict',
+    'Primary verdict',
+    facts.primaryVerdict === null
+      ? UNAVAILABLE
+      : `${facts.primaryVerdict.outcome} (judge ${formatIdentity(facts.primaryVerdict.judge)})`
+  );
+  push(
+    'verdict-confidence',
+    'Confidence',
+    formatConfidence(facts.primaryVerdict?.confidence ?? null)
+  );
+  push(
+    'matrix-escalation',
+    'Matrix escalation',
+    facts.matrix === null
+      ? UNAVAILABLE
+      : facts.matrix.status === 'not_escalated'
+        ? 'not escalated'
+        : facts.matrix.status
+  );
+  push(
+    'matrix-reasons',
+    'Escalation reasons',
+    facts.matrix === null ? UNAVAILABLE : formatList(facts.matrix.reasons)
+  );
+  push('disagreements', 'Disagreements', formatList(facts.disagreements));
+  push('human-checks', 'Human checks', formatList(facts.humanChecks));
+  push(
+    'criterion-assessments',
+    'Criterion assessments',
+    formatCriterionAssessments(facts.criterionAssessments)
+  );
+  push(
+    'evidence-provenance',
+    'Evidence provenance',
+    formatEvidenceProvenance(facts.criterionAssessments)
+  );
+  push('judge-winner', 'Judge winner (immutable)', formatIdentity(facts.judgeWinner));
+  push('synthesized-artifact', 'Synthesized artifact', formatArtifact(facts.synthesis));
+  push('delivered-artifact', 'Delivered artifact', formatArtifact(facts.delivery));
+  return rows;
+}
+
+function buildNotes(
+  facts: JudgeOperationsProjectionFacts,
+  state: JudgeOperationsViewState
+): string[] {
+  const notes: string[] = [];
+
+  if (state === 'not_applicable') {
+    // A run without judging is complete as-is: no missing-evidence caveat, and
+    // nothing that would read as pending, degraded, broken, or empty.
+    notes.push('Poetic ran no judge for this run, so there is no judge verdict to report.');
+    return notes.map(truncateLine);
+  }
+
+  switch (facts.evidenceState) {
+    case 'historical':
+      notes.push(
+        'Historical record: Poetic did not publish judge operations evidence for this run.'
+      );
+      break;
+    case 'partial':
+      notes.push('Partial record: some judge operations evidence is unavailable.');
+      break;
+    case 'unavailable':
+      notes.push('Judge operations evidence is unavailable for this run.');
+      break;
+    default:
+      break;
+  }
+
+  if (state === 'escalated') {
+    notes.push(
+      'Matrix escalation is an escalated judge verdict. The judge winner shown here remains authoritative.'
+    );
+  }
+
+  if (facts.primaryVerdict?.outcome === 'inconclusive' && facts.judgeWinner === null) {
+    notes.push('The judge declared no winner. BB does not select one.');
+  }
+
+  const winner = facts.judgeWinner?.trim() ?? '';
+  if (winner.length > 0) {
+    const synthesis = artifactIdentity(facts.synthesis);
+    const delivery = artifactIdentity(facts.delivery);
+    if (synthesis !== null && synthesis !== winner) {
+      notes.push(
+        `Synthesized artifact ${synthesis} differs from the judge winner ${winner}; the judge winner is unchanged.`
+      );
+    }
+    if (delivery !== null && delivery !== winner) {
+      notes.push(
+        `Delivered artifact ${delivery} differs from the judge winner ${winner}; the judge winner is unchanged.`
+      );
+    }
+  }
+
+  return notes.map(truncateLine);
+}
+
+/**
+ * Project one judge-operations record into the cockpit presentation view.
+ *
+ * Pure and deterministic: the same record always renders the same view, and no
+ * field is derived from anything other than the record itself.
+ */
+export function buildJudgeOperationsView(
+  facts: JudgeOperationsProjectionFacts
+): JudgeOperationsView {
+  const state = deriveState(facts);
+  return {
+    viewVersion: JUDGE_OPERATIONS_VIEW_VERSION,
+    contractVersion: facts.contractVersion,
+    runId: facts.runId,
+    state,
+    headline: truncateLine(deriveHeadline(facts, state)),
+    rows: buildRows(facts),
+    notes: buildNotes(facts, state),
+    // Judging that does not apply is a complete state, never a degraded one.
+    degraded: facts.applies && facts.evidenceState !== 'complete',
+  };
+}
+
+/** Honest presentation for historical transports that predate JOC-01. */
+export function buildUnavailableJudgeOperationsView(runId: string): JudgeOperationsView {
+  return buildJudgeOperationsView({
+    contractVersion: UNAVAILABLE,
+    runId,
+    applies: true,
+    notApplicableReason: null,
+    requestedJudges: null,
+    executedJudges: null,
+    phase: null,
+    status: 'unknown',
+    primaryVerdict: null,
+    matrix: null,
+    disagreements: null,
+    humanChecks: null,
+    criterionAssessments: null,
+    judgeWinner: null,
+    synthesis: null,
+    delivery: null,
+    evidenceState: 'historical',
+  });
+}