Skip to content

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}`);
}
}
#CheckWhat It ValidatesError Code Prefix
1PLAN_STRUCTUREPlan has required fields, valid JSON structurePLAN_STRUCTURE_*
2CAPABILITY_AVAILABILITYAll referenced capabilities exist in the registryCAPABILITY_NOT_FOUND
3CAPABILITY_VERSIONReferenced versions exist and are not quarantinedVERSION_NOT_FOUND, VERSION_QUARANTINED
4SCHEMA_COMPATIBILITYData flowing between steps is type-compatibleSCHEMA_MISMATCH
5BINDING_VALIDITYPath expressions in bindings resolve to real dataBINDING_UNRESOLVABLE
6DEPENDENCY_GRAPHStep dependencies form a valid DAG (no cycles)CIRCULAR_DEPENDENCY
7EFFECT_MODE_COMPATIBILITYEffect classes are compatible with the requested execution modeEFFECT_MODE_INCOMPATIBLE
8POLICY_COMPLIANCEPlan complies with loaded governance policiesPOLICY_VIOLATION
9CONSTRAINT_SATISFACTIONUser has required roles, rate limits are satisfiedROLE_MISSING, RATE_LIMIT_EXCEEDED
10SUB_PLAN_DEPTHSub-plan nesting does not exceed the depth limit (5)DEPTH_EXCEEDED
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[];
}
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)
}

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.

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.

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)

Ensures the execution mode supports the plan’s capabilities:

  • SIMULATED mode: all effect classes allowed (nothing actually executes)
  • DRY_RUN mode: READ executes, writes are logged but not committed
  • LIVE mode: all effect classes execute with full governance

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),
},
});