Skip to content

Validator

The Validator is the safety gate between plan generation and plan execution. Every plan — whether generated by the Planner, authored by a developer, or retrieved from the Plan Library — must pass validation before execution. No exceptions. This specification defines the validation pipeline, its checks, its output format, and its role as defense-in-depth behind the policy-aware Planner.


  1. No invalid plan executes. The Validator is the last line of defense. If it passes a plan, the Execution Engine must be able to run it without structural failures.
  2. Structured, actionable failures. Validation failures are not generic errors. Each failure identifies the specific check that failed, the specific step or binding that caused it, and a human-readable explanation.
  3. Defense-in-depth. The Planner is policy-aware and should produce executable plans. The Validator is the safety net. Policy-denied plans from the Planner should be rare exceptions (race conditions, registry changes). The Validator catches them anyway.
  4. Deterministic. The same plan + the same registry/policy state = the same validation result. Always. No LLM involvement. No randomness.
  5. Fast. Validation should add minimal latency to the planning pipeline. Target: < 200ms for a 10-step plan.
  6. Cacheable for promoted plans. Promoted plans that haven’t changed can cache their validation result. Re-validation is only required when the plan, its capabilities, or its applicable policies change.

interface ValidationRequest {
plan: PlanIR; // Full Plan IR (from Enrichment or direct authoring)
user_context: UserContext; // Who is requesting execution
requested_mode: ExecutionMode; // LIVE, DRY_RUN, or SIMULATED
environment: string; // 'production', 'staging', 'development'
}
interface ValidationResult {
valid: boolean;
plan_id: string;
validation_id: string; // Unique ID for this validation run
timestamp: string;
duration_ms: number;
// If valid: these are populated
validated_plan?: PlanIR; // The plan, unchanged (confirmation it passed)
validation_hash?: string; // Hash of plan + registry state + policy state (for cache)
// If invalid: these are populated
errors?: ValidationError[]; // Hard failures -- plan cannot execute
warnings?: ValidationWarning[]; // Soft issues -- plan can execute but something is notable
// Always populated
checks_performed: CheckResult[]; // Full audit of every check and its outcome
}
interface ValidationError {
check: ValidationCheck; // Which check failed
severity: 'error';
step_index?: number; // Which step (if step-specific)
field?: string; // Which field (if field-specific)
message: string; // Human-readable explanation
code: string; // Machine-readable error code
suggestion?: string; // How to fix it (if known)
}
interface ValidationWarning {
check: ValidationCheck;
severity: 'warning';
step_index?: number;
field?: string;
message: string;
code: string;
}
interface CheckResult {
check: ValidationCheck;
passed: boolean;
duration_ms: number;
details?: string; // Additional info (e.g., "3 capabilities checked, all available")
}
type ValidationCheck =
| 'SCHEMA_COMPATIBILITY'
| 'CAPABILITY_AVAILABILITY'
| 'CAPABILITY_VERSION'
| 'POLICY_COMPLIANCE'
| 'EFFECT_MODE_COMPATIBILITY'
| 'BINDING_VALIDITY'
| 'DEPENDENCY_GRAPH'
| 'CONSTRAINT_SATISFACTION'
| 'PLAN_STRUCTURE'
| 'SUB_PLAN_DEPTH';

The Validator runs checks in a defined order. All checks run even if an earlier check fails — this ensures the developer gets a complete picture of all issues, not just the first one.

Check 1: PLAN_STRUCTURE
Verify the Plan IR is structurally valid JSON conforming to the Plan IR schema.
Check 2: CAPABILITY_AVAILABILITY
Verify every capability referenced in the plan exists in the Capability Registry.
Check 3: CAPABILITY_VERSION
Verify the pinned capability versions are still available and not quarantined.
Check 4: SCHEMA_COMPATIBILITY
Verify data flow: each step's input bindings resolve to values whose
types match the capability's input_schema.
Check 5: BINDING_VALIDITY
Verify all binding path expressions are valid and reference existing
steps, outputs, or intent inputs.
Check 6: DEPENDENCY_GRAPH
Verify the depends_on graph is a valid DAG (no cycles).
Verify all referenced step indices exist.
Check 7: EFFECT_MODE_COMPATIBILITY
Verify the plan's aggregate effect class is permitted in the requested
execution mode.
Check 8: POLICY_COMPLIANCE
Run full pre-execution policy evaluation on the plan.
Check 9: CONSTRAINT_SATISFACTION
Verify all capability-level constraints are satisfied
(required_roles, rate limits, preconditions).
Check 10: SUB_PLAN_DEPTH
If the plan invokes sub-plans, verify the total depth does not
exceed the limit (default: 5).

