@lota-sdk/core 0.1.9 → 0.1.11

package/src/services/plan-validator.service.ts

@@ -0,0 +1,760 @@
+import type {
+  PlanCompletionCheck,
+  PlanDataSchema,
+  PlanDraft,
+  PlanFailureClass,
+  PlanNodeSpec,
+  PlanValidationIssueSeverity,
+} from '@lota-sdk/shared/schemas/execution-plan'
+import type { PlanNodeResultSubmission } from '@lota-sdk/shared/schemas/tools'
+
+const STRUCTURAL_NODE_TYPES = new Set(['switch', 'join'])
+const HUMAN_NODE_TYPES = new Set(['human-input', 'human-approval', 'human-review-edit', 'human-decision'])
+
+export interface PlanValidationIssueInput {
+  severity: PlanValidationIssueSeverity
+  code: string
+  message: string
+  detail?: Record<string, unknown>
+  nodeId?: string
+}
+
+export interface DraftValidationResult {
+  blocking: PlanValidationIssueInput[]
+  warnings: PlanValidationIssueInput[]
+}
+
+export interface NodeResultValidationResult {
+  blocking: PlanValidationIssueInput[]
+  warnings: PlanValidationIssueInput[]
+  failureClass: PlanFailureClass | null
+}
+
+function createIssue(params: {
+  code: string
+  message: string
+  severity?: PlanValidationIssueSeverity
+  detail?: Record<string, unknown>
+  nodeId?: string
+}): PlanValidationIssueInput {
+  return {
+    severity: params.severity ?? 'blocking',
+    code: params.code,
+    message: params.message,
+    ...(params.detail ? { detail: params.detail } : {}),
+    ...(params.nodeId ? { nodeId: params.nodeId } : {}),
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function readPathValue(source: unknown, path: string): unknown {
+  if (!path.trim()) return source
+
+  let current: unknown = source
+  for (const segment of path
+    .split('.')
+    .map((part) => part.trim())
+    .filter(Boolean)) {
+    if (!isRecord(current)) return undefined
+    current = current[segment]
+  }
+  return current
+}
+
+function hasAllFields(value: unknown, fields: string[]): boolean {
+  if (!isRecord(value)) return false
+  return fields.every((field) => readPathValue(value, field) !== undefined)
+}
+
+function validateSchemaValue(params: { schema: PlanDataSchema; value: unknown; path: string }): string[] {
+  const issues: string[] = []
+  const { schema, value, path } = params
+
+  if (value === null || value === undefined) {
+    if (schema.required || (!schema.nullable && value === null)) {
+      issues.push(`${path} is required`)
+    }
+    return issues
+  }
+
+  if (schema.enum && !schema.enum.some((candidate) => Object.is(candidate, value))) {
+    issues.push(`${path} must be one of the allowed enum values`)
+    return issues
+  }
+
+  if (schema.type === 'string') {
+    if (typeof value !== 'string') issues.push(`${path} must be a string`)
+    return issues
+  }
+
+  if (schema.type === 'number') {
+    if (typeof value !== 'number' || Number.isNaN(value)) issues.push(`${path} must be a number`)
+    return issues
+  }
+
+  if (schema.type === 'boolean') {
+    if (typeof value !== 'boolean') issues.push(`${path} must be a boolean`)
+    return issues
+  }
+
+  if (schema.type === 'array') {
+    if (!Array.isArray(value)) {
+      issues.push(`${path} must be an array`)
+      return issues
+    }
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      issues.push(`${path} must contain at least ${schema.minItems} item(s)`)
+    }
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+      issues.push(`${path} must contain at most ${schema.maxItems} item(s)`)
+    }
+    const itemSchema = schema.items
+    if (itemSchema) {
+      value.forEach((entry, index) => {
+        issues.push(...validateSchemaValue({ schema: itemSchema, value: entry, path: `${path}[${index}]` }))
+      })
+    }
+    return issues
+  }
+
+  if (!isRecord(value)) {
+    issues.push(`${path} must be an object`)
+    return issues
+  }
+
+  for (const [key, childSchema] of Object.entries(schema.properties ?? {})) {
+    issues.push(...validateSchemaValue({ schema: childSchema, value: value[key], path: `${path}.${key}` }))
+  }
+
+  return issues
+}
+
+function buildReachableNodeIds(entryNodeIds: string[], adjacency: Map<string, string[]>): Set<string> {
+  const visited = new Set<string>()
+  const queue = [...entryNodeIds]
+
+  while (queue.length > 0) {
+    const nodeId = queue.shift()
+    if (!nodeId || visited.has(nodeId)) continue
+    visited.add(nodeId)
+    for (const next of adjacency.get(nodeId) ?? []) {
+      if (!visited.has(next)) {
+        queue.push(next)
+      }
+    }
+  }
+
+  return visited
+}
+
+function graphHasCycle(nodeIds: string[], adjacency: Map<string, string[]>): boolean {
+  const visiting = new Set<string>()
+  const visited = new Set<string>()
+
+  const visit = (nodeId: string): boolean => {
+    if (visited.has(nodeId)) return false
+    if (visiting.has(nodeId)) return true
+
+    visiting.add(nodeId)
+    for (const next of adjacency.get(nodeId) ?? []) {
+      if (visit(next)) return true
+    }
+    visiting.delete(nodeId)
+    visited.add(nodeId)
+    return false
+  }
+
+  return nodeIds.some((nodeId) => visit(nodeId))
+}
+
+function resolveSchemaRef(
+  draft: Pick<PlanDraft, 'schemas'>,
+  schemaRef: string | null | undefined,
+): PlanDataSchema | undefined {
+  if (!schemaRef) return undefined
+  return draft.schemas[schemaRef]
+}
+
+class PlanValidatorService {
+  validateDraft(draft: PlanDraft): DraftValidationResult {
+    const blocking: PlanValidationIssueInput[] = []
+    const warnings: PlanValidationIssueInput[] = []
+    const nodeIds = new Set<string>()
+    const edgeIds = new Set<string>()
+    const nodesById = new Map(draft.nodes.map((node) => [node.id, node]))
+    const adjacency = new Map<string, string[]>(draft.nodes.map((node) => [node.id, []]))
+    const inbound = new Map<string, string[]>(draft.nodes.map((node) => [node.id, []]))
+
+    for (const node of draft.nodes) {
+      if (nodeIds.has(node.id)) {
+        blocking.push(
+          createIssue({
+            code: 'duplicate_node_id',
+            message: `Plan contains duplicate node id "${node.id}".`,
+            nodeId: node.id,
+          }),
+        )
+      }
+      nodeIds.add(node.id)
+
+      const isStructuralNode = STRUCTURAL_NODE_TYPES.has(node.type)
+      if (!isStructuralNode && node.deliverables.length === 0) {
+        blocking.push(
+          createIssue({
+            code: 'node_missing_deliverables',
+            message: `Node "${node.label}" must define at least one deliverable.`,
+            nodeId: node.id,
+          }),
+        )
+      }
+      if (node.successCriteria.length === 0) {
+        blocking.push(
+          createIssue({
+            code: 'node_missing_success_criteria',
+            message: `Node "${node.label}" must define at least one success criterion.`,
+            nodeId: node.id,
+          }),
+        )
+      }
+      if (!isStructuralNode && node.completionChecks.length === 0) {
+        blocking.push(
+          createIssue({
+            code: 'node_missing_completion_checks',
+            message: `Node "${node.label}" must define at least one completion check.`,
+            nodeId: node.id,
+          }),
+        )
+      }
+      if (HUMAN_NODE_TYPES.has(node.type) && node.owner.executorType !== 'user') {
+        blocking.push(
+          createIssue({
+            code: 'human_node_owner_mismatch',
+            message: `Human node "${node.label}" must be owned by a user executor.`,
+            nodeId: node.id,
+          }),
+        )
+      }
+      if (
+        !HUMAN_NODE_TYPES.has(node.type) &&
+        node.type !== 'join' &&
+        node.type !== 'switch' &&
+        node.owner.ref.trim().length === 0
+      ) {
+        blocking.push(
+          createIssue({
+            code: 'node_owner_missing',
+            message: `Node "${node.label}" must declare an executor reference.`,
+            nodeId: node.id,
+          }),
+        )
+      }
+      if (node.inputSchemaRef && !resolveSchemaRef(draft, node.inputSchemaRef)) {
+        blocking.push(
+          createIssue({
+            code: 'missing_input_schema_ref',
+            message: `Node "${node.label}" references unknown input schema "${node.inputSchemaRef}".`,
+            nodeId: node.id,
+          }),
+        )
+      }
+      if (node.outputSchemaRef && !resolveSchemaRef(draft, node.outputSchemaRef)) {
+        blocking.push(
+          createIssue({
+            code: 'missing_output_schema_ref',
+            message: `Node "${node.label}" references unknown output schema "${node.outputSchemaRef}".`,
+            nodeId: node.id,
+          }),
+        )
+      }
+      for (const deliverable of node.deliverables) {
+        if (deliverable.schemaRef && !resolveSchemaRef(draft, deliverable.schemaRef)) {
+          blocking.push(
+            createIssue({
+              code: 'missing_artifact_schema_ref',
+              message: `Node "${node.label}" references unknown artifact schema "${deliverable.schemaRef}".`,
+              nodeId: node.id,
+              detail: { artifactName: deliverable.name },
+            }),
+          )
+        }
+      }
+      for (const check of node.completionChecks) {
+        const checkSchemaRef = typeof check.config.schemaRef === 'string' ? check.config.schemaRef : undefined
+        if (checkSchemaRef && !resolveSchemaRef(draft, checkSchemaRef)) {
+          blocking.push(
+            createIssue({
+              code: 'missing_completion_check_schema_ref',
+              message: `Node "${node.label}" references unknown completion-check schema "${checkSchemaRef}".`,
+              nodeId: node.id,
+              detail: { checkDescription: check.description },
+            }),
+          )
+        }
+      }
+      if (node.toolPolicy.allow.some((toolName) => node.toolPolicy.deny.includes(toolName))) {
+        warnings.push(
+          createIssue({
+            code: 'tool_policy_overlap',
+            severity: 'warning',
+            message: `Node "${node.label}" lists the same tool in allow and deny policy.`,
+            nodeId: node.id,
+          }),
+        )
+      }
+    }
+
+    const entryNodeIds = draft.entryNodeIds ?? []
+    for (const entryNodeId of entryNodeIds) {
+      if (!nodesById.has(entryNodeId)) {
+        blocking.push(
+          createIssue({
+            code: 'missing_entry_node',
+            message: `Entry node "${entryNodeId}" does not exist in the plan.`,
+            detail: { entryNodeId },
+          }),
+        )
+      }
+    }
+
+    for (const edge of draft.edges) {
+      if (edgeIds.has(edge.id)) {
+        blocking.push(
+          createIssue({
+            code: 'duplicate_edge_id',
+            message: `Plan contains duplicate edge id "${edge.id}".`,
+            detail: { edgeId: edge.id },
+          }),
+        )
+      }
+      edgeIds.add(edge.id)
+
+      if (!nodesById.has(edge.source)) {
+        blocking.push(
+          createIssue({
+            code: 'missing_edge_source',
+            message: `Edge "${edge.id}" references missing source node "${edge.source}".`,
+            detail: { edgeId: edge.id, source: edge.source },
+          }),
+        )
+        continue
+      }
+      if (!nodesById.has(edge.target)) {
+        blocking.push(
+          createIssue({
+            code: 'missing_edge_target',
+            message: `Edge "${edge.id}" references missing target node "${edge.target}".`,
+            detail: { edgeId: edge.id, target: edge.target },
+          }),
+        )
+        continue
+      }
+
+      adjacency.get(edge.source)?.push(edge.target)
+      inbound.get(edge.target)?.push(edge.source)
+    }
+
+    for (const node of draft.nodes) {
+      const inboundEdges = inbound.get(node.id) ?? []
+      const outboundEdges = adjacency.get(node.id) ?? []
+
+      if (node.type === 'join' && inboundEdges.length < 2) {
+        blocking.push(
+          createIssue({
+            code: 'join_requires_multiple_inbound_edges',
+            message: `Join node "${node.label}" must have at least two inbound edges.`,
+            nodeId: node.id,
+          }),
+        )
+      }
+
+      if (node.type === 'switch') {
+        const conditionalEdges = draft.edges.filter((edge) => edge.source === node.id && edge.when)
+        if (conditionalEdges.length === 0) {
+          blocking.push(
+            createIssue({
+              code: 'switch_requires_conditional_edges',
+              message: `Switch node "${node.label}" must define conditional outbound edges.`,
+              nodeId: node.id,
+            }),
+          )
+        }
+        if (outboundEdges.length < 2) {
+          warnings.push(
+            createIssue({
+              code: 'switch_has_single_path',
+              severity: 'warning',
+              message: `Switch node "${node.label}" only routes to one target.`,
+              nodeId: node.id,
+            }),
+          )
+        }
+      }
+
+      if (!entryNodeIds.includes(node.id) && inboundEdges.length === 0) {
+        blocking.push(
+          createIssue({
+            code: 'orphan_node',
+            message: `Node "${node.label}" is not connected to the graph.`,
+            nodeId: node.id,
+          }),
+        )
+      }
+
+      if (node.inputSchemaRef && inboundEdges.length > 0) {
+        const hasMappedInput = draft.edges
+          .filter((edge) => edge.target === node.id)
+          .some((edge) => Object.keys(edge.map).length > 0)
+        if (!hasMappedInput) {
+          blocking.push(
+            createIssue({
+              code: 'unresolved_node_input',
+              message: `Node "${node.label}" declares inputSchemaRef but no inbound edge maps data into it.`,
+              nodeId: node.id,
+            }),
+          )
+        }
+      }
+    }
+
+    const reachableNodeIds = buildReachableNodeIds(entryNodeIds, adjacency)
+    for (const node of draft.nodes) {
+      if (!reachableNodeIds.has(node.id)) {
+        blocking.push(
+          createIssue({
+            code: 'unreachable_node',
+            message: `Node "${node.label}" is unreachable from the configured entry nodes.`,
+            nodeId: node.id,
+          }),
+        )
+      }
+    }
+
+    if (
+      graphHasCycle(
+        draft.nodes.map((node) => node.id),
+        adjacency,
+      )
+    ) {
+      blocking.push(
+        createIssue({
+          code: 'cycle_detected',
+          message: 'Plan graph contains a cycle. Loop semantics are not supported in this cutover.',
+        }),
+      )
+    }
+
+    return { blocking, warnings }
+  }
+
+  validateNodeResult(params: {
+    draft: Pick<PlanDraft, 'schemas'>
+    node: PlanNodeSpec
+    result: PlanNodeResultSubmission
+  }): NodeResultValidationResult {
+    const blocking: PlanValidationIssueInput[] = []
+    const warnings: PlanValidationIssueInput[] = []
+    const artifactsByName = new Map(params.result.artifacts.map((artifact) => [artifact.name, artifact]))
+
+    if (params.node.outputSchemaRef) {
+      const outputSchema = resolveSchemaRef(params.draft, params.node.outputSchemaRef)
+      if (!params.result.structuredOutput) {
+        blocking.push(
+          createIssue({
+            code: 'structured_output_missing',
+            message: `Node "${params.node.label}" requires structured output.`,
+            nodeId: params.node.id,
+          }),
+        )
+      } else if (outputSchema) {
+        const schemaIssues = validateSchemaValue({
+          schema: outputSchema,
+          value: params.result.structuredOutput,
+          path: 'structuredOutput',
+        })
+        if (schemaIssues.length > 0) {
+          blocking.push(
+            createIssue({
+              code: 'schema_validation_failed',
+              message: `Structured output for node "${params.node.label}" failed schema validation.`,
+              nodeId: params.node.id,
+              detail: { issues: schemaIssues },
+            }),
+          )
+        }
+      }
+    }
+
+    for (const deliverable of params.node.deliverables) {
+      const artifact = artifactsByName.get(deliverable.name)
+      if (!artifact) {
+        if (deliverable.required) {
+          blocking.push(
+            createIssue({
+              code: 'required_artifact_missing',
+              message: `Node "${params.node.label}" is missing required artifact "${deliverable.name}".`,
+              nodeId: params.node.id,
+            }),
+          )
+        }
+        continue
+      }
+
+      if (artifact.kind !== deliverable.kind) {
+        blocking.push(
+          createIssue({
+            code: 'artifact_kind_mismatch',
+            message: `Artifact "${deliverable.name}" must be of kind "${deliverable.kind}".`,
+            nodeId: params.node.id,
+          }),
+        )
+      }
+
+      if (deliverable.schemaRef) {
+        if (artifact.schemaRef !== deliverable.schemaRef) {
+          blocking.push(
+            createIssue({
+              code: 'artifact_schema_mismatch',
+              message: `Artifact "${deliverable.name}" must declare schemaRef "${deliverable.schemaRef}".`,
+              nodeId: params.node.id,
+            }),
+          )
+        }
+
+        const artifactSchema = resolveSchemaRef(params.draft, deliverable.schemaRef)
+        if (!artifact.payload) {
+          blocking.push(
+            createIssue({
+              code: 'artifact_payload_missing',
+              message: `Artifact "${deliverable.name}" must include payload data for schema validation.`,
+              nodeId: params.node.id,
+            }),
+          )
+        } else if (artifactSchema) {
+          const schemaIssues = validateSchemaValue({
+            schema: artifactSchema,
+            value: artifact.payload,
+            path: `artifact:${deliverable.name}`,
+          })
+          if (schemaIssues.length > 0) {
+            blocking.push(
+              createIssue({
+                code: 'schema_validation_failed',
+                message: `Artifact "${deliverable.name}" failed schema validation.`,
+                nodeId: params.node.id,
+                detail: { issues: schemaIssues, artifact: deliverable.name },
+              }),
+            )
+          }
+        }
+      }
+    }
+
+    for (const check of params.node.completionChecks) {
+      const issue = this.evaluateCompletionCheck({
+        draft: params.draft,
+        node: params.node,
+        result: params.result,
+        check,
+      })
+      if (!issue) continue
+      if (issue.severity === 'warning') {
+        warnings.push(issue)
+      } else {
+        blocking.push(issue)
+      }
+    }
+
+    return { blocking, warnings, failureClass: this.resolveFailureClass(blocking) }
+  }
+
+  private evaluateCompletionCheck(params: {
+    draft: Pick<PlanDraft, 'schemas'>
+    node: PlanNodeSpec
+    result: PlanNodeResultSubmission
+    check: PlanCompletionCheck
+  }): PlanValidationIssueInput | null {
+    const { check, node, result, draft } = params
+    const artifactName = typeof check.config.artifact === 'string' ? check.config.artifact : undefined
+    const artifact = artifactName ? result.artifacts.find((candidate) => candidate.name === artifactName) : undefined
+    const target =
+      artifactName && artifact
+        ? artifact.payload
+        : typeof check.config.target === 'string'
+          ? readPathValue(result.structuredOutput, check.config.target)
+          : result.structuredOutput
+
+    if (check.type === 'schema') {
+      const schemaRef =
+        (typeof check.config.schemaRef === 'string' ? check.config.schemaRef : undefined) ??
+        artifact?.schemaRef ??
+        (artifactName ? node.deliverables.find((candidate) => candidate.name === artifactName)?.schemaRef : undefined)
+      if (!schemaRef) {
+        return createIssue({
+          code: 'schema_check_missing_schema_ref',
+          message: `Completion check "${check.description}" does not resolve a schema reference.`,
+          nodeId: node.id,
+          severity: check.blocking ? 'blocking' : 'warning',
+        })
+      }
+
+      if (artifactName && !artifact) {
+        return createIssue({
+          code: 'schema_check_artifact_missing',
+          message: `Completion check "${check.description}" requires artifact "${artifactName}".`,
+          nodeId: node.id,
+          severity: check.blocking ? 'blocking' : 'warning',
+        })
+      }
+
+      const schema = resolveSchemaRef(draft, schemaRef)
+      if (!schema) {
+        return createIssue({
+          code: 'schema_check_schema_missing',
+          message: `Completion check "${check.description}" references unknown schema "${schemaRef}".`,
+          nodeId: node.id,
+          severity: check.blocking ? 'blocking' : 'warning',
+        })
+      }
+
+      const schemaIssues = validateSchemaValue({
+        schema,
+        value: target,
+        path: artifactName ? `artifact:${artifactName}` : 'structuredOutput',
+      })
+      if (schemaIssues.length > 0) {
+        return createIssue({
+          code: 'schema_validation_failed',
+          message: `Completion check "${check.description}" failed schema validation.`,
+          nodeId: node.id,
+          severity: check.blocking ? 'blocking' : 'warning',
+          detail: { issues: schemaIssues, schemaRef },
+        })
+      }
+
+      return null
+    }
+
+    if (check.type === 'assertion') {
+      const requiredFields = Array.isArray(check.config.mustContainFields)
+        ? check.config.mustContainFields.filter((field): field is string => typeof field === 'string')
+        : []
+      if (requiredFields.length > 0 && !hasAllFields(target, requiredFields)) {
+        return createIssue({
+          code: 'assertion_failed',
+          message: `Assertion "${check.description}" failed because required fields are missing.`,
+          nodeId: node.id,
+          severity: check.blocking ? 'blocking' : 'warning',
+          detail: { mustContainFields: requiredFields },
+        })
+      }
+
+      const equalityPath = typeof check.config.path === 'string' ? check.config.path : undefined
+      if (equalityPath && 'equals' in check.config) {
+        const actual = readPathValue(target, equalityPath)
+        if (!Object.is(actual, check.config.equals)) {
+          return createIssue({
+            code: 'assertion_failed',
+            message: `Assertion "${check.description}" failed at path "${equalityPath}".`,
+            nodeId: node.id,
+            severity: check.blocking ? 'blocking' : 'warning',
+            detail: { path: equalityPath, expected: check.config.equals, actual },
+          })
+        }
+      }
+
+      const truthyPaths = Array.isArray(check.config.truthyPaths)
+        ? check.config.truthyPaths.filter((entry): entry is string => typeof entry === 'string')
+        : []
+      if (truthyPaths.some((path) => !readPathValue(target, path))) {
+        return createIssue({
+          code: 'assertion_failed',
+          message: `Assertion "${check.description}" expected truthy values that were not present.`,
+          nodeId: node.id,
+          severity: check.blocking ? 'blocking' : 'warning',
+          detail: { truthyPaths },
+        })
+      }
+
+      return null
+    }
+
+    if (check.type === 'tool-check') {
+      const mode = typeof check.config.mode === 'string' ? check.config.mode : 'artifact-present'
+      if (mode === 'artifact-present' && artifactName && !artifact) {
+        return createIssue({
+          code: 'required_artifact_missing',
+          message: `Tool check "${check.description}" requires artifact "${artifactName}".`,
+          nodeId: node.id,
+          severity: check.blocking ? 'blocking' : 'warning',
+        })
+      }
+      if (
+        mode === 'artifact-kind' &&
+        artifactName &&
+        artifact &&
+        typeof check.config.kind === 'string' &&
+        artifact.kind !== check.config.kind
+      ) {
+        return createIssue({
+          code: 'artifact_kind_mismatch',
+          message: `Tool check "${check.description}" expected artifact "${artifactName}" to be kind "${check.config.kind}".`,
+          nodeId: node.id,
+          severity: check.blocking ? 'blocking' : 'warning',
+        })
+      }
+      if (
+        mode === 'min-artifact-count' &&
+        typeof check.config.count === 'number' &&
+        result.artifacts.length < check.config.count
+      ) {
+        return createIssue({
+          code: 'required_artifact_missing',
+          message: `Tool check "${check.description}" expected at least ${check.config.count} artifact(s).`,
+          nodeId: node.id,
+          severity: check.blocking ? 'blocking' : 'warning',
+        })
+      }
+      return null
+    }
+
+    if (check.type === 'human-approval') {
+      const approvedField = typeof check.config.approvedField === 'string' ? check.config.approvedField : 'approved'
+      if (readPathValue(result.structuredOutput, approvedField) !== true) {
+        return createIssue({
+          code: 'human_rejected',
+          message: `Human approval check "${check.description}" did not pass.`,
+          nodeId: node.id,
+          severity: check.blocking ? 'blocking' : 'warning',
+          detail: { approvedField },
+        })
+      }
+      return null
+    }
+
+    const resultField = typeof check.config.resultField === 'string' ? check.config.resultField : 'passed'
+    if (readPathValue(result.structuredOutput, resultField) !== true) {
+      return createIssue({
+        code: 'schema_validation_failed',
+        message: `LLM judge check "${check.description}" did not report success.`,
+        nodeId: node.id,
+        severity: check.blocking ? 'blocking' : 'warning',
+        detail: { resultField },
+      })
+    }
+    return null
+  }
+
+  private resolveFailureClass(blocking: PlanValidationIssueInput[]): PlanFailureClass | null {
+    for (const issue of blocking) {
+      if (issue.code === 'required_artifact_missing') return 'required_artifact_missing'
+      if (issue.code === 'human_rejected') return 'human_rejected'
+      if (issue.code === 'schema_validation_failed') return 'schema_validation_failed'
+    }
+    return blocking.length > 0 ? 'non_recoverable_logic_error' : null
+  }
+}
+
+export const planValidatorService = new PlanValidatorService()