@poetic-ai/poetic 1.42.0

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

@@ -0,0 +1,303 @@
+/**
+ * Read Poetic's optional judge-operations projection as untrusted process output.
+ *
+ * The projection (JOC-01) is canonical: Poetic already decided the verdict, the
+ * winner, Matrix escalation, synthesis, and delivery. This module only validates
+ * the payload and renames its fields into the shape the pure cockpit presentation
+ * (JOC-02) reads. It holds the same boundary the rest of the plugin holds:
+ *
+ *   - No recomputation. No score, verdict, winner, confidence, Matrix decision,
+ *     or terminal state is derived, re-ranked, or defaulted here.
+ *   - Absent evidence stays absent. A projection field Poetic reported as
+ *     `unavailable` becomes `null`, which the presentation renders as an explicit
+ *     `unavailable`; a published empty list stays an empty list ("none").
+ *   - A missing, foreign-version, or mismatched payload yields `null`, which is
+ *     honest absence. Records written before this field existed are unaffected.
+ *   - The immutable judge winner stays separate from the synthesized and
+ *     delivered artifact identity; the two are never merged or reconciled.
+ */
+
+import type {
+  JudgeArtifactIdentity,
+  JudgeCriterionAssessmentFacts,
+  JudgeEvidenceState,
+  JudgeMatrixFacts,
+  JudgeOperationsProjectionFacts,
+  JudgeOperationsStatus,
+  JudgePrimaryVerdictFacts,
+  JudgeVerdictOutcome,
+  MatrixEscalationStatus,
+} from './judge-operations-view.js';
+
+/** Projection contract major version this plugin understands. */
+const SUPPORTED_PROJECTION_MAJOR = '1';
+
+type JsonRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is JsonRecord {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function optionalString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+/**
+ * Unwrap one `JudgeEvidence<T>` wrapper. `available` yields the recorded value;
+ * `unavailable`, a malformed wrapper, and an absent wrapper all yield null, so a
+ * missing field is never distinguishable from a fabricated one.
+ */
+function evidenceValue(value: unknown): unknown {
+  if (!isRecord(value)) return null;
+  return value.state === 'available' ? (value.value ?? null) : null;
+}
+
+function evidenceString(value: unknown): string | null {
+  return optionalString(evidenceValue(value));
+}
+
+function evidenceNumber(value: unknown): number | null {
+  const unwrapped = evidenceValue(value);
+  return typeof unwrapped === 'number' && Number.isFinite(unwrapped) ? unwrapped : null;
+}
+
+function evidenceUnavailable(value: unknown): boolean {
+  return evidenceValue(value) === null;
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.flatMap((entry) => {
+        const text = optionalString(entry);
+        return text ? [text] : [];
+      })
+    : [];
+}
+
+/** A published list of judge names, or null when Poetic published no list. */
+function evidenceStringList(value: unknown): string[] | null {
+  const unwrapped = evidenceValue(value);
+  return Array.isArray(unwrapped) ? stringList(unwrapped) : null;
+}
+
+/**
+ * Map Poetic's judge lifecycle phase onto the cockpit's status vocabulary.
+ *
+ * The presentation vocabulary has no "did not run" member, so a recorded
+ * deliberate skip (`not_requested`) reports `unknown` and keeps Poetic's own
+ * phase on the status row. Reporting it as `not_started` would render a run that
+ * will never be judged as still in progress.
+ */
+function viewStatus(phase: string | null): JudgeOperationsStatus {
+  switch (phase) {
+    case 'judging':
+    case 'escalated':
+      return 'running';
+    case 'complete':
+      return 'complete';
+    default:
+      return 'unknown';
+  }
+}
+
+/** Copy Poetic's outcome classification; anything else is reported unknown. */
+function verdictOutcome(status: string | null): JudgeVerdictOutcome {
+  if (status === 'decisive') return 'decisive';
+  if (status === 'inconclusive') return 'inconclusive';
+  return 'unknown';
+}
+
+function matrixStatus(state: unknown): MatrixEscalationStatus {
+  if (state === 'escalated') return 'escalated';
+  if (state === 'not_escalated') return 'not_escalated';
+  return 'unknown';
+}
+
+/** Recorded judge stack: a single requested label is still a published list. */
+function requestedJudges(stack: JsonRecord | null): string[] | null {
+  const requested = evidenceString(stack?.requested);
+  return requested === null ? null : [requested];
+}
+
+function primaryVerdict(
+  verdict: JsonRecord | null,
+  status: string | null
+): JudgePrimaryVerdictFacts | null {
+  // These statuses mean Poetic recorded no verdict at all, so the whole block is
+  // reported unavailable rather than as a verdict with empty fields.
+  if (status === null || status === 'not_applicable' || status === 'not_run') return null;
+  if (status === 'unavailable' && verdict === null) return null;
+  return {
+    judge: evidenceString(verdict?.primaryJudge),
+    outcome: verdictOutcome(status),
+    confidence: evidenceNumber(verdict?.confidence),
+  };
+}
+
+function matrixFacts(matrix: JsonRecord | null): JudgeMatrixFacts | null {
+  if (matrix === null) return null;
+  const status = matrixStatus(matrix.state);
+  if (status === 'unknown' && !Array.isArray(matrix.escalationReasons)) return null;
+  return { status, reasons: stringList(matrix.escalationReasons) };
+}
+
+/**
+ * Recorded profile disagreement evidence.
+ *
+ * `unanimous` is a published "none". A split or inconclusive profile decision
+ * reports the recorded per-profile winners verbatim; when Poetic recorded the
+ * decision but not the profiles, the evidence is unavailable rather than empty.
+ */
+function disagreements(matrix: JsonRecord | null): string[] | null {
+  if (matrix === null) return null;
+  const decision = matrix.profileDecision;
+  if (decision === 'unanimous') return [];
+  if (decision !== 'split' && decision !== 'inconclusive') return null;
+  const profiles = evidenceValue(matrix.profiles);
+  if (!isRecord(profiles)) return null;
+  return Object.entries(profiles).flatMap(([profile, winner]) => {
+    const recorded = optionalString(winner);
+    return recorded ? [`${profile}=${recorded}`] : [];
+  });
+}
+
+/**
+ * Recorded human checks, each labelled with the authority Poetic gave it. A
+ * blocking check must never render as advisory, and the cockpit renders one row.
+ */
+function humanChecks(matrix: JsonRecord | null): string[] | null {
+  if (matrix === null) return null;
+  const blocking = evidenceStringList(matrix.blockingHumanChecks);
+  const advisory = evidenceStringList(matrix.advisoryHumanChecks);
+  if (blocking === null && advisory === null) return null;
+  return [
+    ...(blocking ?? []).map((check) => `blocking: ${check}`),
+    ...(advisory ?? []).map((check) => `advisory: ${check}`),
+  ];
+}
+
+function criterionAssessments(criteria: unknown): JudgeCriterionAssessmentFacts[] | null {
+  const unwrapped = evidenceValue(criteria);
+  if (!Array.isArray(unwrapped)) return null;
+  return unwrapped.flatMap((entry) => {
+    if (!isRecord(entry)) return [];
+    const criterion = optionalString(entry.criterion);
+    const assessment = optionalString(entry.assessment);
+    if (!criterion || !assessment) return [];
+    return [{ criterion, assessment, evidenceProvenance: evidenceString(entry.provenance) }];
+  });
+}
+
+/**
+ * The immutable judge winner's variant identity.
+ *
+ * A judge-declared "no winner" and an unavailable winner both yield null: the
+ * cockpit renders the distinction from the verdict outcome, and BB never selects
+ * a winner of its own.
+ */
+function judgeWinner(winner: JsonRecord | null): string | null {
+  if (winner === null || winner.state !== 'selected') return null;
+  const identity = isRecord(winner.identity) ? winner.identity : null;
+  return evidenceString(identity?.variant);
+}
+
+/** Synthesized artifact identity, reported only when Poetic published a path. */
+function synthesisIdentity(artifacts: JsonRecord | null): JudgeArtifactIdentity | null {
+  const synthesis = evidenceValue(artifacts?.synthesis);
+  if (!isRecord(synthesis)) return null;
+  const id = evidenceString(synthesis.artifactPath) ?? evidenceString(synthesis.jsonPath);
+  return id === null ? null : { id, variantId: null };
+}
+
+/**
+ * Delivered artifact identity. The recorded variant id is preferred because it is
+ * the identity the cockpit compares against the judge winner when disclosing that
+ * delivery diverged; the judge winner itself is never changed by that comparison.
+ */
+function deliveryIdentity(artifacts: JsonRecord | null): JudgeArtifactIdentity | null {
+  const delivery = evidenceValue(artifacts?.delivery);
+  if (!isRecord(delivery)) return null;
+  const variantId = evidenceString(delivery.variantId);
+  const id = variantId ?? evidenceString(delivery.commit) ?? evidenceString(delivery.branch);
+  return id === null ? null : { id, variantId };
+}
+
+/**
+ * How complete the projected record is.
+ *
+ * A run that judges nothing by design is complete as-is. A record with no judge
+ * evidence at all is historical. Otherwise the record is partial when Poetic
+ * reported a degraded lifecycle, attached record caveats, or published no verdict
+ * outcome or winner. Per-criterion assessments are deliberately excluded: upstream
+ * does not record them yet, so their absence is not evidence of a partial record.
+ */
+function evidenceState(
+  projection: JsonRecord,
+  applies: boolean,
+  phase: string | null,
+  status: string | null
+): JudgeEvidenceState {
+  if (!applies) return 'complete';
+  if (status === 'unavailable' && phase === 'unavailable') return 'historical';
+  const verdict = isRecord(projection.verdict) ? projection.verdict : null;
+  const winner = isRecord(projection.winner) ? projection.winner : null;
+  const partial =
+    status === 'degraded' ||
+    status === 'unavailable' ||
+    stringList(projection.caveats).length > 0 ||
+    verdict === null ||
+    evidenceUnavailable(verdict.outcome) ||
+    winner === null ||
+    winner.state === 'unavailable';
+  return partial ? 'partial' : 'complete';
+}
+
+/**
+ * Validate and map one judge-operations projection payload.
+ *
+ * Returns null when the field is absent, carries an incompatible major version,
+ * or describes a different run. Absence is honest: records written before the
+ * projection existed simply have no judge-operations evidence to present.
+ */
+export function parseJudgeOperations(
+  value: unknown,
+  runId: string
+): JudgeOperationsProjectionFacts | null {
+  if (!isRecord(value)) return null;
+  const contractVersion = optionalString(value.version);
+  if (!contractVersion || contractVersion.split('.')[0] !== SUPPORTED_PROJECTION_MAJOR) return null;
+  if (optionalString(value.runId) !== runId) return null;
+  const applicability = optionalString(value.applicability);
+  if (applicability !== 'applicable' && applicability !== 'not_applicable') return null;
+
+  const applies = applicability === 'applicable';
+  const phase = optionalString(value.phase);
+  const status = optionalString(value.status);
+  const stack = isRecord(value.stack) ? value.stack : null;
+  const verdict = isRecord(value.verdict) ? value.verdict : null;
+  const matrix = isRecord(value.matrix) ? value.matrix : null;
+  const artifacts = isRecord(value.artifacts) ? value.artifacts : null;
+  const winner = isRecord(value.winner) ? value.winner : null;
+
+  return {
+    contractVersion,
+    runId,
+    applies,
+    notApplicableReason: applies ? null : optionalString(value.notApplicableReason),
+    requestedJudges: applies ? requestedJudges(stack) : null,
+    executedJudges: applies ? evidenceStringList(stack?.executed) : null,
+    phase,
+    status: applies ? viewStatus(phase) : 'unknown',
+    primaryVerdict: applies ? primaryVerdict(verdict, status) : null,
+    matrix: applies ? matrixFacts(matrix) : null,
+    disagreements: applies ? disagreements(matrix) : null,
+    humanChecks: applies ? humanChecks(matrix) : null,
+    criterionAssessments: applies ? criterionAssessments(value.criteria) : null,
+    judgeWinner: applies ? judgeWinner(winner) : null,
+    // Fusion still synthesizes and delivers, so artifact identity is reported for
+    // every run kind, including one that judges nothing.
+    synthesis: synthesisIdentity(artifacts),
+    delivery: deliveryIdentity(artifacts),
+    evidenceState: evidenceState(value, applies, phase, status),
+  };
+}

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

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { JUDGE_OPERATIONS_VIEW_VERSION } from './judge-operations-view.js';
+
+/**
+ * Rendered judge-operations cockpit for one run. Presentation only: every value is
+ * already-decided Poetic evidence or the explicit `unavailable` label the pure view
+ * emits, so this schema validates shape and never asserts a judge outcome.
+ *
+ * Kept in its own module, like `repository-schema.ts`, so the shape can be
+ * validated without loading the BB plugin SDK.
+ */
+export const judgeOperationsViewSchema = z
+  .object({
+    viewVersion: z.literal(JUDGE_OPERATIONS_VIEW_VERSION),
+    /** Version of the canonical projection contract this view rendered. */
+    contractVersion: z.string(),
+    runId: z.string(),
+    state: z.enum([
+      'not_applicable',
+      'escalated',
+      'decisive',
+      'inconclusive',
+      'in_progress',
+      'unavailable',
+    ]),
+    headline: z.string(),
+    rows: z
+      .array(z.object({ id: z.string(), label: z.string(), value: z.string() }).strict())
+      .readonly(),
+    notes: z.array(z.string()).readonly(),
+    degraded: z.boolean(),
+  })
+  .strict();