Validates the Plan IR document itself:

  • Has all required top-level fields (plan_id, name, version, steps, input_schema, output_schema, metadata).
  • steps is a non-empty array.
  • Each step has required fields (step_index, name, capability or sub_plan, input_bindings).
  • No duplicate step_index values.
  • step_index values are sequential starting from 0.
  • Plan version is valid semver.

Error codes:

CodeMeaning
PLAN_MISSING_FIELDRequired field is absent
PLAN_EMPTY_STEPSSteps array is empty
PLAN_DUPLICATE_INDEXTwo steps have the same step_index
PLAN_INVALID_VERSIONVersion string is not valid semver

For each step that references a capability:

  • The capability name exists in the Capability Registry.
  • The capability is not disabled or removed.

Error codes:

CodeMeaning
CAPABILITY_NOT_FOUNDCapability name is not registered
CAPABILITY_DISABLEDCapability exists but is currently disabled

For each step:

  • The pinned capability version (capability.version) exists in the registry.
  • The version is not quarantined.
  • If no version is pinned: resolve to the latest available version (and record which version was resolved in the check result).

Error codes:

CodeMeaning
VERSION_NOT_FOUNDThe specific version is not registered
VERSION_QUARANTINEDThe version has been quarantined due to failures

For each step, validate that the resolved input values match the capability’s input_schema:

  • For each input binding, trace the source (literal value, intent input, prior step output, named reference, transform result).
  • Resolve the source’s type (from the source capability’s output_schema, or from the plan’s input_schema for intent inputs).
  • Check structural compatibility: is the source type assignable to the target type? Uses the Type System’s compatibility rules (see Type System Specification).

This is the most complex check. It’s essentially a type checker for the plan’s data flow.

Compatibility rules:

Source TypeTarget TypeCompatible?
stringstringYes
string (format: email)stringYes (format is a refinement)
stringstring (format: email)Warning (source may not be a valid email)
integernumberYes (integer is a subtype of number)
numberintegerWarning (may lose precision)
Object with extra fieldsObject (target)Yes (extra fields are ignored)
Object missing required fieldObject (target)Error

Error codes:

CodeMeaning
SCHEMA_TYPE_MISMATCHSource type is incompatible with target type
SCHEMA_MISSING_REQUIREDA required input field has no binding
SCHEMA_FORMAT_MISMATCHTypes match but format constraints may not (warning)

For each input binding in each step:

  • Path expressions ($.steps[N].out.field) reference valid step indices and output fields.
  • Named references ($.named.key.field) reference steps with matching output_name.
  • Intent input references ($.inputs.field) match fields in the plan’s input_schema.
  • Literal values ($literal) are valid JSON.
  • Transform expressions ($transform) reference valid transform functions.

Error codes:

CodeMeaning
BINDING_INVALID_PATHPath expression references a non-existent step or field
BINDING_MISSING_SOURCEBinding references a step output that doesn’t exist
BINDING_CIRCULARBinding creates a circular reference
BINDING_INVALID_TRANSFORMTransform function is not recognized

Analyze the depends_on fields across all steps:

  • Build a directed graph from depends_on relationships.
  • Verify the graph is acyclic (DAG). A cycle means the plan cannot execute.
  • Verify all step indices in depends_on arrays reference existing steps.
  • Verify that data flow is consistent with dependencies (if step B reads step A’s output, step B must depend on step A).

v1 note: Even though v1 executes steps sequentially (ignoring depends_on for scheduling), the Validator still checks the dependency graph for structural correctness. This ensures plans are valid for future parallel execution and catches data flow inconsistencies.

Error codes:

CodeMeaning
DEPENDENCY_CYCLEThe depends_on graph contains a cycle
DEPENDENCY_MISSING_STEPdepends_on references a non-existent step
DEPENDENCY_MISSING_DATA_DEPStep reads from a step it doesn’t depend on (would race in parallel execution)

Check the plan’s aggregate effect class against the requested execution mode:

Aggregate EffectSIMULATEDDRY_RUNLIVE
READAllowedAllowedAllowed
WRITE_INTERNALAllowed (mocked)Allowed (blocked at outbox)Allowed
WRITE_EXTERNALAllowed (mocked)Warning (should use sandbox)Allowed
DESTRUCTIVEAllowed (mocked)Error (not permitted in DRY_RUN)Allowed (with policy gates)

The aggregate effect class is the highest effect class across all steps in the plan.

Error codes:

CodeMeaning
EFFECT_MODE_DENIEDPlan’s aggregate effect is not permitted in the requested mode

Warning codes:

CodeMeaning
EFFECT_MODE_CAUTIONPlan has external effects in DRY_RUN (should use sandbox/test keys)

