opencode-wait-a-minute 0.0.0-stage → 1.1.0-rc.8

package/src/persistence/transaction-log.js

@@ -0,0 +1,157 @@
+// transaction-log.js
+// Append-only journal of state mutations with durability guarantees.
+// Each entry is one line of canonical JSON, fsynced before returning.
+
+import { appendFile, open, mkdir, rename } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { dirname } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Canonical JSON (shared semantic with state-schema.js but kept local so this
+// file is usable independently — no cross-file coupling for the journal).
+// ---------------------------------------------------------------------------
+
+function canonical(v) {
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return "[" + v.map(canonical).join(",") + "]";
+  const keys = Object.keys(v).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonical(v[k])).join(",") + "}";
+}
+
+function entryHash(entry) {
+  const { hash, _corrupt, _rawLine, ...rest } = entry;
+  return createHash("sha256").update(canonical(rest)).digest("hex");
+}
+
+// ---------------------------------------------------------------------------
+// AppendLog
+// ---------------------------------------------------------------------------
+
+/**
+ * Append-only journal. Each append() is atomic (single write + fsync of the
+ * file descriptor). Reads return all entries from disk in append order.
+ *
+ * Recovery: caller replays entries from disk after a crash. The journal never
+ * overwrites prior entries; partial writes are detectable via per-entry hash.
+ */
+export class TransactionLog {
+  /**
+   * @param {string} path  absolute path to the journal file
+   * @param {object} [opts]
+   * @param {string} [opts.dir]  directory to ensure exists
+   */
+  constructor(path, opts = {}) {
+    this.path = path;
+    this.dir = opts.dir ?? dirname(path);
+    this._seq = 0;
+    this._ready = this._init();
+  }
+
+  async _init() {
+    await mkdir(this.dir, { recursive: true });
+  }
+
+  async append(op) {
+    await this._ready;
+    const entry = {
+      seq: ++this._seq,
+      ts: new Date().toISOString(),
+      ...op,
+    };
+    entry.hash = entryHash(entry);
+    const line = canonical(entry) + "\n";
+    // appendFile is atomic for small writes < PIPE_BUF; we also explicitly
+    // fsync via a handle so the kernel commits to disk before we return.
+    const fh = await open(this.path, "a");
+    try {
+      await fh.appendFile(line);
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    return entry;
+  }
+
+  /** Read all entries. Skips lines that fail to parse (corruption isolation). */
+  async readAll() {
+    await this._ready;
+    let raw = "";
+    try {
+      const fh = await open(this.path, "r");
+      try {
+        raw = await fh.readFile("utf8");
+      } finally {
+        await fh.close();
+      }
+    } catch (e) {
+      if (e.code === "ENOENT") return [];
+      throw e;
+    }
+    const out = [];
+    const lines = raw.split("\n");
+    for (const line of lines) {
+      if (!line) continue;
+      try {
+        const entry = JSON.parse(line);
+        // Per-entry hash check; treat mismatch as corruption but include line
+        // so caller can quarantine it explicitly if needed.
+        if (entry && entry.hash && entry.hash !== entryHash(entry)) {
+          out.push({ ...entry, _corrupt: true });
+        } else {
+          out.push(entry);
+        }
+      } catch {
+        out.push({ _corrupt: true, _rawLine: line });
+      }
+    }
+    return out;
+  }
+
+  /** Number of valid entries currently on disk. */
+  async size() {
+    const all = await this.readAll();
+    return all.filter((e) => !e._corrupt).length;
+  }
+
+  /** Truncate the journal. Used by GC after compaction. */
+  async truncate() {
+    await this._ready;
+    await rename(this.path, this.path + ".truncated-" + Date.now()).catch(() => {});
+    this._seq = 0;
+  }
+}
+
+/**
+ * Replay a list of journal entries, applying each to a state map.
+ * - Skips entries with _corrupt: true
+ * - Returns { applied, skipped, finalState }
+ *
+ * Each entry's payload is expected to be { type, taskId, data, op? } where
+ * op is "set" (default) or "del". Replay is idempotent by (seq).
+ */
+export function replay(entries, initialState = {}) {
+  const applied = [];
+  const skipped = [];
+  const state = { ...initialState };
+
+  for (const entry of entries) {
+    if (!entry || entry._corrupt) {
+      skipped.push(entry);
+      continue;
+    }
+    const { seq, type, taskId, data, op = "set" } = entry;
+    if (!type || !taskId) {
+      skipped.push(entry);
+      continue;
+    }
+    const key = `${type}:${taskId}`;
+    if (op === "del") {
+      delete state[key];
+    } else {
+      state[key] = data;
+    }
+    applied.push({ seq, key, op });
+  }
+
+  return { applied, skipped, finalState: state };
+}

package/src/policy/action-capabilities.js

@@ -0,0 +1,116 @@
+/**
+ * Action Capabilities — Structured classification of agent tool capabilities.
+ *
+ * Define cuatro niveles de capacidad, cada uno con un significado explícito
+ * respecto a mutación, autorización y fail-mode:
+ *
+ *   - SAFE     : read-only / efectos reversibles mínimos. Autónoma.
+ *   - GUARDED  : mutaciones bounded y reversibles. Autónoma si está dentro del scope.
+ *   - BLOCKED  : destructivo, irreversible o sensible. Requiere autorización explícita.
+ *   - UNKNOWN  : la herramienta no aparece en el catálogo. Fail-closed (treated as BLOCKED).
+ *
+ * Implementa: action-risk-envelope / C01 fail-closed.
+ *
+ * El uso de UNKNOWN permite que el evaluador aplique una política fail-closed
+ * ante herramientas no registradas: cualquier herramienta que no aparezca
+ * explícitamente en SAFE/GUARDED/BLOCKED se clasifica como UNKNOWN y, por
+ * política, se trata como BLOCKED para evitar que una herramienta nueva o
+ * mal nombrada ejecute mutaciones sin control.
+ */
+
+export const CAPABILITY_LEVELS = Object.freeze({
+  SAFE: "SAFE",
+  GUARDED: "GUARDED",
+  BLOCKED: "BLOCKED",
+  UNKNOWN: "UNKNOWN",
+});
+
+/**
+ * Mapa explícito de capacidades por nombre de herramienta.
+ * Cualquier herramienta que NO esté aquí se clasifica como UNKNOWN.
+ */
+export const ACTION_CAPABILITIES = Object.freeze({
+  // --- SAFE: read-only / sin efectos ---
+  read:        CAPABILITY_LEVELS.SAFE,
+  glob:        CAPABILITY_LEVELS.SAFE,
+  grep:        CAPABILITY_LEVELS.SAFE,
+  ls:          CAPABILITY_LEVELS.SAFE,
+  tool_search: CAPABILITY_LEVELS.SAFE,
+  webfetch:    CAPABILITY_LEVELS.SAFE,
+  fetch:       CAPABILITY_LEVELS.SAFE,
+
+  // --- GUARDED: mutaciones bounded ---
+  write:       CAPABILITY_LEVELS.GUARDED,
+  edit:        CAPABILITY_LEVELS.GUARDED,
+  apply_patch: CAPABILITY_LEVELS.GUARDED,
+  patch:       CAPABILITY_LEVELS.GUARDED,
+  todo_write:  CAPABILITY_LEVELS.GUARDED,
+  todowrite:   CAPABILITY_LEVELS.GUARDED,
+  bash:        CAPABILITY_LEVELS.GUARDED,
+  sh:          CAPABILITY_LEVELS.GUARDED,
+  pty_spawn:   CAPABILITY_LEVELS.GUARDED,
+  pty_write:   CAPABILITY_LEVELS.GUARDED,
+  task:        CAPABILITY_LEVELS.GUARDED, // delegation: GUARDED, not SAFE
+
+  // --- BLOCKED: destructivo / sensible ---
+  rm:          CAPABILITY_LEVELS.BLOCKED,
+  rmdir:       CAPABILITY_LEVELS.BLOCKED,
+  mv:          CAPABILITY_LEVELS.BLOCKED,
+  sudo:        CAPABILITY_LEVELS.BLOCKED,
+  chmod:       CAPABILITY_LEVELS.BLOCKED,
+  chown:       CAPABILITY_LEVELS.BLOCKED,
+  docker:      CAPABILITY_LEVELS.BLOCKED,
+  ssh:         CAPABILITY_LEVELS.BLOCKED,
+  scp:         CAPABILITY_LEVELS.BLOCKED,
+  rsync:       CAPABILITY_LEVELS.BLOCKED,
+  push:        CAPABILITY_LEVELS.BLOCKED,
+  force_push:  CAPABILITY_LEVELS.BLOCKED,
+});
+
+/**
+ * Resuelve la capacidad explícita de una herramienta por nombre exacto.
+ * No hace coincidencia por sub-string ni por prefijo — debe ser match exacto.
+ *
+ * Esto evita la colisión por sub-string: "bash-safe" no debe resolverse a "bash".
+ *
+ * @param {string} tool — nombre de la herramienta (case-insensitive).
+ * @returns {"SAFE"|"GUARDED"|"BLOCKED"|"UNKNOWN"}
+ */
+export function getCapability(tool) {
+  if (typeof tool !== "string" || tool.length === 0) {
+    return CAPABILITY_LEVELS.UNKNOWN;
+  }
+  const normalized = tool.toLowerCase();
+  const cap = ACTION_CAPABILITIES[normalized];
+  return cap || CAPABILITY_LEVELS.UNKNOWN;
+}
+
+/**
+ * Resuelve la capacidad effective aplicando fail-closed:
+ * UNKNOWN → BLOCKED.
+ *
+ * Esta es la función que el risk-engine debe usar cuando evalúa una acción.
+ * Si la herramienta no está en el catálogo, la acción queda BLOCKED.
+ *
+ * @param {string} tool
+ * @returns {"SAFE"|"GUARDED"|"BLOCKED"}
+ */
+export function getEffectiveCapability(tool) {
+  const cap = getCapability(tool);
+  if (cap === CAPABILITY_LEVELS.UNKNOWN) {
+    return CAPABILITY_LEVELS.BLOCKED;
+  }
+  return cap;
+}
+
+/**
+ * ¿Es una herramienta mutante? (GUARDED o BLOCKED).
+ * Incluye UNKNOWN como BLOCKED (fail-closed).
+ *
+ * @param {string} tool
+ * @returns {boolean}
+ */
+export function isMutatingCapability(tool) {
+  const eff = getEffectiveCapability(tool);
+  return eff === CAPABILITY_LEVELS.GUARDED || eff === CAPABILITY_LEVELS.BLOCKED;
+}

package/src/policy/action-policy.js

@@ -0,0 +1,4 @@
+export function evaluateActionPolicy(action, strategy) {
+  if (!strategy || strategy.status !== "ACTIVE") return { allowed: true };
+  return { allowed: true, covered: true, reason: "Strategy active" };
+}

package/src/policy/assessment-engine.js

@@ -0,0 +1,104 @@
+import { AssessmentResult } from "../context/assessment-rules.js";
+import { compareValues } from "../context/compare-values.js";
+import { compareObject } from "../context/compare-object.js";
+import { compareArray } from "../context/compare-array.js";
+
+export { AssessmentResult };
+
+/**
+ * Produce a structured assessment: { result, summary, findings }
+ * - result:    aggregate verdict (worst-case across findings)
+ * - summary:   counts of supported / contradicted / inconclusive / total
+ * - findings:  per-field comparison details with `path`, `expected`, `actual`, `reason`
+ */
+export function createAssessment(expected, actual) {
+  const findings = compareTopLevel(expected, actual);
+
+  const summary = summarize(findings);
+  const result = aggregate(summary);
+
+  return { result, summary, findings, expected, actual };
+}
+
+function compareTopLevel(expected, actual) {
+  if (expected === undefined || expected === null) {
+    return [
+      {
+        result: AssessmentResult.INCONCLUSIVE,
+        path: "",
+        expected,
+        actual,
+        reason: "no expected value provided",
+      },
+    ];
+  }
+
+  if (actual === undefined || actual === null) {
+    return [
+      {
+        result: AssessmentResult.CONTRADICTED,
+        path: "",
+        expected,
+        actual,
+        reason: "no actual value provided",
+      },
+    ];
+  }
+
+  if (Array.isArray(expected) && Array.isArray(actual)) {
+    return compareArray(expected, actual, "");
+  }
+
+  if (
+    typeof expected === "object" &&
+    typeof actual === "object" &&
+    !Array.isArray(actual)
+  ) {
+    return compareObject(expected, actual, "");
+  }
+
+  return compareValues(expected, actual, "");
+}
+
+function summarize(findings) {
+  const summary = { supported: 0, contradicted: 0, inconclusive: 0, total: 0 };
+  for (const f of findings) {
+    summary.total++;
+    if (f.result === AssessmentResult.SUPPORTED) summary.supported++;
+    else if (f.result === AssessmentResult.CONTRADICTED) summary.contradicted++;
+    else summary.inconclusive++;
+  }
+  return summary;
+}
+
+/**
+ * Aggregate verdict: a single CONTRADICTED makes the whole assessment CONTRADICTED;
+ * otherwise any INCONCLUSIVE downgrades SUPPORTED to INCONCLUSIVE.
+ */
+function aggregate(summary) {
+  if (summary.contradicted > 0) return AssessmentResult.CONTRADICTED;
+  if (summary.inconclusive > 0) return AssessmentResult.INCONCLUSIVE;
+  if (summary.supported > 0) return AssessmentResult.SUPPORTED;
+  return AssessmentResult.INCONCLUSIVE;
+}
+
+export function assessObservation(experiment, observation) {
+  const expectedObs = experiment.expectedObservation;
+  if (!expectedObs || typeof expectedObs !== "object") {
+    return {
+      result: AssessmentResult.INCONCLUSIVE,
+      summary: { supported: 0, contradicted: 0, inconclusive: 0, total: 0 },
+      findings: [],
+      reasoning: "No expectedObservation defined for this experiment.",
+      expected: expectedObs,
+      actual: observation,
+    };
+  }
+
+  const actual = observation?.actual || observation;
+  const target = expectedObs.expected && typeof expectedObs.expected === "object"
+    ? expectedObs.expected
+    : expectedObs;
+
+  return createAssessment(target, actual);
+}

package/src/policy/assumption-tracking.js

@@ -0,0 +1,66 @@
+let _assumptionCounter = 0;
+export function createAssumption(statement, source, impact = "unknown") {
+  _assumptionCounter++;
+  return {
+    id: `assumption-${Date.now().toString(36)}-${_assumptionCounter}`,
+    statement,
+    source,
+    impact, // "critical" | "material" | "minor" | "unknown"
+    validated: false,
+    invalidated: false,
+    createdAt: Date.now()
+  };
+}
+
+export function validateAssumption(assumption, evidence) {
+  const supporting = evidence.filter(e =>
+    e.requirementId === assumption.relatedTo && e.supports !== false
+  );
+
+  return {
+    assumptionId: assumption.id,
+    validated: supporting.length > 0,
+    supportingEvidence: supporting.length,
+    invalidated: assumption.invalidated
+  };
+}
+
+export function trackAssumptionBudget(assumptions, maxUnvalidated = 5) {
+  const unvalidated = assumptions.filter(a => !a.validated && !a.invalidated);
+  return {
+    withinBudget: unvalidated.length <= maxUnvalidated,
+    current: unvalidated.length,
+    max: maxUnvalidated,
+    overBudget: Math.max(0, unvalidated.length - maxUnvalidated)
+  };
+}
+
+export const DEFAULT_ASSUMPTION_BUDGET = {
+  maxUnvalidated: 5,
+  maxCritical: 2,
+  maxMaterial: 5
+};
+
+export function checkAssumptionBudget(assumptions, budget = DEFAULT_ASSUMPTION_BUDGET) {
+  const unvalidated = assumptions.filter(a => !a.validated && !a.invalidated);
+  const critical = unvalidated.filter(a => a.impact === "critical");
+  const material = unvalidated.filter(a => a.impact === "material");
+
+  const violations = [];
+
+  if (unvalidated.length > budget.maxUnvalidated) {
+    violations.push(`Too many unvalidated assumptions: ${unvalidated.length} > ${budget.maxUnvalidated}`);
+  }
+  if (critical.length > budget.maxCritical) {
+    violations.push(`Too many critical assumptions: ${critical.length} > ${budget.maxCritical}`);
+  }
+  if (material.length > budget.maxMaterial) {
+    violations.push(`Too many material assumptions: ${material.length} > ${budget.maxMaterial}`);
+  }
+
+  return {
+    valid: violations.length === 0,
+    violations,
+    counts: { unvalidated: unvalidated.length, critical: critical.length, material: material.length }
+  };
+}

package/src/policy/budget-enforcer.js

@@ -0,0 +1,7 @@
+export function enforceBudget(items, budget) {
+  let prunedItems = [...items];
+  if (budget.maxItems !== undefined) {
+    prunedItems = prunedItems.slice(0, budget.maxItems);
+  }
+  return prunedItems;
+}

package/src/policy/config-validator.js

@@ -0,0 +1,102 @@
+export function validateConfig(config, schema) {
+  const errors = [];
+
+  function validatePath(value, sub, path) {
+    if (sub.type === 'object' && sub.properties) {
+      if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        if (sub.required) errors.push(`${path}: expected object`);
+        return;
+      }
+      for (const key of Object.keys(sub.properties)) {
+        const childSchema = sub.properties[key];
+        validatePath(value[key], childSchema, path ? `${path}.${key}` : key);
+      }
+      // Reject extra keys if additionalProperties is explicitly false.
+      if (sub.additionalProperties === false) {
+        for (const key of Object.keys(value)) {
+          if (!(key in sub.properties)) {
+            errors.push(`${path ? path + '.' : ''}${key}: unexpected property`);
+          }
+        }
+      }
+      return;
+    }
+
+    const isPresent = value !== undefined;
+    if (sub.required && !isPresent) {
+      errors.push(`${path}: required`);
+      return;
+    }
+    if (!isPresent) return;
+
+    switch (sub.type) {
+      case 'string':
+        if (typeof value !== 'string') {
+          errors.push(`${path}: expected string`);
+        } else {
+          if (sub.minLength !== undefined && value.length < sub.minLength) {
+            errors.push(`${path}: shorter than minLength ${sub.minLength}`);
+          }
+          if (sub.maxLength !== undefined && value.length > sub.maxLength) {
+            errors.push(`${path}: longer than maxLength ${sub.maxLength}`);
+          }
+          if (sub.pattern !== undefined && !sub.pattern.test(value)) {
+            errors.push(`${path}: does not match pattern`);
+          }
+          if (sub.enum && !sub.enum.includes(value)) {
+            errors.push(`${path}: must be one of ${sub.enum.join(', ')}`);
+          }
+        }
+        break;
+      case 'number':
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+          errors.push(`${path}: expected number`);
+        } else {
+          if (sub.minimum !== undefined && value < sub.minimum) {
+            errors.push(`${path}: below minimum ${sub.minimum}`);
+          }
+          if (sub.maximum !== undefined && value > sub.maximum) {
+            errors.push(`${path}: above maximum ${sub.maximum}`);
+          }
+        }
+        break;
+      case 'integer': {
+        if (typeof value !== 'number' || !Number.isInteger(value)) {
+          errors.push(`${path}: expected integer`);
+        } else {
+          if (sub.minimum !== undefined && value < sub.minimum) {
+            errors.push(`${path}: below minimum ${sub.minimum}`);
+          }
+          if (sub.maximum !== undefined && value > sub.maximum) {
+            errors.push(`${path}: above maximum ${sub.maximum}`);
+          }
+        }
+        break;
+      }
+      case 'boolean':
+        if (typeof value !== 'boolean') errors.push(`${path}: expected boolean`);
+        break;
+      case 'array':
+        if (!Array.isArray(value)) {
+          errors.push(`${path}: expected array`);
+        } else {
+          if (sub.minItems !== undefined && value.length < sub.minItems) {
+            errors.push(`${path}: fewer than minItems ${sub.minItems}`);
+          }
+          if (sub.maxItems !== undefined && value.length > sub.maxItems) {
+            errors.push(`${path}: more than maxItems ${sub.maxItems}`);
+          }
+          if (sub.items) {
+            value.forEach((item, i) => validatePath(item, sub.items, `${path}[${i}]`));
+          }
+        }
+        break;
+      default:
+        // Unknown type — pass through (lenient).
+        break;
+    }
+  }
+
+  validatePath(config, schema, '');
+  return { valid: errors.length === 0, errors };
+}

