Skip to content

Plan IR

This document defines the Intermediate Representation (IR) for Zakardo Plans — the most critical data structure in the entire system. It covers two formats: the Plan Draft (what the Planner produces) and the Full Plan IR (what the Execution Engine runs). The Plan Draft is minimal and LLM-friendly. The Full Plan IR is enriched by the runtime from the draft.

Prerequisites: Glossary, System Architecture, Type System


Plan IR exists in two forms:

LayerProduced ByContainsPurpose
Plan DraftPlanner (LLM)Capability chain + input bindingsMinimal format the LLM generates. Sequential, no metadata, no schemas.
Full Plan IRPlan Enrichment (runtime)Everything needed for executionComplete format with schemas, parallelism, error policies, metadata.

Why two layers?

The Planner uses an LLM for reasoning. LLMs are unreliable at producing large, complex JSON documents in one shot. The more fields the LLM must generate, the higher the failure rate. By separating the format into what the LLM decides (Plan Draft) and what the runtime computes (Full Plan IR), we:

  • Reduce the LLM’s output surface to the minimum necessary decisions.
  • Let the runtime infer schemas, compute parallelism, and add metadata deterministically.
  • Enable incremental generation (the LLM builds the draft step by step, with validation between each step).
  • Keep the Full Plan IR rich enough for execution, governance, and auditability.

Plan Draft must:

  1. Be trivially simple. An LLM should be able to produce a valid draft with minimal structural complexity.
  2. Be sequential. Steps are an ordered list. No graph reasoning required.
  3. Capture only decisions. Which capabilities to call and how to wire their inputs. Nothing else.
  4. Support incremental construction. Each step can be generated and validated independently.

Full Plan IR must:

  1. Be JSON-serializable. Plans are stored, transmitted, and inspected as JSON documents.
  2. Support all execution constructs. Sequence, parallel, conditional, error handling, gates, interaction points, sub-plan invocation.
  3. Express data bindings. Steps reference outputs of prior steps via path expressions.
  4. Be deterministic. Given the same Plan IR and the same inputs, the Execution Engine produces the same execution sequence (modulo external side effects).
  5. Be inspectable. A human or an LLM can read a Plan IR document and understand what it will do.
  6. Be versionable. Plans are versioned artifacts. The IR format must support diffing and breaking change detection.

1A. Plan Generation Strategy: Backward Chaining

Section titled “1A. Plan Generation Strategy: Backward Chaining”

The Planner generates Plan Drafts using backward chaining (goal-directed reasoning). Instead of building forward from the intent (“what should I do first?”), it starts from the desired output and works backwards (“what capability produces the result I need? what does it need that I don’t have?“).

  • Anchors the LLM on the goal. The first decision is “what output do I need?” — a constrained question with a clear answer.
  • Single-capability plans are trivial. Most intents resolve to one capability. The backward chain is one step: find the capability, confirm inputs are available, done.
  • Multi-step plans emerge from gap analysis. Each additional capability is added only to fill a gap between what’s available and what’s needed. No unnecessary steps.
  • It’s type-driven. Gap analysis is a schema matching problem: “capability X needs type Y, I have type Z, what bridges Z to Y?” The runtime can assist by querying the Capability Registry.
  • Produces minimal plans. Because steps are only added to close gaps, there’s no tendency to hallucinate extra steps.
Step 1: GOAL IDENTIFICATION
Planner (LLM): Given intent, identify the desired output.
Example: "delete customer account ABC-123" -> goal: account deleted
Step 2: TERMINAL CAPABILITY SELECTION
Runtime: Query Capability Registry for capabilities whose output matches the goal.
Planner (LLM): Score candidates against intent. Pick the best match.
If high confidence (one clear winner): select it.
If medium confidence (2-3 close options): LLM scores and picks best.
If low confidence (nothing matches): fall back to CLARIFY mode.
Example: delete_customer_account selected (score: 0.95)
Step 3: POLICY PRE-CHECK (critical -- ensures plans always succeed)
Runtime: Check TWO policy surfaces:
a. System-level policy (Policy Engine): effect class, boundary, tags vs. user roles
b. Capability-level constraints: required_roles declared on the capability
If both ALLOWED: proceed to Step 4.
If either DENIED: go to Step 3A (find alternative).
Step 3A: ALTERNATIVE CAPABILITY SEARCH
Runtime: Query Capability Registry for alternative capabilities that
achieve a version of the goal within the user's permissions.
Common pattern: "request_X" as an alternative to "X"
(e.g., request_account_deletion instead of delete_customer_account).
Planner (LLM): Evaluate alternatives. Pick the best match.
If alternative found:
- Adjust the goal (e.g., "deletion request submitted" instead of "deleted").
- Replace terminal capability with the alternative.
- Continue to Step 4 with the new capability.
If no alternative found:
- CONVERSE: explain why the action isn't possible and what the user can do.
- Example: "I can't delete that account -- it requires admin permissions.
Ask your administrator, or I can help you with something else."
Example: request_account_deletion found (WRITE_INTERNAL, user allowed).
Goal adjusted: "deletion request submitted."
Step 4: GAP ANALYSIS
Runtime: Compare terminal capability's input schema against available data
(intent inputs + system context).
Identify gaps: input fields that cannot be satisfied from available data.
If no gaps: plan is complete (single-capability plan). Go to Step 6.
Example: request_account_deletion needs {customer_id: uuid, reason: string}.
Available: {customer_id: "ABC-123"}. Gap: [reason].
Step 5: GAP RESOLUTION (repeat until all gaps closed)
Runtime: Query Capability Registry for capabilities whose output can fill the gap.
Planner (LLM): Select the bridging capability.
Runtime: POLICY PRE-CHECK on the bridging capability (same as Step 3).
If blocked: search for an alternative bridging capability.
Runtime: Check if bridging capability's inputs are available.
If yes: gap closed, add capability to draft.
If no: recurse (new gap to resolve).
If unresolvable: fall back to CLARIFY mode (ask user for missing data).
Example: reason can be asked via CLARIFY or defaulted.
Step 6: ASSEMBLE PLAN DRAFT
Runtime: Arrange capabilities in execution order (reversed from chain order).
Wire input bindings based on data flow.
Result: Plan Draft.

