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
1. Two-Layer Design
Section titled “1. Two-Layer Design”Plan IR exists in two forms:
| Layer | Produced By | Contains | Purpose |
|---|---|---|---|
| Plan Draft | Planner (LLM) | Capability chain + input bindings | Minimal format the LLM generates. Sequential, no metadata, no schemas. |
| Full Plan IR | Plan Enrichment (runtime) | Everything needed for execution | Complete 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.
1.1 Design Goals
Section titled “1.1 Design Goals”Plan Draft must:
- Be trivially simple. An LLM should be able to produce a valid draft with minimal structural complexity.
- Be sequential. Steps are an ordered list. No graph reasoning required.
- Capture only decisions. Which capabilities to call and how to wire their inputs. Nothing else.
- Support incremental construction. Each step can be generated and validated independently.
Full Plan IR must:
- Be JSON-serializable. Plans are stored, transmitted, and inspected as JSON documents.
- Support all execution constructs. Sequence, parallel, conditional, error handling, gates, interaction points, sub-plan invocation.
- Express data bindings. Steps reference outputs of prior steps via path expressions.
- Be deterministic. Given the same Plan IR and the same inputs, the Execution Engine produces the same execution sequence (modulo external side effects).
- Be inspectable. A human or an LLM can read a Plan IR document and understand what it will do.
- 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?“).
1A.1 Why Backward Chaining
Section titled “1A.1 Why Backward Chaining”- 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.
1A.2 Generation Protocol
Section titled “1A.2 Generation Protocol”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.
1A.3 Planner Response Modes
Section titled “1A.3 Planner Response Modes”The Planner does not always produce a plan. It has three response modes:
| Mode | When | Output |
|---|---|---|
| GENERATE | High-confidence goal + capabilities resolve all gaps + policy pre-check passes for all capabilities | Plan Draft |
| CLARIFY | Ambiguous intent, multiple viable paths, unresolvable gaps, missing information | Structured clarification question |
| CONVERSE | Exploratory, 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:
- Clarification — if the system is unsure at any point (ambiguous intent, missing data, too many options).
- 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.
2. Plan Draft (Planner Output)
Section titled “2. Plan Draft (Planner Output)”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.
2.1 Plan Draft Structure
Section titled “2.1 Plan Draft Structure”{ "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" } ]}2.2 Plan Draft Fields
Section titled “2.2 Plan Draft Fields”| Field | Type | Required | Description |
|---|---|---|---|
intent | string | Yes | The original user intent (natural language). |
goal | string | Yes | The identified goal output (what the plan produces). |
steps | array of DraftStep | Yes | Ordered list of capability invocations. Sequential by definition. |
2.3 Draft Step Fields
Section titled “2.3 Draft Step Fields”| Field | Type | Required | Description |
|---|---|---|---|
capability | string | Yes | Capability name. No version pinning — the enricher resolves the latest compatible version. |
inputs | object | Yes | Maps capability input fields to values. See Section 2.4. |
output | string | Yes | A short name for this step’s output. Used to reference it in subsequent steps. |
condition | string | No | Natural language condition (e.g., "if user is premium"). Enrichment converts to structured condition. |
2.4 Draft Input Binding Syntax
Section titled “2.4 Draft Input Binding Syntax”Draft bindings are deliberately simpler than Full Plan IR bindings:
| Syntax | Meaning | Example |
|---|---|---|
$.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 string | Literal value | "welcome_v2" |
| Plain number/boolean | Literal value | 3, true |
Key differences from Full Plan IR bindings:
- No
$literalwrapper needed. If a value is not a path expression (doesn’t start with$), it’s a literal. - No
$transformexpressions. 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.
2.5 What the LLM Does NOT Generate
Section titled “2.5 What the LLM Does NOT Generate”The following fields are never in a Plan Draft — they are added by Plan Enrichment:
| Field | Added By |
|---|---|
plan_id | Enrichment (UUID generation) |
version | Enrichment (initial 1.0.0 or incremented) |
name | Enrichment (derived from intent + capabilities) |
metadata | Enrichment (author, timestamp, lifecycle state) |
input_schema | Enrichment (inferred from intent inputs + capability schemas) |
output_schema | Enrichment (inferred from terminal step’s output schema) |
depends_on | Enrichment (computed from data flow analysis) |
step_index | Enrichment (assigned from array position) |
error_policy | Enrichment (default policy, may be overridden by developer or policy) |
execution_constraints | Enrichment (computed from aggregate effect classes) |
retry | Enrichment (default retry for REMOTE capabilities) |
Structured condition | Enrichment (converted from natural language condition) |
2.6 Incremental Draft Construction
Section titled “2.6 Incremental Draft Construction”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.
3. Full Plan IR (Enriched Format)
Section titled “3. Full Plan IR (Enriched Format)”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).
3.1 Top-Level Structure
Section titled “3.1 Top-Level Structure”{ "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": { ... }}3.2 Top-Level Fields
Section titled “3.2 Top-Level Fields”| Field | Type | Required | Description |
|---|---|---|---|
plan_id | string (UUID) | Yes | Unique identifier for this plan. Persists across versions. |
version | string (semver) | Yes | Version of this plan. |
name | string | Yes | Machine-readable name. Must match ^[a-z][a-z0-9_]*$. |
description | string | Yes | Human-readable description. Used by the Planner for matching and by the frontend for Plan Preview. |
metadata | object | Yes | See Section 3.3. |
input_schema | JSON Schema | Yes | Schema for the plan’s required inputs (sourced from the intent). |
output_schema | JSON Schema | Yes | Schema for the plan’s final output. |
steps | array of Step | Yes | The execution steps. See Section 4. |
error_policy | object | No | Plan-level error handling policy. See Section 7. |
execution_constraints | object | No | Constraints on how this plan may be executed. See Section 8. |
source_intent | string | No | Original natural language intent. Preserved for traceability and re-generation. |
3.3 Metadata Fields
Section titled “3.3 Metadata Fields”| Field | Type | Required | Description |
|---|---|---|---|
author | string | Yes | "planner" if generated by the Planner, "developer" if hand-authored. |
created_at | string (ISO 8601) | Yes | When this version was created. |
lifecycle_state | LifecycleState enum | Yes | Current lifecycle state. |
tags | array of string | No | Searchable tags for plan discovery. |
trust_score | number (0.0 - 1.0) | No | Current trust score. Managed by the Plan Library. |
parent_plan_id | string (UUID) | No | If this plan was derived from another (repair, fork), the parent’s ID. |
source_draft | PlanDraft | No | The original Plan Draft this was enriched from. Preserved for traceability. |
4. Steps (Full Plan IR)
Section titled “4. Steps (Full Plan IR)”Steps are the core of Plan IR. A step is a single node in the execution graph.
4.1 Step Structure
Section titled “4.1 Step Structure”{ "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": []}4.2 Step Fields
Section titled “4.2 Step Fields”| Field | Type | Required | Description |
|---|---|---|---|
step_index | integer (>= 0) | Yes | Unique index within the plan. Determines order for sequential steps. |
name | string | Yes | Human-readable name for this step. Used in traces, previews, and error messages. |
capability | CapabilityRef | Yes (unless sub_plan) | Reference to the capability to invoke. |
sub_plan | PlanRef | No | Reference to a sub-plan to invoke instead of a capability. Mutually exclusive with capability. |
input_bindings | object | Yes | Maps capability input fields to path expressions on the Execution Context. See Section 4. |
output_key | string | Yes | Key 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>). |
condition | Condition | No | If present, this step only executes when the condition is true. See Section 5. |
error_handler | ErrorHandler | No | Step-level error handling. Overrides plan-level error_policy for this step. See Section 6. |
depends_on | array of integer | Yes | Step 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_ms | integer | No | Maximum execution time for this step. Overrides plan-level default. |
retry | RetryPolicy | No | Retry policy for this step. See Section 6.3. |
4.3 Sub-Plan Steps
Section titled “4.3 Sub-Plan Steps”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_keyonly. - 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)”5.1 Binding Syntax
Section titled “5.1 Binding Syntax”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.
5.2 Literal Values
Section titled “5.2 Literal Values”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).
5.3 Computed Bindings
Section titled “5.3 Computed Bindings”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:
| Transform | Description | Args |
|---|---|---|
concat | Concatenate strings | Array of path expressions and/or literals |
map | Extract a field from each item in an array | source (path to array), field (field name) |
filter | Filter array items by a condition | source, field, operator, value |
count | Count items in an array | source (path to array) |
first | Get the first item from an array | source (path to array) |
coalesce | Return the first non-null value | Array of path expressions |
format_date | Format a timestamp | source (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.
5.4 Output Keys and Named References
Section titled “5.4 Output Keys and Named References”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" }, ... }6. Conditionals
Section titled “6. Conditionals”6.1 Condition Structure
Section titled “6.1 Condition Structure”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]}6.2 Condition Operators
Section titled “6.2 Condition Operators”| Operator | Description | Operands |
|---|---|---|
equals | Strict equality | left, right (path or literal) |
not_equals | Strict inequality | left, right |
greater_than | Numeric comparison | left, right |
less_than | Numeric comparison | left, right |
contains | String contains substring, or array contains item | left (collection), right (item) |
is_null | Value is null or undefined | operand |
is_not_null | Value is not null and not undefined | operand |
and | Logical AND | conditions (array of Condition) |
or | Logical OR | conditions (array of Condition) |
not | Logical NOT | condition (single Condition) |
6.3 Conditional Behavior
Section titled “6.3 Conditional Behavior”- If a condition evaluates to
false, the step is skipped. - A skipped step produces no output. Its
output_keyis set tonullin 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 acoalescetransform is used).
7. Error Handling
Section titled “7. Error Handling”7.1 Plan-Level Error Policy
Section titled “7.1 Plan-Level Error Policy”{ "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" }}| Field | Type | Description |
|---|---|---|
default_behavior | enum | What happens when a step fails: abort (stop the plan), skip (skip and continue), retry (retry the step). |
on_step_failure | enum | Override for step failure behavior. |
max_retries | integer | Maximum retry attempts per step. |
retry_delay_ms | integer | Delay between retries. |
retry_backoff | enum | Backoff strategy: linear (constant delay) or exponential (delay doubles each retry). |
on_abort | enum | What happens when the plan aborts: rollback (execute compensation steps), compensate (execute compensation capabilities), none (just stop). |
7.2 Step-Level Error Handler
Section titled “7.2 Step-Level Error Handler”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]}| Field | Type | Description |
|---|---|---|
on_failure | enum | abort, skip, retry, fallback. |
fallback_step | integer | If on_failure is fallback, the step index to execute instead. |
max_retries | integer | Override plan-level max retries. |
retry_delay_ms | integer | Override plan-level retry delay. |
7.3 Retry Policy
Section titled “7.3 Retry Policy”{ "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.
7.4 Compensation Steps
Section titled “7.4 Compensation Steps”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.
8. Execution Constraints
Section titled “8. Execution Constraints”{ "execution_constraints": { "allowed_modes": ["DRY_RUN", "LIVE"], "max_execution_time_ms": 60000, "max_steps": 50, "require_plan_approval": true, "aggregate_effect_class": "WRITE_EXTERNAL" }}| Field | Type | Description |
|---|---|---|
allowed_modes | array of ExecutionMode | Which execution modes this plan permits. |
max_execution_time_ms | integer | Total plan execution timeout. |
max_steps | integer | Maximum number of steps (prevents runaway generated plans). |
require_plan_approval | boolean | If true, execution pauses for user approval after Plan Preview. |
aggregate_effect_class | EffectClass | The highest effect class among all capabilities in this plan. Computed by the Validator. |
9. Execution Order and Parallelism
Section titled “9. Execution Order and Parallelism”9.1 v1: Sequential Execution
Section titled “9.1 v1: Sequential Execution”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_onto 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_onarrays 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.
9.2 How Enrichment Detects Parallelism
Section titled “9.2 How Enrichment Detects Parallelism”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:
- For each step, extract all input references (paths starting with
$). - Map each reference to its source step (the step whose
outputname matches). - Build a dependency graph: step X depends on step Y if any of X’s inputs reference Y’s output.
- Assign
depends_onbased on the graph.
Result:
| Step | References | Depends 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] } ]}9.5 Execution Graph Rules
Section titled “9.5 Execution Graph Rules”- A step cannot depend on itself.
- Circular dependencies are invalid (the Validator rejects them).
- A step with
depends_on: []and no data dependencies on prior steps can start immediately (in future parallel execution). - A step with
depends_on: [X, Y]starts only after both X and Y have completed successfully (in future parallel execution). - If a dependency step was skipped (due to condition), the dependent step still proceeds (the skipped step’s output is
null). - Developers authoring Full Plan IR directly may set
depends_onmanually. 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.
10. Plan Enrichment
Section titled “10. Plan Enrichment”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.
10.1 Enrichment Pipeline
Section titled “10.1 Enrichment Pipeline”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 IR10.2 Enrichment Guarantees
Section titled “10.2 Enrichment Guarantees”- 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.
10.3 Enrichment vs. Validation
Section titled “10.3 Enrichment vs. Validation”Enrichment and Validation are separate steps with different concerns:
| Concern | Enrichment | Validation |
|---|---|---|
| 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) |
11. Complete Examples
Section titled “11. Complete Examples”11.1 Simple Plan: Draft and Enriched
Section titled “11.1 Simple Plan: Draft and Enriched”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 results11.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. Plan IR Versioning Rules
Section titled “12. Plan IR Versioning Rules”12.1 What Constitutes a Plan Version Change
Section titled “12.1 What Constitutes a Plan Version Change”| Change | Version Bump |
|---|---|
| Fix a description or tag | PATCH |
| Change a literal value in input bindings | PATCH |
| Add an optional field to input/output schema | MINOR |
| Add a new step that does not change output schema | MINOR |
| Remove a step | MAJOR |
| Change output schema (remove/rename fields) | MAJOR |
| Change input schema (add required field) | MAJOR |
| Change a capability reference to a different capability | MAJOR |
| Reorder steps (changing step indices) | MAJOR |
| Change error policy | MINOR |
12.2 Plan Fingerprinting
Section titled “12.2 Plan Fingerprinting”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.
13. Plan IR JSON Schema
Section titled “13. Plan IR JSON Schema”The formal JSON Schema for Plan IR is available at:
zakardo://schemas/plan-ir/1.0.0It 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.
14. Summary of Decisions
Section titled “14. Summary of Decisions”| Decision | Resolution |
|---|---|
| Two-layer format | Plan Draft (LLM output, minimal) + Full Plan IR (enriched, execution-ready) |
| Plans always succeed | The 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 generation | Before 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 strategy | Backward chaining: goal → terminal capability → policy pre-check → gap analysis → resolve |
| LLM generates sequential only | Steps are an ordered list. Parallelism is inferred by Plan Enrichment. |
| Incremental generation | Draft built step by step with runtime validation between turns. |
| Three Planner response modes | GENERATE (produce draft), CLARIFY (ask for info), CONVERSE (non-actionable dialogue) |
| Clarification as universal fallback | At any decision point, if confidence is too low, fall back to clarification |
| LLM scoring | When multiple options exist, LLM scores candidates before falling back to clarification |
| Serialization format | JSON |
| Execution graph model | DAG 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 handling | Plan-level default + step-level overrides. Supports abort, skip, retry, fallback, compensation. Applied by enrichment defaults + developer overrides. |
| Sub-plan invocation | Via sub_plan field on a step (mutually exclusive with capability). Scoped context, depth limit 5. |
| Parallel execution | Inferred by enrichment from data flow analysis. Expressed via depends_on in Full Plan IR. |
| Versioning | Semver with structural fingerprinting |
| Interaction Points | Not declared in Plan IR. They are declared on the capability. Plan IR references interaction responses via $.steps[N].interaction_response. |
| Plan Enrichment | Deterministic runtime process: capability resolution → schema inference → binding conversion → condition conversion → dependency analysis → metadata generation → default policies |
| Source traceability | Full Plan IR preserves the source Plan Draft in metadata.source_draft |