principles-disciple 1.8.0 → 1.8.2

package/src/core/nocturnal-arbiter.ts

@@ -0,0 +1,706 @@
+/**
+ * Nocturnal Arbiter — Deterministic Validation of Reflection Artifacts
+ * ===================================================================
+ *
+ * PURPOSE: Validate that a reflection artifact passes all deterministic checks
+ * before being approved for persistence. This module is PURE FUNCTIONS —
+ * no side effects, no file I/O.
+ *
+ * VALIDATION RULES:
+ * 1. JSON is parseable and has required fields
+ * 2. principleId matches the target principle
+ * 3. sessionId matches the source snapshot
+ * 4. All required string fields are non-empty
+ * 5. No fields contain placeholder or dummy values
+ * 6. artifactId is a valid unique identifier
+ * 7. No raw/private content in any text field
+ *
+ * DESIGN CONSTRAINTS:
+ * - Pure functions only — no I/O, no side effects
+ * - Deterministic — same input always produces same output
+ * - Fail closed — invalid artifacts are rejected, never sanitized
+ * - No LLM involvement — all checks are algorithmic
+ */
+
+import type { NocturnalSessionSnapshot } from './nocturnal-trajectory-extractor.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A raw reflection artifact as generated by the reflector.
+ * This is the raw output before arbiter validation.
+ */
+export interface RawReflectionArtifact {
+  artifactId?: unknown;
+  sessionId?: unknown;
+  principleId?: unknown;
+  sourceSnapshotRef?: unknown;
+  badDecision?: unknown;
+  betterDecision?: unknown;
+  rationale?: unknown;
+  createdAt?: unknown;
+  thinkingModelDelta?: unknown;
+  planningRatioGain?: unknown;
+  invalid?: unknown;
+  reason?: unknown;
+}
+
+/**
+ * A validated and approved reflection artifact.
+ * This is the output after arbiter validation passes.
+ */
+export interface NocturnalArtifact {
+  artifactId: string;
+  sessionId: string;
+  principleId: string;
+  sourceSnapshotRef: string;
+  badDecision: string;
+  betterDecision: string;
+  rationale: string;
+  createdAt: string;
+  /** Design-alignment metric: delta in thinking model activation (-1 to 1) */
+  thinkingModelDelta?: number;
+  /** Design-alignment metric: gain in planning ratio (-1 to 1) */
+  planningRatioGain?: number;
+}
+
+/**
+ * Validation failure reason.
+ */
+export interface ArbiterFailure {
+  reason: string;
+  field?: string;
+}
+
+/**
+ * Result of arbiter validation.
+ */
+export interface ArbiterResult {
+  /** Whether the artifact passed validation */
+  passed: boolean;
+  /** The validated artifact (if passed) */
+  artifact?: NocturnalArtifact;
+  /** The raw input (if failed) */
+  rawInput?: RawReflectionArtifact;
+  /** Failure reasons (if failed) */
+  failures: ArbiterFailure[];
+}
+
+// ---------------------------------------------------------------------------
+// Validation Helpers
+// ---------------------------------------------------------------------------
+
+function isNonEmptyString(val: unknown): val is string {
+  return typeof val === 'string' && val.trim().length > 0;
+}
+
+function isValidUUID(val: string): boolean {
+  // Simple UUID v4 pattern check
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(val);
+}
+
+function isISO8601(val: string): boolean {
+  // ISO 8601 timestamp check
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/.test(val);
+}
+
+/**
+ * Check if a string contains placeholder/dummy values.
+ */
+function containsPlaceholder(val: string): boolean {
+  const placeholders = [
+    '<placeholder>',
+    '<uuid>',
+    '<session-id>',
+    '<principle-id>',
+    '<reason>',
+    '<action>',
+    'undefined',
+    'null',
+    'n/a',
+    'tbd',
+    'todo',
+    'fixme',
+  ];
+  const lower = val.toLowerCase();
+  return placeholders.some((p) => lower === p || lower.startsWith(p + ' '));
+}
+
+/**
+ * Check if a string contains raw/private content patterns.
+ * This is a heuristic check — not foolproof.
+ */
+function containsRawContent(val: string): boolean {
+  // Detect file paths with actual code (not just path shapes)
+  const rawPatterns = [
+    /function\s+\w+\s*\(/,           // function definitions
+    /class\s+\w+/,                   // class definitions
+    /const\s+\w+\s*=/,              // variable declarations
+    /import\s+.*from/,              // import statements
+    /export\s+(default\s+)?/,        // export statements
+    /api_key|secret|password|token/, // credential patterns (case insensitive)
+  ];
+  return rawPatterns.some((p) => p.test(val));
+}
+
+// ---------------------------------------------------------------------------
+// Trinity Intermediate Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validation result for a Trinity stage output.
+ */
+export interface TrinityStageValidationResult {
+  valid: boolean;
+  failures: string[];
+}
+
+/**
+ * Validate a Dreamer output contract.
+ * Ensures the output is well-formed before passing to Philosopher.
+ */
+export function validateDreamerOutput(output: unknown): TrinityStageValidationResult {
+  const failures: string[] = [];
+
+  if (output === null || output === undefined || typeof output !== 'object') {
+    return { valid: false, failures: ['Dreamer output must be a JSON object'] };
+  }
+
+  const obj = output as Record<string, unknown>;
+
+  // Check valid flag
+  if (obj.valid !== true) {
+    if (typeof obj.reason === 'string' && obj.reason.length > 0) {
+      failures.push(`Dreamer marked invalid: ${obj.reason}`);
+    } else {
+      failures.push('Dreamer output marked invalid with no reason');
+    }
+  }
+
+  // Check candidates array
+  if (!Array.isArray(obj.candidates)) {
+    failures.push('Dreamer output must have a candidates array');
+  } else {
+    // Validate each candidate
+    obj.candidates.forEach((candidate: unknown, idx: number) => {
+      if (candidate === null || candidate === undefined || typeof candidate !== 'object') {
+        failures.push(`Dreamer candidate at index ${idx} is not an object`);
+        return;
+      }
+      const c = candidate as Record<string, unknown>;
+
+      if (typeof c.candidateIndex !== 'number') {
+        failures.push(`Dreamer candidate ${idx} missing candidateIndex`);
+      }
+      if (typeof c.badDecision !== 'string' || c.badDecision.trim().length === 0) {
+        failures.push(`Dreamer candidate ${idx} missing non-empty badDecision`);
+      }
+      if (typeof c.betterDecision !== 'string' || c.betterDecision.trim().length === 0) {
+        failures.push(`Dreamer candidate ${idx} missing non-empty betterDecision`);
+      }
+      if (typeof c.rationale !== 'string' || c.rationale.trim().length === 0) {
+        failures.push(`Dreamer candidate ${idx} missing non-empty rationale`);
+      }
+      if (typeof c.confidence !== 'number' || c.confidence < 0 || c.confidence > 1) {
+        failures.push(`Dreamer candidate ${idx} has invalid confidence (must be 0-1)`);
+      }
+
+      // badDecision and betterDecision should not be identical
+      if (
+        typeof c.badDecision === 'string' &&
+        typeof c.betterDecision === 'string' &&
+        c.badDecision.trim() === c.betterDecision.trim()
+      ) {
+        failures.push(`Dreamer candidate ${idx}: badDecision and betterDecision are identical`);
+      }
+    });
+
+    // Check for duplicate candidateIndices
+    const indices = (obj.candidates as Array<Record<string, unknown>>)
+      .map((c) => c.candidateIndex)
+      .filter((i) => typeof i === 'number');
+    const uniqueIndices = new Set(indices);
+    if (indices.length !== uniqueIndices.size) {
+      failures.push('Dreamer candidates have duplicate candidateIndex values');
+    }
+  }
+
+  // Check generatedAt
+  if (typeof obj.generatedAt !== 'string' || !isISO8601(obj.generatedAt)) {
+    failures.push('Dreamer output missing valid ISO 8601 generatedAt');
+  }
+
+  return { valid: failures.length === 0, failures };
+}
+
+/**
+ * Validate a Philosopher output contract.
+ * Ensures the output is well-formed before passing to Scribe.
+ */
+export function validatePhilosopherOutput(output: unknown): TrinityStageValidationResult {
+  const failures: string[] = [];
+
+  if (output === null || output === undefined || typeof output !== 'object') {
+    return { valid: false, failures: ['Philosopher output must be a JSON object'] };
+  }
+
+  const obj = output as Record<string, unknown>;
+
+  // Check valid flag
+  if (obj.valid !== true) {
+    if (typeof obj.reason === 'string' && obj.reason.length > 0) {
+      failures.push(`Philosopher marked invalid: ${obj.reason}`);
+    } else {
+      failures.push('Philosopher output marked invalid with no reason');
+    }
+  }
+
+  // Check judgments array
+  if (!Array.isArray(obj.judgments)) {
+    failures.push('Philosopher output must have a judgments array');
+  } else {
+    // Validate each judgment
+    obj.judgments.forEach((judgment: unknown, idx: number) => {
+      if (judgment === null || judgment === undefined || typeof judgment !== 'object') {
+        failures.push(`Philosopher judgment at index ${idx} is not an object`);
+        return;
+      }
+      const j = judgment as Record<string, unknown>;
+
+      if (typeof j.candidateIndex !== 'number') {
+        failures.push(`Philosopher judgment ${idx} missing candidateIndex`);
+      }
+      if (typeof j.critique !== 'string' || j.critique.trim().length === 0) {
+        failures.push(`Philosopher judgment ${idx} missing non-empty critique`);
+      }
+      if (typeof j.principleAligned !== 'boolean') {
+        failures.push(`Philosopher judgment ${idx} missing principleAligned boolean`);
+      }
+      if (typeof j.score !== 'number' || j.score < 0 || j.score > 1) {
+        failures.push(`Philosopher judgment ${idx} has invalid score (must be 0-1)`);
+      }
+      if (typeof j.rank !== 'number' || j.rank < 1) {
+        failures.push(`Philosopher judgment ${idx} has invalid rank (must be >= 1)`);
+      }
+    });
+
+    // Check ranks are unique and sequential (1, 2, 3...)
+    const ranks = (obj.judgments as Array<Record<string, unknown>>)
+      .map((j) => j.rank)
+      .filter((r) => typeof r === 'number')
+      .sort((a, b) => a - b);
+    for (let i = 0; i < ranks.length; i++) {
+      if (ranks[i] !== i + 1) {
+        failures.push('Philosopher judgments must have sequential ranks starting from 1');
+        break;
+      }
+    }
+  }
+
+  // Check overallAssessment
+  if (typeof obj.overallAssessment !== 'string' || obj.overallAssessment.trim().length === 0) {
+    failures.push('Philosopher output missing non-empty overallAssessment');
+  }
+
+  // Check generatedAt
+  if (typeof obj.generatedAt !== 'string' || !isISO8601(obj.generatedAt)) {
+    failures.push('Philosopher output missing valid ISO 8601 generatedAt');
+  }
+
+  return { valid: failures.length === 0, failures };
+}
+
+/**
+ * Validate a TrinityDraftArtifact contract.
+ * This is the final artifact before arbiter approval.
+ */
+export function validateTrinityDraft(draft: unknown): TrinityStageValidationResult {
+  const failures: string[] = [];
+
+  if (draft === null || draft === undefined || typeof draft !== 'object') {
+    return { valid: false, failures: ['Trinity draft must be a JSON object'] };
+  }
+
+  const obj = draft as Record<string, unknown>;
+
+  // Required fields
+  if (typeof obj.selectedCandidateIndex !== 'number') {
+    failures.push('Trinity draft missing selectedCandidateIndex');
+  }
+  if (typeof obj.badDecision !== 'string' || obj.badDecision.trim().length === 0) {
+    failures.push('Trinity draft missing non-empty badDecision');
+  }
+  if (typeof obj.betterDecision !== 'string' || obj.betterDecision.trim().length === 0) {
+    failures.push('Trinity draft missing non-empty betterDecision');
+  }
+  if (typeof obj.rationale !== 'string' || obj.rationale.trim().length < 20) {
+    failures.push('Trinity draft rationale must be at least 20 characters');
+  }
+  if (typeof obj.sessionId !== 'string' || obj.sessionId.trim().length === 0) {
+    failures.push('Trinity draft missing non-empty sessionId');
+  }
+  if (typeof obj.principleId !== 'string' || obj.principleId.trim().length === 0) {
+    failures.push('Trinity draft missing non-empty principleId');
+  }
+  if (typeof obj.sourceSnapshotRef !== 'string') {
+    failures.push('Trinity draft missing sourceSnapshotRef');
+  }
+
+  // Semantic validation
+  if (
+    typeof obj.badDecision === 'string' &&
+    typeof obj.betterDecision === 'string' &&
+    obj.badDecision.trim() === obj.betterDecision.trim()
+  ) {
+    failures.push('Trinity draft badDecision and betterDecision are identical');
+  }
+
+  // Validate telemetry
+  if (typeof obj.telemetry === 'object' && obj.telemetry !== null) {
+    const t = obj.telemetry as Record<string, unknown>;
+    if (t.chainMode !== 'trinity' && t.chainMode !== 'single-reflector') {
+      failures.push('Trinity draft telemetry must have valid chainMode');
+    }
+    if (typeof t.dreamerPassed !== 'boolean') {
+      failures.push('Trinity draft telemetry missing dreamerPassed boolean');
+    }
+    if (typeof t.philosopherPassed !== 'boolean') {
+      failures.push('Trinity draft telemetry missing philosopherPassed boolean');
+    }
+    if (typeof t.scribePassed !== 'boolean') {
+      failures.push('Trinity draft telemetry missing scribePassed boolean');
+    }
+  } else {
+    failures.push('Trinity draft missing telemetry object');
+  }
+
+  return { valid: failures.length === 0, failures };
+}
+
+/**
+ * Parse and validate a Dreamer output from JSON string.
+ */
+export function parseAndValidateDreamerOutput(jsonString: string): TrinityStageValidationResult {
+  try {
+    const parsed = JSON.parse(jsonString);
+    return validateDreamerOutput(parsed);
+  } catch (err) {
+    return {
+      valid: false,
+      failures: [`Failed to parse Dreamer output JSON: ${err instanceof Error ? err.message : String(err)}`],
+    };
+  }
+}
+
+/**
+ * Parse and validate a Philosopher output from JSON string.
+ */
+export function parseAndValidatePhilosopherOutput(jsonString: string): TrinityStageValidationResult {
+  try {
+    const parsed = JSON.parse(jsonString);
+    return validatePhilosopherOutput(parsed);
+  } catch (err) {
+    return {
+      valid: false,
+      failures: [`Failed to parse Philosopher output JSON: ${err instanceof Error ? err.message : String(err)}`],
+    };
+  }
+}
+
+/**
+ * Parse and validate a Trinity draft artifact from JSON string.
+ */
+export function parseAndValidateTrinityDraft(jsonString: string): TrinityStageValidationResult {
+  try {
+    const parsed = JSON.parse(jsonString);
+    return validateTrinityDraft(parsed);
+  } catch (err) {
+    return {
+      valid: false,
+      failures: [`Failed to parse Trinity draft JSON: ${err instanceof Error ? err.message : String(err)}`],
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core Arbiter
+// ---------------------------------------------------------------------------
+
+export interface ArbiterOptions {
+  /**
+   * Expected principle ID (from target selection).
+   * If provided, the artifact's principleId must match this.
+   */
+  expectedPrincipleId?: string;
+
+  /**
+   * Expected session ID (from snapshot).
+   * If provided, the artifact's sessionId must match this.
+   */
+  expectedSessionId?: string;
+
+  /**
+   * Minimum quality thresholds for reflection metrics.
+   * If provided, artifacts failing these thresholds are rejected.
+   */
+  qualityThresholds?: {
+    /**
+     * Minimum thinkingModelDelta (delta in thinking model activation).
+     * Must be > 0 for artifact to pass (cognitive improvement required).
+     * Default: undefined (no threshold — only range check [-1, 1])
+     */
+    thinkingModelDeltaMin?: number;
+    /**
+     * Minimum planningRatioGain.
+     * Must be >= -0.5 for artifact to pass (no catastrophic planning regression).
+     * Default: undefined (no threshold — only range check [-1, 1])
+     */
+    planningRatioGainMin?: number;
+  };
+}
+
+/**
+ * Validate a raw reflection artifact against all arbiter rules.
+ *
+ * @param raw - The raw artifact JSON (already parsed)
+ * @param options - Expected values for cross-validation
+ * @returns ArbiterResult with passed/failed status and details
+ */
+export function validateArtifact(
+  raw: unknown,
+  options: ArbiterOptions = {}
+): ArbiterResult {
+  const failures: ArbiterFailure[] = [];
+
+  // Rule 1: Must be an object
+  if (raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw)) {
+    return {
+      passed: false,
+      rawInput: raw as RawReflectionArtifact,
+      failures: [{ reason: 'Artifact must be a JSON object' }],
+    };
+  }
+
+  const obj = raw as Record<string, unknown>;
+
+  // Rule 2: Check for invalid flag (reflector said it couldn't generate)
+  if (obj.invalid === true || obj.invalid === 'true') {
+    return {
+      passed: false,
+      rawInput: obj as RawReflectionArtifact,
+      failures: [{ reason: `Reflector marked artifact as invalid: ${String(obj.reason ?? 'no reason provided')}` }],
+    };
+  }
+
+  // Rule 3: Required string fields must be present and non-empty
+  const requiredFields: Array<{ key: keyof RawReflectionArtifact; label: string }> = [
+    { key: 'artifactId', label: 'artifactId' },
+    { key: 'sessionId', label: 'sessionId' },
+    { key: 'principleId', label: 'principleId' },
+    { key: 'badDecision', label: 'badDecision' },
+    { key: 'betterDecision', label: 'betterDecision' },
+    { key: 'rationale', label: 'rationale' },
+    { key: 'createdAt', label: 'createdAt' },
+  ];
+
+  for (const field of requiredFields) {
+    const val = obj[field.key];
+    if (!isNonEmptyString(val)) {
+      failures.push({ reason: `Field '${field.label}' is missing or empty`, field: field.label });
+    } else {
+      // Additional checks for string fields
+      if (field.label === 'artifactId' && !isValidUUID(String(val))) {
+        failures.push({ reason: `Field '${field.label}' must be a valid UUID`, field: field.label });
+      }
+      if (field.label === 'createdAt' && !isISO8601(String(val))) {
+        failures.push({ reason: `Field '${field.label}' must be a valid ISO 8601 timestamp`, field: field.label });
+      }
+    }
+  }
+
+  // Rule 4: Cross-validate principleId
+  if (options.expectedPrincipleId !== undefined) {
+    const principleId = obj.principleId;
+    if (!isNonEmptyString(principleId)) {
+      failures.push({ reason: 'principleId is required but missing', field: 'principleId' });
+    } else if (String(principleId) !== options.expectedPrincipleId) {
+      failures.push({
+        reason: `principleId mismatch: expected '${options.expectedPrincipleId}', got '${String(principleId)}'`,
+        field: 'principleId',
+      });
+    }
+  }
+
+  // Rule 5: Cross-validate sessionId
+  if (options.expectedSessionId !== undefined) {
+    const sessionId = obj.sessionId;
+    if (!isNonEmptyString(sessionId)) {
+      failures.push({ reason: 'sessionId is required but missing', field: 'sessionId' });
+    } else if (String(sessionId) !== options.expectedSessionId) {
+      failures.push({
+        reason: `sessionId mismatch: expected '${options.expectedSessionId}', got '${String(sessionId)}'`,
+        field: 'sessionId',
+      });
+    }
+  }
+
+  // Rule 6: Check for placeholder values in text fields
+  const textFields: Array<keyof RawReflectionArtifact> = [
+    'badDecision',
+    'betterDecision',
+    'rationale',
+  ];
+  for (const field of textFields) {
+    const val = obj[field];
+    if (isNonEmptyString(val)) {
+      const strVal = String(val);
+      if (containsPlaceholder(strVal)) {
+        failures.push({ reason: `Field '${String(field)}' contains a placeholder value`, field: String(field) });
+      }
+      if (containsRawContent(strVal)) {
+        failures.push({
+          reason: `Field '${String(field)}' may contain raw/private content — not allowed in nocturnal artifacts`,
+          field: String(field),
+        });
+      }
+    }
+  }
+
+  // Rule 7: Check sourceSnapshotRef if present
+  const sourceSnapshotRef = obj.sourceSnapshotRef;
+  if (sourceSnapshotRef !== undefined && !isNonEmptyString(sourceSnapshotRef)) {
+    failures.push({ reason: 'Field "sourceSnapshotRef" must be a non-empty string if present', field: 'sourceSnapshotRef' });
+  }
+
+  // Rule 8: badDecision should not be identical to betterDecision
+  const badDecision = obj.badDecision;
+  const betterDecision = obj.betterDecision;
+  if (isNonEmptyString(badDecision) && isNonEmptyString(betterDecision)) {
+    if (String(badDecision).trim() === String(betterDecision).trim()) {
+      failures.push({
+        reason: 'badDecision and betterDecision cannot be identical',
+        field: 'betterDecision',
+      });
+    }
+  }
+
+  // Rule 9: Rationale should not be too short (needs explanation)
+  const rationale = obj.rationale;
+  if (isNonEmptyString(rationale) && String(rationale).trim().length < 20) {
+    failures.push({
+      reason: 'rationale is too short — must provide meaningful explanation',
+      field: 'rationale',
+    });
+  }
+
+  // Rule 10: Validate optional reflection quality metrics (if present)
+  const thinkingModelDelta = obj.thinkingModelDelta;
+  if (thinkingModelDelta !== undefined && typeof thinkingModelDelta !== 'number') {
+    failures.push({
+      reason: 'thinkingModelDelta must be a number if present',
+      field: 'thinkingModelDelta',
+    });
+  } else if (typeof thinkingModelDelta === 'number' && (thinkingModelDelta < -1 || thinkingModelDelta > 1)) {
+    failures.push({
+      reason: 'thinkingModelDelta must be between -1 and 1',
+      field: 'thinkingModelDelta',
+    });
+  }
+
+  const planningRatioGain = obj.planningRatioGain;
+  if (planningRatioGain !== undefined && typeof planningRatioGain !== 'number') {
+    failures.push({
+      reason: 'planningRatioGain must be a number if present',
+      field: 'planningRatioGain',
+    });
+  } else if (typeof planningRatioGain === 'number' && (planningRatioGain < -1 || planningRatioGain > 1)) {
+    failures.push({
+      reason: 'planningRatioGain must be between -1 and 1',
+      field: 'planningRatioGain',
+    });
+  }
+
+  // Rule 11: Quality threshold gate — reject low-signal artifacts
+  // A reflection artifact must show positive cognitive improvement (thinkingModelDelta > 0).
+  // planningRatioGain must not show catastrophic regression (< -0.5).
+  if (
+    options.qualityThresholds?.thinkingModelDeltaMin !== undefined &&
+    thinkingModelDelta !== undefined &&
+    typeof thinkingModelDelta === 'number' &&
+    thinkingModelDelta <= options.qualityThresholds.thinkingModelDeltaMin
+  ) {
+    failures.push({
+      reason: `thinkingModelDelta (${thinkingModelDelta}) does not meet minimum quality threshold (${options.qualityThresholds.thinkingModelDeltaMin}) — reflection shows no cognitive improvement`,
+      field: 'thinkingModelDelta',
+    });
+  }
+
+  if (
+    options.qualityThresholds?.planningRatioGainMin !== undefined &&
+    planningRatioGain !== undefined &&
+    typeof planningRatioGain === 'number' &&
+    planningRatioGain < options.qualityThresholds.planningRatioGainMin
+  ) {
+    failures.push({
+      reason: `planningRatioGain (${planningRatioGain}) shows catastrophic planning regression — below minimum threshold (${options.qualityThresholds.planningRatioGainMin})`,
+      field: 'planningRatioGain',
+    });
+  }
+
+  // Final decision
+  if (failures.length > 0) {
+    return {
+      passed: false,
+      rawInput: obj as RawReflectionArtifact,
+      failures,
+    };
+  }
+
+  // Construct validated artifact
+  const artifact: NocturnalArtifact = {
+    artifactId: String(obj.artifactId),
+    sessionId: String(obj.sessionId),
+    principleId: String(obj.principleId),
+    sourceSnapshotRef: isNonEmptyString(obj.sourceSnapshotRef) ? String(obj.sourceSnapshotRef) : '',
+    badDecision: String(obj.badDecision),
+    betterDecision: String(obj.betterDecision),
+    rationale: String(obj.rationale),
+    createdAt: String(obj.createdAt),
+    thinkingModelDelta: typeof obj.thinkingModelDelta === 'number' ? obj.thinkingModelDelta : undefined,
+    planningRatioGain: typeof obj.planningRatioGain === 'number' ? obj.planningRatioGain : undefined,
+  };
+
+  return {
+    passed: true,
+    artifact,
+    failures: [],
+  };
+}
+
+/**
+ * Parse and validate a JSON string as a reflection artifact.
+ *
+ * @param jsonString - Raw JSON string from reflector
+ * @param options - Expected values for cross-validation
+ * @returns ArbiterResult
+ */
+export function parseAndValidateArtifact(
+  jsonString: string,
+  options: ArbiterOptions = {}
+): ArbiterResult {
+  // Step 1: Parse JSON
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(jsonString);
+  } catch (err) {
+    return {
+      passed: false,
+      failures: [{ reason: `Failed to parse JSON: ${err instanceof Error ? err.message : String(err)}` }],
+    };
+  }
+
+  // Step 2: Validate
+  return validateArtifact(parsed, options);
+}