Key principle: Plans always succeed. The Planner never builds a plan that the current user cannot execute. If a direct capability is policy-blocked, the Planner finds an alternative that achieves a version of the goal within the user’s permissions. If no alternative exists, the Planner explains why and does not generate a plan. Policy validation after enrichment (by the Validator) still exists as a safety net, but policy-denied plans should be rare exceptions — not the normal flow.

The Planner does not always produce a plan. It has three response modes:

ModeWhenOutput
GENERATEHigh-confidence goal + capabilities resolve all gaps + policy pre-check passes for all capabilitiesPlan Draft
CLARIFYAmbiguous intent, multiple viable paths, unresolvable gaps, missing informationStructured clarification question
CONVERSEExploratory, advisory, learning, no actionable intent, or no executable plan possible (all paths blocked by policy)Conversational response (not a plan)

Decision flow:

Intent arrives
-> Is this actionable? (Does the user want something done?)
-> No: CONVERSE (respond helpfully, explain capabilities, give advice)
-> Yes: Can I identify a clear goal output?
-> No: CLARIFY (ask what they want to achieve)
-> Yes: Can I find a terminal capability with confidence?
-> No match: CONVERSE (explain what's possible, suggest alternatives)
-> Multiple close matches: LLM scores. If still ambiguous: CLARIFY
-> Clear match: POLICY PRE-CHECK -- can this user execute it?
-> Blocked: search for alternative capability (e.g., request_X)
-> Alternative found: use it, adjust goal, continue chaining
-> No alternative: CONVERSE (explain what's not possible, why)
-> Allowed: Start backward chaining
-> At any gap: Can I resolve it?
-> Yes: POLICY PRE-CHECK on bridging capability too
-> No: CLARIFY (ask for the missing piece)
-> All gaps closed: GENERATE (produce Plan Draft)

Two universal fallbacks:

  1. Clarification — if the system is unsure at any point (ambiguous intent, missing data, too many options).
  2. Alternative search — if a capability is policy-blocked, the Planner searches for an alternative before giving up. Only if no alternative exists does it fall back to CONVERSE.

Plans always succeed. Every plan the Planner generates is executable by the current user. If the user’s intent requires capabilities they cannot access, the Planner either finds an alternative path (e.g., submitting a request instead of performing the action directly) or explains why the intent cannot be fulfilled.


The Plan Draft is the minimal format the Planner (LLM) produces. It contains only the decisions the LLM must make: which capabilities to call and how to wire their inputs. Everything else is inferred or computed by Plan Enrichment.

{
"intent": "send a welcome email to user 123",
"goal": "email sent confirmation",
"steps": [
{
"capability": "get_user_by_id",
"inputs": {
"user_id": "$.inputs.user_id"
},
"output": "user"
},
{
"capability": "send_templated_email",
"inputs": {
"to": "$.user.email",
"template_name": "welcome_v2",
"template_vars": {
"name": "$.user.display_name"
}
},
"output": "email_result"
}
]
}
FieldTypeRequiredDescription
intentstringYesThe original user intent (natural language).
goalstringYesThe identified goal output (what the plan produces).
stepsarray of DraftStepYesOrdered list of capability invocations. Sequential by definition.
FieldTypeRequiredDescription
capabilitystringYesCapability name. No version pinning — the enricher resolves the latest compatible version.
inputsobjectYesMaps capability input fields to values. See Section 2.4.
outputstringYesA short name for this step’s output. Used to reference it in subsequent steps.
conditionstringNoNatural language condition (e.g., "if user is premium"). Enrichment converts to structured condition.

Draft bindings are deliberately simpler than Full Plan IR bindings:

SyntaxMeaningExample
$.inputs.<field>Reference to plan input (from intent)$.inputs.user_id
$.<output_name>.<field>Reference to a prior step’s output by name$.user.email
Plain stringLiteral value"welcome_v2"
Plain number/booleanLiteral value3, true

Key differences from Full Plan IR bindings:

  • No $literal wrapper needed. If a value is not a path expression (doesn’t start with $), it’s a literal.
  • No $transform expressions. If the LLM needs a transformation, it should use a capability instead.
  • No $.steps[N] indexing. Only named references ($.<output_name>). Simpler for the LLM to reason about.
  • No $.system.* references. System context is injected by enrichment.

The following fields are never in a Plan Draft — they are added by Plan Enrichment:

FieldAdded By
plan_idEnrichment (UUID generation)
versionEnrichment (initial 1.0.0 or incremented)
nameEnrichment (derived from intent + capabilities)
metadataEnrichment (author, timestamp, lifecycle state)
input_schemaEnrichment (inferred from intent inputs + capability schemas)
output_schemaEnrichment (inferred from terminal step’s output schema)
depends_onEnrichment (computed from data flow analysis)
step_indexEnrichment (assigned from array position)
error_policyEnrichment (default policy, may be overridden by developer or policy)
execution_constraintsEnrichment (computed from aggregate effect classes)
retryEnrichment (default retry for REMOTE capabilities)
Structured conditionEnrichment (converted from natural language condition)

The Planner does NOT need to produce the entire Plan Draft in one shot. It can be built incrementally:

Turn 1: LLM generates step 1 (terminal capability from backward chaining)
Runtime validates: Does this capability exist? Are inputs resolvable?
Turn 2: LLM generates step 0 (gap-filling capability)
Runtime validates: Does this close the gap? Are its inputs available?
Turn N: LLM signals "plan complete" (all gaps closed)
Runtime assembles final draft from accumulated steps, reversed into execution order.

Between each turn, the runtime can provide feedback:

  • “Capability X doesn’t exist. Did you mean Y?”
  • “Input field Z is not available. How should it be obtained?”
  • “Step output type doesn’t match next step’s expected input.”

This makes plan generation a conversation between the LLM and the runtime, not a one-shot generation task.


The Full Plan IR is the complete, execution-ready format. It is produced by Plan Enrichment from a Plan Draft (or authored directly by a developer).

{
"plan_id": "550e8400-e29b-41d4-a716-446655440000",
"version": "1.0.0",
"name": "send_welcome_email",
"description": "Looks up a new user and sends them a welcome email",
"metadata": {
"author": "planner",
"created_at": "2026-02-05T14:30:00Z",
"lifecycle_state": "CANDIDATE",
"tags": ["onboarding", "email"],
"source_draft": { ... }
},
"input_schema": {
"type": "object",
"required": ["user_id"],
"properties": {
"user_id": { "type": "string", "format": "uuid" }
},
"x-zakardo": { "kind": "capability-input", "version": "1.0.0" }
},
"output_schema": {
"type": "object",
"properties": {
"email_sent": { "type": "boolean" },
"email_id": { "type": "string" }
},
"x-zakardo": { "kind": "capability-output", "version": "1.0.0" }
},
"steps": [ ... ],
"error_policy": { ... },
"execution_constraints": { ... }
}
FieldTypeRequiredDescription
plan_idstring (UUID)YesUnique identifier for this plan. Persists across versions.
versionstring (semver)YesVersion of this plan.
namestringYesMachine-readable name. Must match ^[a-z][a-z0-9_]*$.
descriptionstringYesHuman-readable description. Used by the Planner for matching and by the frontend for Plan Preview.
metadataobjectYesSee Section 3.3.
input_schemaJSON SchemaYesSchema for the plan’s required inputs (sourced from the intent).
output_schemaJSON SchemaYesSchema for the plan’s final output.
stepsarray of StepYesThe execution steps. See Section 4.
error_policyobjectNoPlan-level error handling policy. See Section 7.
execution_constraintsobjectNoConstraints on how this plan may be executed. See Section 8.
source_intentstringNoOriginal natural language intent. Preserved for traceability and re-generation.
FieldTypeRequiredDescription
authorstringYes"planner" if generated by the Planner, "developer" if hand-authored.
created_atstring (ISO 8601)YesWhen this version was created.
lifecycle_stateLifecycleState enumYesCurrent lifecycle state.
tagsarray of stringNoSearchable tags for plan discovery.
trust_scorenumber (0.0 - 1.0)NoCurrent trust score. Managed by the Plan Library.
parent_plan_idstring (UUID)NoIf this plan was derived from another (repair, fork), the parent’s ID.
source_draftPlanDraftNoThe original Plan Draft this was enriched from. Preserved for traceability.

Steps are the core of Plan IR. A step is a single node in the execution graph.

{
"step_index": 0,
"name": "lookup_user",
"capability": {
"name": "get_user_by_id",
"version": "^1.0.0"
},
"input_bindings": {
"user_id": "$.inputs.user_id"
},
"output_key": "user",
"condition": null,
"error_handler": null,
"depends_on": []
}
FieldTypeRequiredDescription
step_indexinteger (>= 0)YesUnique index within the plan. Determines order for sequential steps.
namestringYesHuman-readable name for this step. Used in traces, previews, and error messages.
capabilityCapabilityRefYes (unless sub_plan)Reference to the capability to invoke.
sub_planPlanRefNoReference to a sub-plan to invoke instead of a capability. Mutually exclusive with capability.
input_bindingsobjectYesMaps capability input fields to path expressions on the Execution Context. See Section 4.
output_keystringYesKey under which this step’s output is stored in the Execution Context ($.steps[N].out is also available, but output_key provides a named alias: $.named.<output_key>).
conditionConditionNoIf present, this step only executes when the condition is true. See Section 5.
error_handlerErrorHandlerNoStep-level error handling. Overrides plan-level error_policy for this step. See Section 6.
depends_onarray of integerYesStep indices that must complete before this step can start. Computed by Enrichment from data flow analysis. In v1, the Execution Engine ignores this field and executes steps sequentially by step_index. Used for validation, documentation, and future parallel execution.
timeout_msintegerNoMaximum execution time for this step. Overrides plan-level default.
retryRetryPolicyNoRetry policy for this step. See Section 6.3.

A step can invoke a sub-plan instead of a capability:

{
"step_index": 2,
"name": "verify_identity",
"sub_plan": {
"plan_id": "770e8400-e29b-41d4-a716-446655440099",
"version": "^2.0.0"
},
"input_bindings": {
"user_id": "$.steps[0].out.id",
"email": "$.steps[0].out.email"
},
"output_key": "identity_result",
"depends_on": [0]
}

Sub-plan constraints (from the System Architecture):

  • Maximum composition depth: 5 levels.
  • Sub-plan has its own scoped Execution Context. Data passes via input_bindings / output_key only.
  • Sub-plan is validated independently by the Validator.
  • Sub-plan trace is nested within the parent trace.

5. Input Bindings and Data Flow (Full Plan IR)

Section titled “5. Input Bindings and Data Flow (Full Plan IR)”

Input bindings map capability input fields to values in the Execution Context using path expressions (defined in Type System Specification, Section 7).

{
"input_bindings": {
"user_id": "$.inputs.user_id",
"user_name": "$.steps[0].out.name",
"selected_option": "$.steps[1].interaction_response.selected_id",
"tenant": "$.system.user.tenant_id"
}
}

Each key is a field name in the capability’s input schema. Each value is a path expression.

In addition to path expressions, input bindings may contain literal values:

{
"input_bindings": {
"template_name": { "$literal": "welcome_email_v2" },
"send_immediately": { "$literal": true },
"max_retries": { "$literal": 3 }
}
}

The $literal wrapper distinguishes literal values from path expressions (which are always strings).

For simple transformations, input bindings support a $transform syntax:

{
"input_bindings": {
"full_name": {
"$transform": "concat",
"args": ["$.steps[0].out.first_name", { "$literal": " " }, "$.steps[0].out.last_name"]
},
"item_ids": {
"$transform": "map",
"source": "$.steps[0].out.items",
"field": "id"
}
}
}

Supported transforms:

TransformDescriptionArgs
concatConcatenate stringsArray of path expressions and/or literals
mapExtract a field from each item in an arraysource (path to array), field (field name)
filterFilter array items by a conditionsource, field, operator, value
countCount items in an arraysource (path to array)
firstGet the first item from an arraysource (path to array)
coalesceReturn the first non-null valueArray of path expressions
format_dateFormat a timestampsource (path to timestamp), format (format string)

Transforms are intentionally limited. They are NOT a general-purpose expression language. Complex transformations should be implemented as capabilities.

Each step declares an output_key. The step’s output is accessible via two paths:

  • $.steps[N].out — by index (always available)
  • $.named.<output_key> — by name (more readable, used in hand-authored plans)

Both reference the same data.

{ "step_index": 0, "output_key": "user", ... }
{ "step_index": 1, "input_bindings": { "email": "$.named.user.email" }, ... }

A step may have a condition that determines whether it executes:

{
"step_index": 2,
"name": "send_premium_offer",
"capability": { "name": "send_offer", "version": "^1.0.0" },
"condition": {
"operator": "equals",
"left": "$.steps[0].out.account_tier",
"right": { "$literal": "premium" }
},
"input_bindings": { ... },
"output_key": "offer_result",
"depends_on": [0]
}
OperatorDescriptionOperands
equalsStrict equalityleft, right (path or literal)
not_equalsStrict inequalityleft, right
greater_thanNumeric comparisonleft, right
less_thanNumeric comparisonleft, right
containsString contains substring, or array contains itemleft (collection), right (item)
is_nullValue is null or undefinedoperand
is_not_nullValue is not null and not undefinedoperand
andLogical ANDconditions (array of Condition)
orLogical ORconditions (array of Condition)
notLogical NOTcondition (single Condition)
  • If a condition evaluates to false, the step is skipped.
  • A skipped step produces no output. Its output_key is set to null in the Execution Context.
  • Steps that depend on a skipped step: if they reference the skipped step’s output, the Validator checks that their input bindings handle null (either the input field is optional, or a coalesce transform is used).

{
"error_policy": {
"default_behavior": "abort",
"on_step_failure": "abort | skip | retry",
"max_retries": 3,
"retry_delay_ms": 1000,
"retry_backoff": "linear | exponential",
"on_abort": "rollback | compensate | none"
}
}
FieldTypeDescription
default_behaviorenumWhat happens when a step fails: abort (stop the plan), skip (skip and continue), retry (retry the step).
on_step_failureenumOverride for step failure behavior.
max_retriesintegerMaximum retry attempts per step.
retry_delay_msintegerDelay between retries.
retry_backoffenumBackoff strategy: linear (constant delay) or exponential (delay doubles each retry).
on_abortenumWhat happens when the plan aborts: rollback (execute compensation steps), compensate (execute compensation capabilities), none (just stop).

A step can override the plan’s error policy:

{
"step_index": 3,
"name": "send_notification",
"capability": { "name": "send_push", "version": "^1.0.0" },
"error_handler": {
"on_failure": "skip",
"fallback_step": 4
},
"input_bindings": { ... },
"output_key": "notification_result",
"depends_on": [2]
}
FieldTypeDescription
on_failureenumabort, skip, retry, fallback.
fallback_stepintegerIf on_failure is fallback, the step index to execute instead.
max_retriesintegerOverride plan-level max retries.
retry_delay_msintegerOverride plan-level retry delay.
{
"retry": {
"max_attempts": 3,
"delay_ms": 500,
"backoff": "exponential",
"max_delay_ms": 10000,
"retry_on": ["TIMEOUT", "TRANSIENT_ERROR"]
}
}

The retry_on array specifies which error types trigger a retry. Other errors cause immediate failure.

When on_abort is compensate, the plan declares compensation mappings:

{
"error_policy": {
"on_abort": "compensate",
"compensation": {
"0": {
"capability": { "name": "cancel_reservation", "version": "^1.0.0" },
"input_bindings": { "reservation_id": "$.steps[0].out.reservation_id" }
}
}
}
}

Compensation steps run in reverse order (last completed step first) and are best-effort. A compensation step failure does not prevent other compensation steps from running.


{
"execution_constraints": {
"allowed_modes": ["DRY_RUN", "LIVE"],
"max_execution_time_ms": 60000,
"max_steps": 50,
"require_plan_approval": true,
"aggregate_effect_class": "WRITE_EXTERNAL"
}
}
FieldTypeDescription
allowed_modesarray of ExecutionModeWhich execution modes this plan permits.
max_execution_time_msintegerTotal plan execution timeout.
max_stepsintegerMaximum number of steps (prevents runaway generated plans).
require_plan_approvalbooleanIf true, execution pauses for user approval after Plan Preview.
aggregate_effect_classEffectClassThe highest effect class among all capabilities in this plan. Computed by the Validator.

In v1, the Execution Engine executes steps strictly sequentially, one at a time, in step_index order. There is no parallel step execution. Pauses (gates, interactions, retries) block the entire plan.

The depends_on field is still computed by Plan Enrichment and stored in the Full Plan IR for:

  • Documentation: it shows the logical data flow between steps.
  • Validation: the Validator uses it to verify the dependency graph is acyclic and data flow is consistent.
  • Future compatibility: v2 may introduce parallel execution using depends_on to determine which steps can run concurrently.

9.2 Parallelism is Inferred, Not Authored (Future)

Section titled “9.2 Parallelism is Inferred, Not Authored (Future)”

A critical design decision: the Planner (LLM) generates sequential steps only. Parallelism is inferred by Plan Enrichment through data flow analysis.

Why?

  • LLMs are poor at graph reasoning. Asking an LLM to produce depends_on arrays is asking it to build a DAG in its head — a task that requires tracking multiple relationships simultaneously.
  • Sequential generation is trivially correct. Each step follows the previous one. No invalid dependency graphs possible.
  • Parallelism detection is mechanical. If step B doesn’t reference any output from step A, they can run in parallel. This is a deterministic computation the runtime does better than an LLM.
  • The LLM’s job is to decide what to do, not how fast to do it. Optimization is the runtime’s concern.

Given a sequential Plan Draft:

{
"steps": [
{
"capability": "get_user_by_id",
"inputs": { "user_id": "$.inputs.user_id" },
"output": "user"
},
{
"capability": "list_orders",
"inputs": { "user_id": "$.inputs.user_id" },
"output": "orders"
},
{
"capability": "get_preferences",
"inputs": { "user_id": "$.inputs.user_id" },
"output": "preferences"
},
{
"capability": "render_dashboard",
"inputs": { "user": "$.user", "orders": "$.orders", "preferences": "$.preferences" },
"output": "dashboard"
}
]
}

Enrichment performs data flow analysis:

  1. For each step, extract all input references (paths starting with $).
  2. Map each reference to its source step (the step whose output name matches).
  3. Build a dependency graph: step X depends on step Y if any of X’s inputs reference Y’s output.
  4. Assign depends_on based on the graph.

Result:

StepReferencesDepends On
0: get_user_by_id$.inputs.user_id (plan input)[]
1: list_orders$.inputs.user_id (plan input)[]
2: get_preferences$.inputs.user_id (plan input)[]
3: render_dashboard$.user, $.orders, $.preferences[0, 1, 2]

Steps 0, 1, and 2 have no data dependencies on each other — they run in parallel. Step 3 waits for all three.

9.3 Expressing Parallelism in Full Plan IR

Section titled “9.3 Expressing Parallelism in Full Plan IR”

In the enriched Full Plan IR, parallel execution is expressed through the depends_on field:

{
"steps": [
{
"step_index": 0,
"name": "get_user",
"capability": { "name": "get_user_by_id", "version": "^1.0.0" },
"input_bindings": { "user_id": "$.inputs.user_id" },
"output_key": "user",
"depends_on": []
},
{
"step_index": 1,
"name": "get_user_orders",
"capability": { "name": "list_orders", "version": "^1.0.0" },
"input_bindings": { "user_id": "$.inputs.user_id" },
"output_key": "orders",
"depends_on": []
},
{
"step_index": 2,
"name": "get_user_preferences",
"capability": { "name": "get_preferences", "version": "^1.0.0" },
"input_bindings": { "user_id": "$.inputs.user_id" },
"output_key": "preferences",
"depends_on": []
},
{
"step_index": 3,
"name": "compose_dashboard",
"capability": { "name": "render_dashboard", "version": "^1.0.0" },
"input_bindings": {
"user": "$.named.user",
"orders": "$.named.orders",
"preferences": "$.named.preferences"
},
"output_key": "dashboard",
"depends_on": [0, 1, 2]
}
]
}
  1. A step cannot depend on itself.
  2. Circular dependencies are invalid (the Validator rejects them).
  3. A step with depends_on: [] and no data dependencies on prior steps can start immediately (in future parallel execution).
  4. A step with depends_on: [X, Y] starts only after both X and Y have completed successfully (in future parallel execution).
  5. If a dependency step was skipped (due to condition), the dependent step still proceeds (the skipped step’s output is null).
  6. Developers authoring Full Plan IR directly may set depends_on manually. Enrichment only computes it for Planner-generated drafts.

v1 note: The Execution Engine ignores depends_on for scheduling purposes and executes steps strictly by step_index order. These rules become active when v2 introduces parallel execution.


Plan Enrichment is the deterministic runtime process that converts a Plan Draft into a Full Plan IR. It is executed after the Planner produces a complete draft and before the Validator checks it.

Plan Draft
│
├─ Step 1: CAPABILITY RESOLUTION
│ For each step, resolve capability name to a registered capability.
│ Pin to the latest compatible version.
│ Fail if capability not found.
│
├─ Step 2: SCHEMA INFERENCE
│ Read each capability's declared input_schema and output_schema from the Registry.
│ Infer the plan's input_schema from external references ($.inputs.*).
│ Infer the plan's output_schema from the terminal step's output schema.
│
├─ Step 3: BINDING CONVERSION
│ Convert draft binding syntax to Full Plan IR binding syntax:
│ "$.<output_name>.<field>" → "$.named.<output_name>.<field>"
│ Plain literals → { "$literal": value }
│ Validate that all referenced paths exist in source schemas.
│
├─ Step 4: CONDITION CONVERSION
│ Convert natural language conditions to structured Condition objects.
│ Uses the capability's output schema to resolve field references.
│ Example: "if user is premium" → { "operator": "equals",
│ "left": "$.named.user.tier", "right": { "$literal": "premium" } }
│ If ambiguous: flag for clarification (halt enrichment, ask Planner/user).
│
├─ Step 5: DEPENDENCY ANALYSIS
│ Trace data flow through all steps.
│ Compute depends_on for each step.
│ Detect parallelization opportunities.
│ Validate: no cycles, no references to non-existent outputs.
│
├─ Step 6: INDEX ASSIGNMENT
│ Assign step_index values (may reorder for optimal parallel execution).
│ Assign output_key from draft output names.
│
├─ Step 7: METADATA GENERATION
│ Generate plan_id (UUID).
│ Set version to 1.0.0 (or increment if updating existing plan).
│ Derive machine-readable name from intent + capabilities.
│ Set author to "planner", lifecycle_state to "CANDIDATE".
│ Compute aggregate_effect_class from capability effect declarations.
│ Preserve source_draft in metadata for traceability.
│
├─ Step 8: DEFAULT POLICIES
│ Apply default error_policy (abort, no compensation).
│ Apply default retry for REMOTE capabilities.
│ Apply default execution_constraints (all modes allowed, 60s timeout).
│ Compute require_plan_approval from aggregate effect class and policies.
│
└─ Output: Full Plan IR
  • Deterministic. The same Plan Draft + the same Capability Registry state = the same Full Plan IR. Always.
  • Transparent. The source draft is preserved in metadata.source_draft. Every enrichment decision is traceable.
  • Fail-fast. If any enrichment step encounters an unresolvable issue (missing capability, invalid binding, ambiguous condition), it halts and reports the issue. It does not produce a partial Full Plan IR.

Enrichment and Validation are separate steps with different concerns:

ConcernEnrichmentValidation
Does this capability exist?Yes (fail if not)No (trusts enrichment)
Are schemas compatible?Partial (checks references exist)Full (deep schema compatibility)
Are policies satisfied?No (applies defaults)Yes (checks all policies)
Is the DAG valid?Yes (builds it)Yes (verifies it)
Are effect classes safe?No (computes them)Yes (checks against policy)
Is the plan structurally correct?Yes (produces it)Yes (verifies it)

Plan Draft (what the LLM produces):

{
"intent": "send a welcome email to user 123",
"goal": "email sent confirmation",
"steps": [
{
"capability": "get_user_by_id",
"inputs": { "user_id": "$.inputs.user_id" },
"output": "user"
},
{
"capability": "send_email",
"inputs": {
"to": "$.user.email",
"subject": "Welcome to our platform!",
"template": "welcome_v2",
"template_vars": { "name": "$.user.display_name" }
},
"output": "email_result"
}
]
}

Full Plan IR (after enrichment):

{
"plan_id": "550e8400-e29b-41d4-a716-446655440000",
"version": "1.0.0",
"name": "send_welcome_email",
"description": "Looks up a new user by ID and sends them a welcome email",
"metadata": {
"author": "developer",
"created_at": "2026-02-05T14:30:00Z",
"lifecycle_state": "PROMOTED",
"tags": ["onboarding", "email"]
},
"input_schema": {
"type": "object",
"required": ["user_id"],
"properties": {
"user_id": { "type": "string", "format": "uuid" }
}
},
"output_schema": {
"type": "object",
"properties": {
"email_sent": { "type": "boolean" },
"email_id": { "type": "string" }
}
},
"steps": [
{
"step_index": 0,
"name": "lookup_user",
"capability": { "name": "get_user_by_id", "version": "^1.0.0" },
"input_bindings": {
"user_id": "$.inputs.user_id"
},
"output_key": "user",
"depends_on": []
},
{
"step_index": 1,
"name": "send_email",
"capability": { "name": "send_email", "version": "^2.0.0" },
"input_bindings": {
"to": "$.named.user.email",
"subject": { "$literal": "Welcome to our platform!" },
"template": { "$literal": "welcome_v2" },
"template_vars": {
"$transform": "concat",
"args": [
{ "$literal": "{\"name\": \"" },
"$.named.user.display_name",
{ "$literal": "\"}" }
]
}
},
"output_key": "email_result",
"depends_on": [0]
}
],
"error_policy": {
"default_behavior": "abort",
"on_abort": "none"
},
"execution_constraints": {
"allowed_modes": ["SIMULATED", "DRY_RUN", "LIVE"],
"max_execution_time_ms": 30000,
"require_plan_approval": false,
"aggregate_effect_class": "WRITE_EXTERNAL"
}
}

11.2 Plan with Interaction Point: Search and Select Contact

Section titled “11.2 Plan with Interaction Point: Search and Select Contact”

Plan Draft:

{
"intent": "find John and send him a message saying hello",
"goal": "message sent confirmation",
"steps": [
{
"capability": "search_contacts",
"inputs": { "query": "$.inputs.search_query" },
"output": "search_results"
},
{
"capability": "send_direct_message",
"inputs": {
"recipient_id": "$.search_results.interaction_response.selected_contact_id",
"body": "$.inputs.message_body"
},
"output": "message_result"
}
]
}

Full Plan IR:

{
"plan_id": "660e8400-e29b-41d4-a716-446655440001",
"version": "1.0.0",
"name": "find_and_message_contact",
"description": "Searches contacts by name, lets user select one, and sends a message",
"metadata": {
"author": "planner",
"created_at": "2026-02-05T15:00:00Z",
"lifecycle_state": "CANDIDATE",
"tags": ["messaging", "contacts"]
},
"input_schema": {
"type": "object",
"required": ["search_query", "message_body"],
"properties": {
"search_query": { "type": "string" },
"message_body": { "type": "string" }
}
},
"output_schema": {
"type": "object",
"properties": {
"message_sent": { "type": "boolean" },
"recipient": { "type": "string" }
}
},
"steps": [
{
"step_index": 0,
"name": "search_contacts",
"capability": { "name": "search_contacts", "version": "^1.0.0" },
"input_bindings": {
"query": "$.inputs.search_query"
},
"output_key": "search_results",
"depends_on": []
},
{
"step_index": 1,
"name": "send_message",
"capability": { "name": "send_direct_message", "version": "^1.0.0" },
"input_bindings": {
"recipient_id": "$.steps[0].interaction_response.selected_contact_id",
"body": "$.inputs.message_body"
},
"output_key": "message_result",
"depends_on": [0]
}
],
"error_policy": {
"default_behavior": "abort",
"on_abort": "none"
},
"execution_constraints": {
"allowed_modes": ["LIVE"],
"max_execution_time_ms": 120000,
"require_plan_approval": true,
"aggregate_effect_class": "WRITE_EXTERNAL"
}
}

Note: Step 0’s search_contacts capability has an Interaction Spec (declared in the capability definition, not in the Plan IR). The plan references the interaction response via $.steps[0].interaction_response.selected_contact_id. The Plan IR does not repeat the Interaction Spec — it only references the response data.

11.3 Plan with Parallel Steps and Conditionals

Section titled “11.3 Plan with Parallel Steps and Conditionals”

Plan Draft (sequential — LLM doesn’t know about parallelism):

{
"intent": "prepare a customer report for customer 456",
"goal": "compiled customer report",
"steps": [
{
"capability": "get_customer",
"inputs": { "customer_id": "$.inputs.customer_id" },
"output": "profile"
},
{
"capability": "list_customer_orders",
"inputs": { "customer_id": "$.inputs.customer_id" },
"output": "orders"
},
{
"capability": "list_support_tickets",
"inputs": { "customer_id": "$.inputs.customer_id" },
"output": "tickets"
},
{
"capability": "run_premium_analytics",
"inputs": { "customer_id": "$.inputs.customer_id", "order_history": "$.orders" },
"output": "premium_analysis",
"condition": "if customer is premium tier"
},
{
"capability": "compile_customer_report",
"inputs": {
"profile": "$.profile",
"orders": "$.orders",
"tickets": "$.tickets",
"premium_analysis": "$.premium_analysis"
},
"output": "report"
}
]
}

Full Plan IR (after enrichment — notice parallelism detected and conditions structured):

{
"plan_id": "770e8400-e29b-41d4-a716-446655440002",
"version": "2.1.0",
"name": "prepare_customer_report",
"description": "Gathers customer data from multiple sources in parallel and prepares a report. Includes premium analysis for premium tier customers.",
"metadata": {
"author": "developer",
"created_at": "2026-02-05T16:00:00Z",
"lifecycle_state": "PROMOTED",
"tags": ["reporting", "customer"]
},
"input_schema": {
"type": "object",
"required": ["customer_id"],
"properties": {
"customer_id": { "type": "string", "format": "uuid" }
}
},
"output_schema": {
"type": "object",
"properties": {
"report": { "type": "object" }
}
},
"steps": [
{
"step_index": 0,
"name": "get_customer_profile",
"capability": { "name": "get_customer", "version": "^1.0.0" },
"input_bindings": { "customer_id": "$.inputs.customer_id" },
"output_key": "profile",
"depends_on": []
},
{
"step_index": 1,
"name": "get_order_history",
"capability": { "name": "list_customer_orders", "version": "^1.0.0" },
"input_bindings": { "customer_id": "$.inputs.customer_id" },
"output_key": "orders",
"depends_on": []
},
{
"step_index": 2,
"name": "get_support_tickets",
"capability": { "name": "list_support_tickets", "version": "^1.0.0" },
"input_bindings": { "customer_id": "$.inputs.customer_id" },
"output_key": "tickets",
"depends_on": []
},
{
"step_index": 3,
"name": "premium_analysis",
"capability": { "name": "run_premium_analytics", "version": "^1.0.0" },
"input_bindings": {
"customer_id": "$.inputs.customer_id",
"order_history": "$.named.orders"
},
"output_key": "premium_analysis",
"depends_on": [0, 1],
"condition": {
"operator": "equals",
"left": "$.named.profile.tier",
"right": { "$literal": "premium" }
}
},
{
"step_index": 4,
"name": "compile_report",
"capability": { "name": "compile_customer_report", "version": "^1.0.0" },
"input_bindings": {
"profile": "$.named.profile",
"orders": "$.named.orders",
"tickets": "$.named.tickets",
"premium_analysis": {
"$transform": "coalesce",
"args": ["$.named.premium_analysis", { "$literal": null }]
}
},
"output_key": "report",
"depends_on": [0, 1, 2, 3]
}
],
"error_policy": {
"default_behavior": "abort",
"on_abort": "none"
},
"execution_constraints": {
"allowed_modes": ["SIMULATED", "DRY_RUN", "LIVE"],
"max_execution_time_ms": 45000,
"max_steps": 10,
"require_plan_approval": false,
"aggregate_effect_class": "READ"
}
}

Execution graph for this plan:

[0: get_profile] [1: get_orders] [2: get_tickets] <-- parallel
| | |
+--------+-------+ |
| |
[3: premium_analysis] | <-- conditional (premium only)
| |
+----------+--------------+
|
[4: compile_report] <-- joins all results

11.4 Plan with Error Handling and Compensation

Section titled “11.4 Plan with Error Handling and Compensation”

Plan Draft:

{
"intent": "book a trip to Paris from March 10-15 with a $2000 budget",
"goal": "flight and hotel confirmation",
"steps": [
{
"capability": "book_flight",
"inputs": {
"destination": "$.inputs.destination",
"date": "$.inputs.dates.check_in",
"max_price": "$.inputs.budget"
},
"output": "flight"
},
{
"capability": "book_hotel",
"inputs": {
"destination": "$.inputs.destination",
"check_in": "$.inputs.dates.check_in",
"check_out": "$.inputs.dates.check_out",
"max_price": "$.inputs.budget"
},
"output": "hotel"
}
]
}

Note: The Plan Draft does not include error handling or compensation. Enrichment adds default policies and the developer/policy engine can add compensation for WRITE_EXTERNAL capabilities.

Full Plan IR:

{
"plan_id": "880e8400-e29b-41d4-a716-446655440003",
"version": "1.0.0",
"name": "book_travel",
"description": "Books a flight and hotel for a trip. Cancels the flight if hotel booking fails.",
"metadata": {
"author": "developer",
"created_at": "2026-02-05T17:00:00Z",
"lifecycle_state": "PROMOTED",
"tags": ["travel", "booking"]
},
"input_schema": {
"type": "object",
"required": ["destination", "dates", "budget"],
"properties": {
"destination": { "type": "string" },
"dates": {
"type": "object",
"properties": {
"check_in": { "type": "string", "format": "date" },
"check_out": { "type": "string", "format": "date" }
}
},
"budget": { "type": "number" }
}
},
"output_schema": {
"type": "object",
"properties": {
"flight_confirmation": { "type": "string" },
"hotel_confirmation": { "type": "string" }
}
},
"steps": [
{
"step_index": 0,
"name": "book_flight",
"capability": { "name": "book_flight", "version": "^1.0.0" },
"input_bindings": {
"destination": "$.inputs.destination",
"date": "$.inputs.dates.check_in",
"max_price": "$.inputs.budget"
},
"output_key": "flight",
"depends_on": [],
"retry": {
"max_attempts": 2,
"delay_ms": 2000,
"backoff": "exponential",
"retry_on": ["TIMEOUT", "TRANSIENT_ERROR"]
}
},
{
"step_index": 1,
"name": "book_hotel",
"capability": { "name": "book_hotel", "version": "^1.0.0" },
"input_bindings": {
"destination": "$.inputs.destination",
"check_in": "$.inputs.dates.check_in",
"check_out": "$.inputs.dates.check_out",
"max_price": "$.inputs.budget"
},
"output_key": "hotel",
"depends_on": [0]
}
],
"error_policy": {
"default_behavior": "abort",
"on_abort": "compensate",
"compensation": {
"0": {
"capability": { "name": "cancel_flight", "version": "^1.0.0" },
"input_bindings": {
"confirmation_id": "$.named.flight.confirmation_id"
}
}
}
},
"execution_constraints": {
"allowed_modes": ["LIVE"],
"max_execution_time_ms": 120000,
"require_plan_approval": true,
"aggregate_effect_class": "WRITE_EXTERNAL"
}
}

In this plan, if step 1 (book_hotel) fails, the plan aborts and runs compensation for step 0, canceling the flight.


12.1 What Constitutes a Plan Version Change

Section titled “12.1 What Constitutes a Plan Version Change”
ChangeVersion Bump
Fix a description or tagPATCH
Change a literal value in input bindingsPATCH
Add an optional field to input/output schemaMINOR
Add a new step that does not change output schemaMINOR
Remove a stepMAJOR
Change output schema (remove/rename fields)MAJOR
Change input schema (add required field)MAJOR
Change a capability reference to a different capabilityMAJOR
Reorder steps (changing step indices)MAJOR
Change error policyMINOR

The Plan Library computes a fingerprint (SHA-256 hash) of the plan’s structural content (steps, bindings, schemas) excluding metadata (lifecycle state, trust score, timestamps). Two plan versions with the same fingerprint are structurally identical.


The formal JSON Schema for Plan IR is available at:

zakardo://schemas/plan-ir/1.0.0

It validates that a given JSON document is a structurally valid Plan IR. The Validator performs additional semantic checks (schema compatibility, capability availability, policy compliance) that go beyond structural validation.


DecisionResolution
Two-layer formatPlan Draft (LLM output, minimal) + Full Plan IR (enriched, execution-ready)
Plans always succeedThe Planner never builds a plan the user cannot execute. If a capability is policy-blocked, the Planner finds an alternative (e.g., request_X) or explains why.
Policy pre-check during generationBefore committing to any capability, the Planner queries the Policy Engine to verify the user can execute it. Blocked capabilities trigger an alternative search.
Plan generation strategyBackward chaining: goal → terminal capability → policy pre-check → gap analysis → resolve
LLM generates sequential onlySteps are an ordered list. Parallelism is inferred by Plan Enrichment.
Incremental generationDraft built step by step with runtime validation between turns.
Three Planner response modesGENERATE (produce draft), CLARIFY (ask for info), CONVERSE (non-actionable dialogue)
Clarification as universal fallbackAt any decision point, if confidence is too low, fall back to clarification
LLM scoringWhen multiple options exist, LLM scores candidates before falling back to clarification
Serialization formatJSON
Execution graph modelDAG via depends_on (computed by enrichment from data flow analysis)
Data binding syntax (Draft)Simplified: $.<output>.<field>, $.inputs.<field>, plain literals
Data binding syntax (Full IR)Path expressions ($.steps[N].out.field, $.named.<key>.field, $.inputs.field) with $literal and $transform extensions
Conditional execution (Draft)Natural language string (converted by enrichment)
Conditional execution (Full IR)Per-step condition with boolean operators
Error handlingPlan-level default + step-level overrides. Supports abort, skip, retry, fallback, compensation. Applied by enrichment defaults + developer overrides.
Sub-plan invocationVia sub_plan field on a step (mutually exclusive with capability). Scoped context, depth limit 5.
Parallel executionInferred by enrichment from data flow analysis. Expressed via depends_on in Full Plan IR.
VersioningSemver with structural fingerprinting
Interaction PointsNot declared in Plan IR. They are declared on the capability. Plan IR references interaction responses via $.steps[N].interaction_response.
Plan EnrichmentDeterministic runtime process: capability resolution → schema inference → binding conversion → condition conversion → dependency analysis → metadata generation → default policies
Source traceabilityFull Plan IR preserves the source Plan Draft in metadata.source_draft