Run the Policy Engine’s pre-execution evaluation on the full plan:

  • Collect all applicable policies (scoped by environment, tenant, user).
  • Evaluate each policy’s conditions against the plan metadata (aggregate effect, tags, lifecycle state, step count).
  • Aggregate results: any DENY stops the plan. GATEs are noted (they’ll trigger at execution time, but the plan itself is valid).

This is the defense-in-depth check. The Planner already performed per-capability policy pre-checks. This check evaluates plan-level policies that the Planner doesn’t see (e.g., “candidate plans must run in DRY_RUN first,” “plans with more than 5 steps require approval”).

Error codes:

CodeMeaning
POLICY_DENIEDA policy explicitly denies this plan
POLICY_REQUIRES_MODEA policy requires a different execution mode

Info codes:

CodeMeaning
POLICY_GATE_PENDINGA policy will trigger a gate during execution (not a failure, informational)

For each capability in the plan, check its declared capability-level constraints:

  • required_roles: Does the current user have at least one of the required roles?
  • rate_limit: Has the user exceeded the rate limit for this capability? (Requires checking execution history.)
  • preconditions: Are static preconditions met? (Dynamic preconditions are checked at execution time.)

Error codes:

CodeMeaning
CONSTRAINT_ROLE_MISSINGUser lacks required role for a capability
CONSTRAINT_RATE_EXCEEDEDUser has exceeded the rate limit
CONSTRAINT_PRECONDITION_FAILEDA static precondition is not met

Note: Role constraint failures at validation time are unexpected — the Planner should have already filtered out capabilities the user can’t access. If this fires, it indicates a race condition (role changed between planning and validation) or a bug. The error message should note this.

If the plan invokes sub-plans (via sub_plan field on steps):

  • Count the maximum nesting depth.
  • Verify it does not exceed the configured limit (default: 5).
  • Recursively validate each sub-plan (all checks apply to sub-plans too).

Error codes:

CodeMeaning
SUB_PLAN_DEPTH_EXCEEDEDNesting depth exceeds the limit
SUB_PLAN_NOT_FOUNDReferenced sub-plan is not in the Plan Library

Promoted plans with a stable validation result can be cached. The cache is invalidated when:

ChangeCache Action
Plan version changesInvalidate
Any referenced capability version changesInvalidate
Any applicable policy changes (add, modify, delete)Invalidate
User roles changeInvalidate (role-dependent checks)
Registry state changes (capability added/removed)Invalidate affected plans
Environment or execution mode changesInvalidate (different mode = different check results)
cache_key = SHA-256(
plan_id + plan_version +
sorted(capability_name:version for each step) +
sorted(applicable_policy_id:version) +
user_roles_hash +
environment + requested_mode
)
  • Per-user caching: Since role checks are user-specific, each user gets their own cache entry for a plan.
  • Cache TTL: Configurable. Default: 5 minutes. Short enough to catch policy changes, long enough to avoid repeated validation for the same user submitting the same intent.

Planner → Plan Draft → Plan Enrichment → Full Plan IR → Validator → Execution Engine

The most common path. The Planner already performed policy pre-checks, so the Validator is defense-in-depth. Most validation failures here are schema compatibility issues (if the Planner selected an incompatible capability combination) or race conditions.

Developer writes Full Plan IR directly → Validator → Plan Library (or Execution Engine)

For hand-authored plans, validation is the primary quality gate. Developers may submit plans that have schema errors, missing bindings, or policy violations. The Validator’s structured errors guide the developer to fix them.

The CLI provides a zakardo plan validate command that runs the Validator locally during development.

Plan Library → Full Plan IR (promoted) → Validator (cached?) → Execution Engine

Promoted plans retrieved from the Plan Library are re-validated before execution. This catches:

  • Policy changes since the plan was promoted
  • Capability deprecation or quarantine since the plan was promoted
  • User role changes (the promoting user may have had different roles than the current user)

If the validation result is cached and the cache key matches, validation is skipped (cache hit).

Training System → Plan IR → Validator (in TRAINING mode) → Execution Engine (TRAINING mode)

Training runs validate plans with requested_mode: 'TRAINING'. The same checks apply, but execution mode compatibility is evaluated against TRAINING (which behaves like SIMULATED for external effects).


When a developer validates a plan via CLI, the output is formatted for readability:

$ zakardo plan validate ./plans/send_welcome_email.json
✗ Validation FAILED (3 errors, 1 warning)
ERRORS:
[SCHEMA_MISSING_REQUIRED] Step 2 (send_templated_email)
Input field "template_id" is required but has no binding.
Suggestion: Add a binding for template_id from intent inputs or a prior step.
[BINDING_INVALID_PATH] Step 1 (get_user_by_id)
Binding "$.steps[3].out.user_id" references step 3, but the plan only has 3 steps (0-2).
Suggestion: Check the step index in the binding path.
[POLICY_DENIED] Plan-level
Policy "candidate_plan_safety" requires CANDIDATE plans to run in DRY_RUN mode first.
Current requested mode: LIVE.
Suggestion: Run with --mode dry_run first, then promote the plan.
WARNINGS:
[SCHEMA_FORMAT_MISMATCH] Step 2 (send_templated_email)
Input "to" expects format "email", but source (step 0, field "contact_info") is
typed as plain "string". The value may not be a valid email at runtime.
Checks performed: 10/10 | Duration: 47ms