package/src/policy/execution-assessment.js

@@ -0,0 +1,142 @@
+/**
+ * Observation assessment — compares expected vs actual observations.
+ * Returns: SUPPORTED | INCONCLUSIVE | CONTRADICTED
+ */
+
+export const AssessmentResult = {
+  SUPPORTED: "SUPPORTED",
+  INCONCLUSIVE: "INCONCLUSIVE",
+  CONTRADICTED: "CONTRADICTED",
+};
+
+function classifyComparison(expected, actual) {
+  if (expected === actual) {
+    return "SUPPORTED";
+  }
+
+  if (expected === undefined || expected === null || actual === undefined || actual === null) {
+    return "INCONCLUSIVE";
+  }
+
+  if (typeof expected === "boolean" && typeof actual === "boolean") {
+    return expected === actual ? "SUPPORTED" : "CONTRADICTED";
+  }
+
+  if (typeof expected === "number" && typeof actual === "number") {
+    if (expected === actual) return "SUPPORTED";
+    if (Math.abs(expected - actual) <= (Math.abs(expected) * 0.1 + 0.01)) return "SUPPORTED";
+    return "CONTRADICTED";
+  }
+
+  if (typeof expected === "string" && typeof actual === "string") {
+    if (expected === actual) return "SUPPORTED";
+    if (actual.includes(expected) || expected.includes(actual)) return "SUPPORTED";
+    if (actual === "pending" || actual === "unknown" || actual === "not applicable") {
+      return "INCONCLUSIVE";
+    }
+    return "CONTRADICTED";
+  }
+
+  if (Array.isArray(expected) && Array.isArray(actual)) {
+    if (expected.length === 0 && actual.length === 0) return "SUPPORTED";
+    if (expected.length === 0) return "INCONCLUSIVE";
+    const allPresent = expected.every((e) => actual.includes(e));
+    const anyPresent = expected.some((e) => actual.includes(e));
+    if (allPresent) return "SUPPORTED";
+    if (anyPresent) return "INCONCLUSIVE";
+    return "CONTRADICTED";
+  }
+
+  if (typeof expected === "object" && typeof actual === "object" && expected !== null && actual !== null) {
+    return "INCONCLUSIVE";
+  }
+
+  if (actual === "pending" || actual === "unknown" || actual === "not applicable") {
+    return "INCONCLUSIVE";
+  }
+
+  return "CONTRADICTED";
+}
+
+export function createAssessment(expected, actual) {
+  const comparisons = [];
+  let supported = 0;
+  let contradicted = 0;
+  let inconclusive = 0;
+
+  const expectedKeys = Object.keys(expected);
+  const actualKeys = Object.keys(actual || {});
+
+  for (const key of expectedKeys) {
+    const expectedValue = expected[key];
+    const actualValue = actualKeys.includes(key) ? actual[key] : undefined;
+    const status = classifyComparison(expectedValue, actualValue);
+
+    comparisons.push({
+      field: key,
+      expected: expectedValue,
+      actual: actualValue,
+      status,
+    });
+
+    if (status === "SUPPORTED") supported++;
+    else if (status === "CONTRADICTED") contradicted++;
+    else inconclusive++;
+  }
+
+  const missingFields = expectedKeys.filter((k) => !actualKeys.includes(k));
+
+  // Missing fields count as contradicted
+  for (const field of missingFields) {
+    comparisons.push({
+      field,
+      expected: expected[field],
+      actual: undefined,
+      status: "CONTRADICTED",
+    });
+    contradicted++;
+  }
+
+  let result;
+  if (contradicted > 0) {
+    result = "CONTRADICTED";
+  } else if (inconclusive > 0 || (supported === 0 && expectedKeys.length > 0)) {
+    result = "INCONCLUSIVE";
+  } else {
+    result = "SUPPORTED";
+  }
+
+  const reasoning = generateReasoning(result, comparisons, missingFields);
+
+  return {
+    result,
+    reasoning,
+    comparisons,
+    summary: { supported, contradicted, inconclusive, total: expectedKeys.length },
+    expected,
+    actual,
+  };
+}
+
+function generateReasoning(result, comparisons, missingFields) {
+  const parts = [];
+
+  if (result === "SUPPORTED") {
+    parts.push(`All ${comparisons.length} expected fields match observations.`);
+  } else if (result === "CONTRADICTED") {
+    const conflicts = comparisons.filter((c) => c.status === "CONTRADICTED");
+    parts.push(
+      `${conflicts.length} of ${comparisons.length} expected fields conflict with observations: ${conflicts.map((c) => c.field).join(", ")}.`
+    );
+  } else {
+    if (missingFields.length > 0) {
+      parts.push(`Missing data for: ${missingFields.join(", ")}. `);
+    }
+    const unclear = comparisons.filter((c) => c.status === "INCONCLUSIVE");
+    parts.push(
+      `${unclear.length} of ${comparisons.length} fields are inconclusive: ${unclear.map((c) => c.field).join(", ")}.`
+    );
+  }
+
+  return parts.join(" ");
+}