Validator
The Validator is the safety gate between plan generation and execution. It runs 10 checks on every Plan IR — all checks run even if earlier ones fail, producing a comprehensive error report.
import { Validator, CapabilityRegistry } from '@zakardo/core';import type { ValidationRequest, ValidationResult } from '@zakardo/core';
const registry = new CapabilityRegistry();// ... register capabilities ...
const validator = new Validator();
const result: ValidationResult = validator.validate({ plan: enrichedPlanIR, user_context: { user_id: 'user-1', roles: ['admin'] }, requested_mode: 'LIVE', environment: 'production',});
if (result.valid) { console.log('Plan is valid — ready for execution'); console.log('Validated plan:', result.validated_plan);} else { console.log('Validation failed:'); for (const error of result.errors) { console.log(` [${error.check}] ${error.code}: ${error.message}`); }}The 10 Checks
Section titled “The 10 Checks”| # | Check | What It Validates | Error Code Prefix |
|---|---|---|---|
| 1 | PLAN_STRUCTURE | Plan has required fields, valid JSON structure | PLAN_STRUCTURE_* |
| 2 | CAPABILITY_AVAILABILITY | All referenced capabilities exist in the registry | CAPABILITY_NOT_FOUND |
| 3 | CAPABILITY_VERSION | Referenced versions exist and are not quarantined | VERSION_NOT_FOUND, VERSION_QUARANTINED |
| 4 | SCHEMA_COMPATIBILITY | Data flowing between steps is type-compatible | SCHEMA_MISMATCH |
| 5 | BINDING_VALIDITY | Path expressions in bindings resolve to real data | BINDING_UNRESOLVABLE |
| 6 | DEPENDENCY_GRAPH | Step dependencies form a valid DAG (no cycles) | CIRCULAR_DEPENDENCY |
| 7 | EFFECT_MODE_COMPATIBILITY | Effect classes are compatible with the requested execution mode | EFFECT_MODE_INCOMPATIBLE |
| 8 | POLICY_COMPLIANCE | Plan complies with loaded governance policies | POLICY_VIOLATION |
| 9 | CONSTRAINT_SATISFACTION | User has required roles, rate limits are satisfied | ROLE_MISSING, RATE_LIMIT_EXCEEDED |
| 10 | SUB_PLAN_DEPTH | Sub-plan nesting does not exceed the depth limit (5) | DEPTH_EXCEEDED |
ValidationRequest
Section titled “ValidationRequest”interface ValidationRequest { plan: PlanIR; // The enriched plan to validate user_context: UserContext; // Who is requesting execution requested_mode: ExecutionMode; // SIMULATED | DRY_RUN | LIVE environment: string; // 'production' | 'staging' | 'development' | etc.}
interface UserContext { user_id: string; tenant_id?: string; roles: readonly string[];}ValidationResult
Section titled “ValidationResult”interface ValidationResult { valid: boolean; // Overall pass/fail plan_id: PlanId; // Plan identifier validation_id: ValidationId; // Unique validation run ID timestamp: string; // ISO 8601 duration_ms: number; // How long validation took validated_plan?: PlanIR; // Plan (if valid) with validation hash validation_hash?: string; // SHA-256 of the validated plan errors: readonly ValidationError[]; // All errors found warnings: readonly ValidationWarning[]; // Non-blocking warnings checks_performed: readonly CheckResult[]; // Result of each check}
interface ValidationError { check: ValidationCheck; // Which check produced this error severity: 'error'; code: string; // Machine-readable error code message: string; // Human-readable description path?: string; // JSON path to the problematic element step_index?: number; // Which step (if step-specific)}Check Details
Section titled “Check Details”Check 1: PLAN_STRUCTURE
Section titled “Check 1: PLAN_STRUCTURE”Validates that the plan has the required fields: plan_id, version, metadata, steps (non-empty array), and that each step has capability, version, step_index, and bindings.
Check 4: SCHEMA_COMPATIBILITY
Section titled “Check 4: SCHEMA_COMPATIBILITY”The most complex check. For each step’s input bindings, the validator traces the data source and verifies that the source schema is structurally compatible with the expected input schema. Uses the checkCompatibility function from the type system.
Check 6: DEPENDENCY_GRAPH
Section titled “Check 6: DEPENDENCY_GRAPH”Builds an adjacency list from depends_on declarations and verifies:
- No cycles exist (topological sort succeeds)
- All referenced dependencies point to valid step indices
- The graph is connected (no orphaned steps)
Check 7: EFFECT_MODE_COMPATIBILITY
Section titled “Check 7: EFFECT_MODE_COMPATIBILITY”Ensures the execution mode supports the plan’s capabilities:
SIMULATEDmode: all effect classes allowed (nothing actually executes)DRY_RUNmode:READexecutes, writes are logged but not committedLIVEmode: all effect classes execute with full governance
Custom Policy Evaluator
Section titled “Custom Policy Evaluator”By default, the validator uses a stub policy evaluator. Provide a custom one:
import { Validator, PolicyEngine } from '@zakardo/core';
const policyEngine = new PolicyEngine(policies);
const validator = new Validator({ policyEvaluator: { evaluate: (plan, context) => policyEngine.evaluatePlan(plan, context), },});Further Reading
Section titled “Further Reading”- Enrichment Pipeline API — what produces the Plan IR
- Execution Engine API — what runs validated plans
- Validator Specification — full specification