When the frontend receives a validation failure (from the Runtime API), it gets the structured ValidationResult. The frontend SDK renders this as:

  • A summary: “This plan cannot be executed because of 3 issues.”
  • Each error with its human-readable message and suggestion.
  • A link to retry after fixing (for developer-authored plans).

Every validation run is recorded in the Trace:

interface ValidationTraceEntry {
validation_id: string;
plan_id: string;
plan_version: string;
user_id: string;
requested_mode: ExecutionMode;
environment: string;
result: 'pass' | 'fail';
error_count: number;
warning_count: number;
checks: CheckResult[];
duration_ms: number;
cache_hit: boolean;
timestamp: string;
}

This enables:

  • Auditing: every validation decision is recorded.
  • Monitoring: track validation failure rates, common error types, cache hit rates.
  • Debugging: when a plan fails execution despite passing validation, the trace shows exactly what was checked.

When the frontend renders a Plan Preview (before the user approves execution), the validation result is included:

  • Valid plan: Plan Preview shows the plan with a green “Ready to execute” indicator.
  • Valid plan with warnings: Plan Preview shows the plan with a yellow “Proceed with caution” indicator and lists warnings.
  • Invalid plan: Plan Preview shows the plan with a red “Cannot execute” indicator and lists errors. The “Execute” button is disabled.

The Plan Preview also shows any pending gates (from Check 8, POLICY_GATE_PENDING). These are not errors — the plan is valid — but the user should know that execution will pause for approvals.


Developers can register custom validation checks that run as part of the pipeline:

config/execution.ts
{
validator: {
custom_checks: [
{
name: 'COMPLIANCE_CHECK',
description: 'Verify plan complies with internal compliance requirements',
check: async (plan, context) => {
// Custom logic
if (plan.metadata.tags.includes('financial') && !context.user_context.roles.includes('compliance_approved')) {
return {
passed: false,
errors: [{
check: 'COMPLIANCE_CHECK',
severity: 'error',
message: 'Financial plans require the compliance_approved role',
code: 'COMPLIANCE_ROLE_MISSING',
}],
};
}
return { passed: true };
},
},
],
}
}

Custom checks run after all built-in checks. They have access to the full Plan IR and user context.

Developers can register hooks that fire after validation completes:

  • onValidationPass(result) — called when a plan passes. Useful for logging, metrics, or triggering external workflows.
  • onValidationFail(result) — called when a plan fails. Useful for alerting, escalation, or auto-repair triggers.

DecisionResolution
Validator is mandatoryEvery plan must pass validation. No bypass. Not even promoted plans (they use cached validation).
Defense-in-depthThe Planner handles policy at generation time. The Validator catches what the Planner missed. Policy denials at validation are exceptional, not normal.
DeterministicSame plan + same state = same result. No LLM. No randomness.
All checks runEven if an early check fails, all checks execute. Developer gets the full picture.
10 built-in checksStructure, capability availability, version, schema compatibility, binding validity, dependency graph, effect/mode compatibility, policy compliance, constraint satisfaction, sub-plan depth.
Structured errorsEach error has: check type, severity, step index, field, message, code, and optional suggestion.
Validation cachingPromoted plans cache their validation result. Cache invalidated on plan, capability, policy, or role changes. Default TTL: 5 minutes.
Custom checksDevelopers can register custom validation checks in config/execution.ts. Run after built-in checks.
Warnings are non-blockingWarnings (e.g., format mismatches) do not prevent execution. Errors do.
Plan Preview integrationValidation result is shown in Plan Preview — valid (green), warnings (yellow), invalid (red). Pending gates listed as informational.
Trace integrationEvery validation run recorded in the Trace. Enables auditing and monitoring.
Target latency< 200ms for a 10-step plan (excluding sub-plan recursion).

QuestionDeferred To
How does the Execution Engine handle plans that pass validation but fail at runtime?Execution Engine Specification
How are validation metrics monitored and alerted on?Trace System Specification
What is the exact zakardo plan validate CLI command interface?CLI and DX Specification
How does the frontend render validation results in Plan Preview?Frontend Architecture Specification
How are custom checks distributed in Capability Packs?Registry and Marketplace Specification
How does validation interact with plan promotion criteria?Plan Library and Lifecycle Specification