Skip to content

Capability System

This document defines everything about Capabilities: their definition format, metadata, execution contract, lifecycle, interaction specifications, registration, resolution, and packaging. A Capability is the atomic unit of execution in Zakardo — the “instruction” in the plan’s “program.”

Prerequisites: Glossary, System Architecture, Type System, Plan IR


The Capability System must:

  1. Define a complete contract. A capability definition tells you everything: what it takes, what it returns, what side effects it has, where it runs, and what user interaction it needs. No hidden behavior.
  2. Be machine-readable. Capability definitions are structured JSON documents. The Planner reads them to generate plans. The Validator reads them to check plans. Plan Enrichment reads them to infer schemas and parallelism.
  3. Be human-readable. Developers need to author, debug, and review capabilities. The definition must be clear without tooling.
  4. Enable safe composition. Because every capability declares its effect class and boundary, the runtime can reason about the aggregate behavior of a plan before executing it.
  5. Support versioning. Capabilities evolve. The system must handle multiple versions of the same capability running simultaneously.
  6. Enable discovery. The Planner finds capabilities by querying the Capability Registry. Capability definitions must carry enough information for the Planner (and Plan Enrichment) to match, score, and wire capabilities automatically.

A capability definition is a JSON document that fully describes a capability. It is the “source of truth” that gets registered in the Capability Registry.

{
"name": "send_templated_email",
"version": "2.1.0",
"description": "Sends a templated email to a recipient using the email service",
"effect_class": "WRITE_EXTERNAL",
"boundary": "REMOTE",
"input_schema": { ... },
"output_schema": { ... },
"interaction_spec": null,
"anchored_view": null,
"tags": ["email", "communication", "notification"],
"metadata": {
"author": "zakardo-core",
"created_at": "2026-02-05T10:00:00Z",
"deprecated": false,
"deprecation_message": null,
"documentation_url": null
},
"execution": {
"timeout_ms": 30000,
"idempotent": true,
"idempotency_key_path": "$.input.recipient + $.input.template_name + $.input.idempotency_token",
"retry_safe": true
}
}
FieldTypeRequiredDescription
namestringYesUnique capability name. Must match ^[a-z][a-z0-9_]*$.
versionstring (semver)YesCurrent version of this capability.
descriptionstringYesHuman-readable description. The Planner uses this to understand what the capability does and when to select it. Write this like a docstring, not a marketing blurb.
effect_classEffectClass enumYesSide effect declaration. See Section 3.
boundaryBoundary enumYesExecution boundary declaration. See Section 4.
input_schemaJSON SchemaYesSchema for the capability’s input. See Section 5.
output_schemaJSON SchemaYesSchema for the capability’s output. See Section 6.
interaction_specInteractionSpecNoIf present, declares that this capability requires user interaction during execution. See Section 7.
anchored_viewAnchoredViewDefNoIf present, registers a persistent view template for this capability’s output. See Section 8.
tagsarray of stringYesSearchable tags for discovery. Used by the Planner for fuzzy matching and by the Registry for browsing.
metadataobjectYesSee Section 2.3.
constraintsConstraintsDefNoCapability-level governance constraints (role requirements, rate limits, business preconditions). See Section 16A.
alternativesarray of AlternativeRefNoCapabilities that achieve a version of the same goal with different permissions. See Section 16B (Request Pattern).
executionExecutionConfigNoExecution behavior hints. See Section 9.
FieldTypeRequiredDescription
authorstringYesWho published this capability. A pack publisher name or developer identifier.
created_atstring (ISO 8601)YesWhen this version was published.
deprecatedbooleanNoIf true, this version is deprecated. The Planner should prefer non-deprecated versions. Default: false.
deprecation_messagestringNoIf deprecated, a message explaining what to use instead.
documentation_urlstring (URL)NoLink to external documentation for this capability.

Every capability declares exactly one Effect Class. This is the cornerstone of Zakardo’s governance model — the runtime knows what every capability can do before it runs.

Effect ClassMeaningExamples
READReads data without modification. No side effects.Query a database, fetch user profile, search contacts, list orders
WRITE_INTERNALWrites to data owned and controlled by the Zakardo runtime or host application.Update a user preference, save a draft, set a flag
WRITE_EXTERNALWrites to a third-party system or external service not controlled by the host.Send an email, post to Slack, create a Jira ticket, charge a payment
DESTRUCTIVEDeletes, overwrites, or irreversibly modifies data, whether internal or external.Delete an account, cancel an order, revoke API keys, wipe a dataset

Effect classes have a strict severity ordering:

READ < WRITE_INTERNAL < WRITE_EXTERNAL < DESTRUCTIVE

This ordering is used for:

  • Plan aggregate effect class. A plan’s aggregate effect class is the maximum among all its capabilities. A plan with one WRITE_EXTERNAL capability and ten READ capabilities has aggregate effect class WRITE_EXTERNAL.
  • Policy evaluation. Policies can set thresholds (“require approval for WRITE_EXTERNAL or above”).
  • Execution mode compatibility. SIMULATED mode allows only READ. DRY_RUN allows READ and WRITE_INTERNAL. LIVE allows all.
  1. A capability must declare exactly one effect class. Not zero, not multiple.
  2. The effect class must be accurate. A capability that sends emails must not declare READ. The Validator does not verify this (it can’t inspect implementation), but audit and policy enforcement depend on honest declarations.
  3. If a capability’s implementation changes to produce different side effects, the effect class must be updated and the version bumped (MAJOR version change — see Section 12).
  4. Effect class is immutable within a version. Version 2.1.0 of a capability always has the same effect class. If the effect class changes, it’s a new version.

Effect Class and Boundary together form a two-dimensional governance matrix. The Policy Engine uses this matrix to determine the required governance level:

LOCALREMOTEUSER_ENV
READMinimal governance. Log only.Log + trace. May require network policy.Log + trace. May require user consent.
WRITE_INTERNALStandard governance. May require approval gate for sensitive data.N/A (internal write to remote doesn’t make sense).Log + may require user consent.
WRITE_EXTERNALN/A (external write to local doesn’t make sense).High governance. Outbox required. Approval gate likely.Outbox required. User consent likely.
DESTRUCTIVEHigh governance. Approval gate required.Highest governance. Outbox + approval required.Highest governance. Full consent chain.

The Policy Engine evaluates this matrix. The specific policy rules are defined in the Policy and Governance Specification.


Every capability declares exactly one Boundary — where it executes.

BoundaryMeaningExecution Model
LOCALExecutes against data or services internal to the Zakardo runtime or host application.Direct invocation. No Outbox required. Fast, low-latency.
REMOTEExecutes against a third-party service or external API not controlled by the host.Network call. Outbox required for write/destructive effects. May timeout. Retry policies important.
USER_ENVExecutes within a customer-controlled runtime environment (e.g., a user’s browser, a customer’s server).Delegated execution. The runtime sends instructions; the user environment executes. Results are reported back.
  1. A capability must declare exactly one boundary.
  2. Boundary is immutable within a version.
  3. REMOTE boundary capabilities with WRITE_EXTERNAL or DESTRUCTIVE effect class always go through the Outbox (see System Architecture, Section 5.8).
  4. USER_ENV boundary capabilities require special handling: the runtime cannot directly invoke them. They execute via a protocol with the Frontend SDK or a remote agent.
  5. The Planner uses boundary information to estimate execution time and failure risk when scoring plan candidates.

Boundary influences default timeout behavior:

BoundaryDefault TimeoutRationale
LOCAL5,000 msInternal operations should be fast.
REMOTE30,000 msNetwork calls may take longer. Third-party SLAs vary.
USER_ENV120,000 msUser interaction and delegated execution take human-scale time.

These defaults are overridden by the capability’s execution.timeout_ms field and by plan-level execution constraints.


The input schema defines what data a capability accepts. It uses JSON Schema (Draft 2020-12) with Zakardo x-zakardo extensions (defined in the Type System Specification).

{
"input_schema": {
"type": "object",
"required": ["recipient", "template_name", "template_vars"],
"properties": {
"recipient": {
"type": "string",
"format": "email",
"description": "Email address of the recipient"
},
"template_name": {
"type": "string",
"description": "Name of the email template to use",
"enum": ["welcome_v2", "password_reset", "order_confirmation"]
},
"template_vars": {
"type": "object",
"description": "Variables to inject into the email template",
"additionalProperties": { "type": "string" }
},
"idempotency_token": {
"type": "string",
"description": "Optional token to prevent duplicate sends"
}
},
"x-zakardo": {
"kind": "capability-input",
"version": "2.1.0",
"description": "Input for sending a templated email. Requires a recipient email, template name, and template variables."
}
}
}
  1. type must be "object". Capability inputs are always JSON objects (never primitives or arrays at the top level).
  2. required must list all mandatory fields. Optional fields are not listed in required.
  3. Every property must have a description. This is critical — the Planner (LLM) reads descriptions to understand what data to provide.
  4. Every property must have a type. No untyped properties.
  5. additionalProperties should be set explicitly: true (allow extra fields), false (strict), or a schema (typed extra fields). Default if omitted: false (strict).
  6. The x-zakardo.kind must be "capability-input".
  7. The x-zakardo.version must match the capability version.
  8. The x-zakardo.description should be a Planner-friendly summary of the entire input structure. This is what the Planner reads first when deciding whether this capability’s input can be satisfied.
  9. Sensitive fields must be annotated with "x-zakardo": { "sensitive": true } at the property level. This controls trace behavior.

Plan Enrichment uses input schemas to:

  • Validate draft bindings. Check that every binding in the Plan Draft maps to a real field in the capability’s input schema.
  • Infer plan-level input_schema. If the first step references $.inputs.user_id, and the capability’s input expects a UUID, Plan Enrichment knows the plan-level input must include user_id: uuid.
  • Detect type mismatches. If step 2 binds $.user.email to a field expecting an integer, enrichment flags the error before validation.

The output schema defines what data a capability produces on successful execution.

{
"output_schema": {
"type": "object",
"properties": {
"message_id": {
"type": "string",
"description": "Unique ID of the sent email message"
},
"sent_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the email was sent"
},
"delivery_status": {
"type": "string",
"enum": ["queued", "sent", "failed"],
"description": "Current delivery status"
}
},
"x-zakardo": {
"kind": "capability-output",
"version": "2.1.0",
"description": "Output from sending an email. Contains the message ID, send timestamp, and delivery status."
}
}
}
  1. type must be "object". Capability outputs are always JSON objects.
  2. Every property must have a description. The Planner and Plan Enrichment read these to understand what data flows between steps.
  3. The output schema describes the success case only. Error cases are handled by the error model (see Section 10).
  4. The output schema must include all fields the capability may return. Optional fields should use "type": ["string", "null"] or not be listed in required.
  5. x-zakardo.kind must be "capability-output".
  6. Sensitive output fields must be annotated with "x-zakardo": { "sensitive": true }.

Plan Enrichment uses output schemas to:

  • Infer plan-level output_schema. The terminal step’s output schema becomes the plan’s output schema.
  • Validate data flow. If step 2 references $.user.email, enrichment checks that step 1’s output schema has an email property.
  • Detect parallelism. If two steps both only reference $.inputs.* and neither references the other’s output, they can run in parallel.

An Interaction Spec is an optional part of a capability definition that declares the capability requires user interaction during plan execution.

Many real-world tasks require human judgment in the middle of execution:

  • “Search for contacts matching ‘John’” returns multiple results — the user must select one.
  • “Find flights under $500” returns options — the user must compare and choose.
  • “Here’s the draft email” — the user must review before sending.
  • “What date range?” — the user must input a value.
  • “This will delete 2,347 records” — the user must confirm.

Rather than modeling these as separate capabilities or external workflow steps, Zakardo declares them as part of the capability that produces the data. The capability says “I produce data AND I need the user to interact with it before the plan continues.”

{
"interaction_spec": {
"interaction_type": "SELECT",
"description": "User selects one contact from search results",
"data_mapping": {
"source": "$.output",
"presentation_fields": ["name", "email", "company"],
"selection_field": "id"
},
"preferred_blocks": ["SelectList"],
"response_schema": {
"type": "object",
"required": ["selected_contact_id"],
"properties": {
"selected_contact_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the contact the user selected"
}
},
"x-zakardo": {
"kind": "interaction-response",
"version": "1.0.0"
}
},
"constraints": {
"min_selections": 1,
"max_selections": 1,
"allow_skip": false,
"timeout_ms": 300000
}
}
}
FieldTypeRequiredDescription
interaction_typeInteractionType enumYesThe kind of interaction. See Section 7.4.
descriptionstringYesHuman-readable description of what the user is being asked to do. Displayed as a prompt or heading.
data_mappingDataMappingYesHow to map capability output data into the interaction view. See Section 7.5.
preferred_componentsarray of stringNoA2UI catalog component types preferred for rendering this interaction. If omitted, A2UI Composition picks defaults from the Zakardo Standard Catalog for the interaction type.
response_schemaJSON SchemaYesSchema for the data the user’s interaction produces. This is written to the Execution Context at $.steps[N].interaction_response.
constraintsInteractionConstraintsNoLimits on the interaction. See Section 7.6.
TypeUser ActionTypical UIExample
SELECTChoose one or more items from a listSelectList, DataGrid with selectionSelect a contact, pick a template
COMPAREReview multiple options side-by-side and chooseComparisonTableCompare flight options, compare pricing tiers
REVIEWRead data and approve or rejectDetailCard, DocumentViewerReview a draft email, review a report
INPUTProvide freeform dataFormInput, TextArea, DatePickerEnter a date range, type a message
CONFIRMAccept or reject a proposed actionConfirmationCardConfirm deletion, approve a charge

The data_mapping field tells A2UI Composition how to extract the relevant data from the capability’s output and feed it into A2UI components.

FieldTypeRequiredDescription
sourcestring (path expression)YesPath to the data in the capability’s output. Usually "$.output" (the full output) or a sub-path like "$.output.results".
presentation_fieldsarray of stringNoFor list/table interactions: which fields to display. If omitted, all fields are displayed.
selection_fieldstringNoFor SELECT/COMPARE: which field value is captured as the selection. Usually an ID field.
display_formatstringNoHint for how to format data (e.g., "currency", "date", "markdown").
FieldTypeDescription
min_selectionsintegerMinimum number of items the user must select (for SELECT/COMPARE). Default: 1.
max_selectionsintegerMaximum number of items. Default: 1 for SELECT, unlimited for COMPARE.
allow_skipbooleanIf true, the user can skip the interaction (the plan continues with a null response). Default: false.
timeout_msintegerHow long the system waits for user interaction before timing out. Default: 300,000 ms (5 minutes).
default_valueanyDefault response if the user skips or times out. Must conform to response_schema.

When the Execution Engine reaches a step whose capability has an Interaction Spec:

1. Execute the capability (produces data output).
2. Write output to Execution Context at $.steps[N].out.
3. Detect Interaction Spec on the capability.
4. A2UI Composition reads:
- The Interaction Spec (type, data mapping, preferred components, constraints)
- The capability output data from Execution Context
- The Interaction Spec's response schema
5. A2UI Composition produces A2UI messages:
- surfaceUpdate: selects A2UI catalog components (preferred or defaults)
- dataModelUpdate: maps capability output data using data_mapping
- beginRendering: targets the appropriate surface
6. A2UI messages streamed to frontend via SSE.
7. A2UI Renderer renders the interaction on the target surface.
8. User interacts (selects, inputs, confirms, etc.).
9. User action sent to Runtime API (POST /zakardo/executions/:id/interaction/:id).
10. Response validated against response_schema.
11. Response written to Execution Context at $.steps[N].interaction_response.
12. Execution resumes.

The Plan IR does not repeat the Interaction Spec. It is part of the capability definition, not the plan. The plan references the interaction response:

{
"step_index": 1,
"input_bindings": {
"recipient_id": "$.steps[0].interaction_response.selected_contact_id"
}
}

Plan Enrichment resolves $.steps[0].interaction_response.selected_contact_id by checking step 0’s capability for an Interaction Spec and validating that selected_contact_id exists in the response schema.


An Anchored View is an optional declaration that registers a persistent, polished A2UI surface configuration for a capability’s output. Unlike dynamic Ephemeral Views composed at runtime, Anchored Views are pre-designed A2UI component trees registered in advance.

Use an Anchored View when:

  • The capability is called frequently and the output should always look the same (e.g., “show open deals” in a CRM).
  • The output presentation is complex enough that dynamic A2UI composition would produce a mediocre experience.
  • You want a “product-quality” surface, not a dynamically assembled view.

Do NOT use an Anchored View when:

  • The capability output is simple or varies significantly per invocation.
  • Dynamic A2UI composition produces a good enough experience.
  • The view is a one-off interaction (that’s what Ephemeral Views are for).
{
"anchored_view": {
"view_id": "deals_dashboard",
"display_name": "Open Deals",
"description": "Dashboard view showing all open deals with filtering and summary stats",
"surface": "workspace",
"catalog": "zakardo-standard",
"components": [
{
"id": "root",
"component": { "Column": { "children": { "explicitList": ["summary", "deals_table"] } } }
},
{
"id": "summary",
"component": { "StatusBadge": { "text": { "dataPath": "/summary/total_label" } } }
},
{
"id": "deals_table",
"component": {
"DataTable": {
"columns": [
{ "field": "name", "label": "Deal Name" },
{ "field": "value", "label": "Value", "render": "currency" },
{ "field": "stage", "label": "Stage", "render": "StatusBadge" },
{ "field": "close_date", "label": "Close Date", "render": "date" },
{ "field": "owner", "label": "Owner" }
],
"data": { "dataPath": "/deals" },
"sortable": true,
"filterable": true,
"pageSize": 25
}
}
}
],
"route_hint": "/deals"
}
}
FieldTypeRequiredDescription
view_idstringYesUnique identifier for this anchored view. Used by the frontend to match and render.
display_namestringYesHuman-readable name. May be used in navigation or titles.
descriptionstringYesDescription of what this view shows.
surfacestringYesThe A2UI surface to target (e.g., "workspace", "assistant").
catalogstringNoThe A2UI catalog to use. Defaults to the Zakardo Standard Catalog.
componentsarrayYesPre-defined A2UI component tree (adjacency list format per A2UI spec).
route_hintstringNoSuggested URL path for the frontend. Not enforced by the runtime.

When the Execution Engine completes a step and A2UI Composition produces the output:

  1. Check if the capability has an anchored_view declaration.
  2. If yes: use the anchored view’s pre-defined component tree, populate with capability output data via A2UI data binding.
  3. If no: compose an Ephemeral View dynamically using default A2UI components from the Zakardo Standard Catalog.

This is the mechanism described in the System Architecture (Section 3.1, Step 8i).


The execution field provides hints to the Execution Engine about how to invoke this capability.

FieldTypeRequiredDescription
timeout_msintegerNoMaximum execution time. Overrides boundary-based defaults.
idempotentbooleanNoIf true, the capability can be safely retried without duplicate side effects. Default: false.
idempotency_key_pathstringNoIf idempotent is true, a path expression or formula that computes the idempotency key from the input. Used by the Outbox.
retry_safebooleanNoIf true, transient failures can be retried automatically. Default: false. Different from idempotent — a capability can be retry-safe (no harm from retrying) without being idempotent (retry may produce duplicates but that’s acceptable).
estimated_duration_msintegerNoExpected typical execution time. Used by the Planner for plan cost estimation and by the frontend for progress indication.

For REMOTE boundary capabilities with WRITE_EXTERNAL or DESTRUCTIVE effect class:

  • The Outbox uses idempotency_key_path to generate a unique key per invocation.
  • If the same key appears again (e.g., on retry), the Outbox returns the stored receipt instead of re-executing.
  • If idempotent is false, the Outbox still stages the effect but does NOT automatically retry on failure.

Capabilities do not define error schemas in their output. Instead, all capability errors follow a standard error model.

When a capability fails, it returns (or the runtime wraps the failure in) a standard error:

{
"error": {
"code": "RECIPIENT_NOT_FOUND",
"category": "BUSINESS_ERROR",
"message": "No email address found for the specified recipient",
"details": {
"recipient_id": "550e8400-e29b-41d4-a716-446655440000"
},
"retryable": false
}
}
FieldTypeRequiredDescription
codestringYesMachine-readable error code specific to this capability.
categoryErrorCategory enumYesBroad error classification. See Section 10.3.
messagestringYesHuman-readable error message.
detailsobjectNoAdditional context. Free-form, but should be JSON-serializable.
retryablebooleanYesWhether this error may resolve on retry.
CategoryMeaningRetryable?
VALIDATION_ERRORInput data was invalid (bad format, missing required field).No. Fix the input.
BUSINESS_ERRORInput was valid but the operation cannot be performed (not found, already exists, insufficient permissions).No (usually). Application-specific.
TRANSIENT_ERRORTemporary failure (network timeout, rate limit, service unavailable).Yes.
INFRASTRUCTURE_ERRORRuntime or infrastructure failure (database down, memory exhausted).Maybe. Depends on context.
TIMEOUTThe capability exceeded its timeout.Maybe. Depends on context.

Plan IR defines how errors are handled at the plan level and step level (Plan IR Specification, Section 7). The capability’s error retryable flag informs the Execution Engine’s retry decision:

  • If the plan’s retry policy says “retry on TRANSIENT_ERROR” and the capability returns { category: "TRANSIENT_ERROR", retryable: true }, the Execution Engine retries.
  • If the capability returns retryable: false, the Execution Engine does NOT retry regardless of the plan’s retry policy.

The Capability Registry is the runtime’s store of all registered capabilities. It is the “instruction set” that the Planner, Plan Enrichment, Validator, and Execution Engine all read from.

OperationUsed ByDescription
RegisterDeveloper / Pack installationAdd a new capability (or new version) to the registry.
ResolvePlan EnrichmentGiven a capability name (and optional version constraint), return the capability definition.
QueryPlannerSearch capabilities by tags, description, input/output schemas. Used during backward chaining to find capabilities that match a goal or fill a gap.
ListCLI / DashboardList all registered capabilities, optionally filtered.
DeprecateDeveloperMark a capability version as deprecated.
UnregisterDeveloperRemove a capability version. Fails if any PROMOTED plans reference it.

When Plan Enrichment resolves a capability from a Plan Draft:

  1. The Plan Draft contains a capability name (e.g., "send_templated_email"), no version.
  2. Plan Enrichment queries the registry for the latest non-deprecated version.
  3. If found: pins the version in the Full Plan IR (e.g., { "name": "send_templated_email", "version": "^2.0.0" }).
  4. If not found: enrichment fails with a structured error.

When the Validator resolves a capability from Full Plan IR:

  1. The Full Plan IR contains a name and version constraint (e.g., "^2.0.0").
  2. The Validator queries the registry for the latest version matching the constraint.
  3. If found: validation continues.
  4. If not found (capability was removed or all matching versions are deprecated): validation fails.

Capability version constraints use semver ranges:

ConstraintMeaning
"2.1.0"Exact version.
"^2.0.0"Compatible with 2.x.x (>= 2.0.0, < 3.0.0). Preferred for Plan IR.
"~2.1.0"Approximately 2.1.x (>= 2.1.0, < 2.2.0).
">=2.0.0"Any version 2.0.0 or later.
"*"Any version. Not recommended for production plans.

Plan Enrichment always resolves to "^MAJOR.0.0" (compatible range) to allow non-breaking updates. The Validator re-resolves at execution time to get the latest compatible version.

The Planner (during backward chaining) queries the registry to find capabilities. The query interface supports:

Query TypeDescriptionExample
By output schema”Which capabilities produce data matching this schema?”Find capabilities that output { email: string }
By tags”Which capabilities are tagged with these keywords?”Find capabilities tagged ["email", "send"]
By descriptionSemantic search over capability descriptions.”send an email”
By input schema”Which capabilities accept this type as input?”Find capabilities that accept { user_id: uuid }
By effect class”Which capabilities have this effect class?”Find all READ capabilities
By boundary”Which capabilities have this boundary?”Find all LOCAL capabilities
CombinedAny combination of the above.Find REMOTE capabilities that output email data and accept a user_id

The Planner uses these queries during gap analysis to find bridging capabilities. Schema-based querying is particularly important — it enables the runtime to assist the LLM by narrowing the search space before the LLM scores candidates.


ChangeVersion Bump
Fix a description or tagPATCH
Fix a bug in implementation (no schema change)PATCH
Add an optional input fieldMINOR
Add a new output fieldMINOR
Add or change an Anchored ViewMINOR
Change execution config (timeout, retry hints)MINOR
Remove an input fieldMAJOR
Add a required input fieldMAJOR
Remove an output fieldMAJOR
Change a field’s typeMAJOR
Change effect classMAJOR
Change boundaryMAJOR
Change interaction spec’s response schemaMAJOR
Add an Interaction Spec to a capability that didn’t have oneMAJOR
Remove an Interaction Spec from a capability that had oneMAJOR

When a capability has a MAJOR version bump, all plans referencing it with a ^ constraint will NOT pick up the new version (by semver rules). This means:

  • Existing plans continue to work with the old version.
  • New plans generated by the Planner will use the new version.
  • The old version can be deprecated, which prompts plan authors to update.

The Capability Registry may hold multiple versions of the same capability simultaneously. This is required for:

  • Gradual migration (old plans use v1, new plans use v2).
  • A/B testing (shadow plans may use different capability versions).
  • Rollback (if v2 is problematic, v1 is still available).

This section defines how a capability’s implementation is structured. The implementation is the executable code that performs the capability’s work.

Every capability implementation must conform to the following interface:

// @zakardo/types
interface CapabilityContext {
execution_id: string;
execution_mode: 'LIVE' | 'DRY_RUN' | 'SIMULATED' | 'TRAINING';
environment: string; // 'production', 'staging', 'development'
user: {
user_id: string;
tenant_id?: string;
roles: string[];
};
services: Record<string, any>; // Injected Service Providers
trace: TraceWriter; // For recording custom trace entries
error: (code: string, category: ErrorCategory, message?: string) => CapabilityError;
}
type CapabilityFn<I, O> = (input: I, context: CapabilityContext) => Promise<O>;

Where:

  • input is a JSON object conforming to the capability’s input_schema.
  • context provides:
    • Execution metadata: execution ID, mode, environment, user info.
    • Injected services: context.services contains the Service Providers registered in the application configuration, resolved for the current mode and environment. This is how capabilities access databases, external APIs, and other resources.
    • Trace writer: for recording custom entries in the execution Trace.
    • Error factory: for producing standard capability errors.
  • The return is a JSON object conforming to output_schema (success) or a thrown error (failure).

Example implementation:

src/capabilities/customers/get_customer.ts
import { defineCapability } from '@zakardo/runtime';
export default defineCapability(async (input, context) => {
const db = context.services.db; // Injected, mode-aware
const customer = await db.customer.findUnique({
where: { id: input.customer_id },
});
if (!customer) {
throw context.error('CUSTOMER_NOT_FOUND', 'BUSINESS_ERROR');
}
// Data authorization (Layer 4) -- capability's responsibility
if (
context.user.roles.includes('admin') === false &&
customer.assigned_to !== context.user.user_id
) {
throw context.error(
'ACCESS_DENIED',
'BUSINESS_ERROR',
'You can only view customers assigned to you',
);
}
return {
id: customer.id,
name: customer.name,
email: customer.email,
status: customer.status,
assigned_to: customer.assigned_to,
};
});

The capability never imports a database client directly. It receives the right client for the current mode/environment via context.services.db. In production/LIVE, this is the real database. In SIMULATED, this is an in-memory mock. The capability code doesn’t change.

  1. Atomic. A capability either completes fully or fails. No partial results. No mid-execution side effects that persist on failure (unless the capability is explicitly non-transactional, which must be documented).
  2. Idempotent (for side-effecting capabilities). Capabilities with WRITE_INTERNAL, WRITE_EXTERNAL, or DESTRUCTIVE effect class should be designed for at-least-once execution. The Execution Engine may re-execute a step on process recovery (if the process died mid-capability-invocation). Use the idempotency key (context.execution_id + step index) to ensure duplicate calls are no-ops. See examples below.
  3. Input-only. The implementation receives only the data explicitly bound to it via input_bindings. It cannot read other steps’ outputs or the full Execution Context.
  4. No orchestration. A capability does not call other capabilities. It does not generate plans. It does not invoke the Planner. If your logic needs multiple capabilities, that’s a plan.
  5. Effect-honest. The implementation must only perform side effects consistent with its declared effect_class. A READ capability must not write. A WRITE_INTERNAL capability must not call external APIs.
  6. Timeout-aware. The implementation should respect the configured timeout and fail gracefully if approaching it, rather than being killed mid-operation.
  7. Use injected services. Access databases, external APIs, and other resources through context.services, not direct imports. This enables mode-aware execution and tracing.

Idempotency example (WRITE_INTERNAL):

src/capabilities/orders/create_order.ts
export default defineCapability(async (input, context) => {
const db = context.services.db;
const idempotencyKey = `${context.execution_id}:create_order`;
// Upsert with idempotency key -- safe to call twice on recovery
const order = await db.order.upsert({
where: { idempotency_key: idempotencyKey },
create: { ...input, idempotency_key: idempotencyKey, status: 'pending' },
update: {}, // No-op if already exists
});
return { order_id: order.id, status: order.status };
});

Why idempotency matters: The Execution Engine checkpoints after each step completes. If the process dies during a capability invocation (after the DB write but before the checkpoint), the engine will re-execute the step on recovery. Without idempotency, this would create a duplicate order. With the idempotency key, the upsert is a no-op.

Zakardo v1 is TypeScript-first. Capabilities are packaged as TypeScript/JavaScript modules:

BoundaryPackagingExecution
LOCALTypeScript function exported from a moduleLoaded and executed in the Zakardo runtime (Node.js) process
REMOTETypeScript function that calls an external API via HTTPExecuted in the runtime process; the HTTP call is the “remote” part
USER_ENVTypeScript/JavaScript via Frontend SDKExecuted in the user’s browser

REMOTE does not mean the capability runs remotely. A REMOTE-boundary capability is a TypeScript function that runs in the Zakardo runtime and makes HTTP calls to an external service (Stripe, Twilio, a third-party API). The capability is the bridge. It has no visibility into the remote service’s internals.

Future packaging formats (not v1):

FormatWhen
Multi-language (Python, Go) via Capability Execution EngineWhen serverless-style capability isolation is implemented
WebAssembly modulesWhen portable sandboxed execution is needed

Capabilities are distributed as Capability Packs. A pack is a bundle that contains everything needed to use a set of capabilities.

ContentRequiredDescription
Capability definitionsYesOne or more capability definition JSON documents.
ImplementationsYesThe executable code for each capability.
Custom A2UI CatalogNoCustom A2UI component definitions needed by Interaction Specs or Anchored Views.
Anchored View templatesNoPre-designed view templates for capability outputs.
Test fixturesNoExample inputs and expected outputs for each capability.
DocumentationNoREADME, usage examples, integration guides.

Every pack includes a zakardo-pack.json manifest:

{
"pack_name": "email-capabilities",
"pack_version": "1.0.0",
"publisher": "zakardo-official",
"description": "Email sending and management capabilities",
"capabilities": [
{ "name": "send_templated_email", "version": "2.1.0" },
{ "name": "send_raw_email", "version": "1.0.0" },
{ "name": "check_email_status", "version": "1.0.0" }
],
"ui_blocks": [{ "block_type": "EmailPreview", "version": "1.0.0" }],
"anchored_views": [{ "view_id": "email_status_dashboard", "capability": "check_email_status" }],
"dependencies": {
"runtime": ">=1.0.0",
"packs": []
},
"license": "MIT",
"repository": "https://github.com/zakardo/email-capabilities"
}
FieldTypeRequiredDescription
pack_namestringYesUnique pack name. Must match ^[a-z][a-z0-9-]*$.
pack_versionstring (semver)YesVersion of the pack. Distinct from individual capability versions.
publisherstringYesPublisher identifier. Verified in the Registry.
descriptionstringYesHuman-readable pack description.
capabilitiesarrayYesList of capabilities included in this pack.
a2ui_catalogobjectNoCustom A2UI catalog definition included in this pack.
anchored_viewsarrayNoAnchored View templates included in this pack.
dependencies.runtimestring (semver range)YesMinimum Zakardo runtime version required.
dependencies.packsarrayNoOther packs this pack depends on.
licensestringNoLicense identifier (SPDX).
repositorystring (URL)NoSource repository URL.

When a pack is installed:

  1. Runtime verifies the pack signature (if the pack is from the Registry).
  2. Runtime checks dependency compatibility (runtime version, dependent packs).
  3. Each capability definition is registered in the Capability Registry.
  4. Each implementation is loaded into the runtime’s capability executor.
  5. Custom A2UI catalog components are registered in the A2UI Catalog Registry.
  6. Each Anchored View template is registered in the Anchored View Registry.
  7. Existing capabilities with the same name but different (lower) versions are not removed. Both versions coexist.

{
"name": "get_user_by_id",
"version": "1.2.0",
"description": "Retrieves a user record by their unique ID. Returns the full user profile including name, email, account tier, and creation date.",
"effect_class": "READ",
"boundary": "LOCAL",
"input_schema": {
"type": "object",
"required": ["user_id"],
"properties": {
"user_id": {
"type": "string",
"format": "uuid",
"description": "The unique identifier of the user to retrieve"
}
},
"x-zakardo": {
"kind": "capability-input",
"version": "1.2.0",
"description": "Accepts a user ID (UUID) and returns the user's profile."
}
},
"output_schema": {
"type": "object",
"required": ["id", "name", "email"],
"properties": {
"id": { "type": "string", "format": "uuid", "description": "User ID" },
"name": { "type": "string", "description": "User's display name" },
"email": { "type": "string", "format": "email", "description": "User's email address" },
"tier": {
"type": "string",
"enum": ["free", "premium", "enterprise"],
"description": "User's account tier"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the user account was created"
}
},
"x-zakardo": {
"kind": "capability-output",
"version": "1.2.0",
"description": "Full user profile with ID, name, email, account tier, and creation date."
}
},
"interaction_spec": null,
"anchored_view": null,
"tags": ["user", "profile", "lookup", "read"],
"metadata": {
"author": "zakardo-core",
"created_at": "2026-01-15T10:00:00Z"
},
"execution": {
"timeout_ms": 5000,
"idempotent": true,
"retry_safe": true,
"estimated_duration_ms": 50
}
}

15.2 WRITE_EXTERNAL Capability with Interaction Spec: Search and Select Contact

Section titled “15.2 WRITE_EXTERNAL Capability with Interaction Spec: Search and Select Contact”
{
"name": "search_contacts",
"version": "1.0.0",
"description": "Searches contacts by name or email query, presents results to the user for selection. The user must select one contact before the plan continues.",
"effect_class": "READ",
"boundary": "LOCAL",
"input_schema": {
"type": "object",
"required": ["query"],
"properties": {
"query": {
"type": "string",
"description": "Search query (name, email, or partial match)"
},
"max_results": {
"type": "integer",
"description": "Maximum number of results to return",
"default": 20
}
},
"x-zakardo": {
"kind": "capability-input",
"version": "1.0.0",
"description": "Search query to find contacts. Returns matching contacts for user selection."
}
},
"output_schema": {
"type": "object",
"required": ["contacts", "total_count"],
"properties": {
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "format": "uuid", "description": "Contact ID" },
"name": { "type": "string", "description": "Contact name" },
"email": { "type": "string", "format": "email", "description": "Contact email" },
"company": { "type": "string", "description": "Contact's company" }
}
},
"description": "List of matching contacts"
},
"total_count": {
"type": "integer",
"description": "Total number of matches (may be more than returned)"
}
},
"x-zakardo": {
"kind": "capability-output",
"version": "1.0.0",
"description": "List of contacts matching the search query, with total count."
}
},
"interaction_spec": {
"interaction_type": "SELECT",
"description": "Select one contact from the search results",
"data_mapping": {
"source": "$.output.contacts",
"presentation_fields": ["name", "email", "company"],
"selection_field": "id"
},
"preferred_blocks": ["SelectList"],
"response_schema": {
"type": "object",
"required": ["selected_contact_id"],
"properties": {
"selected_contact_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the selected contact"
}
},
"x-zakardo": {
"kind": "interaction-response",
"version": "1.0.0"
}
},
"constraints": {
"min_selections": 1,
"max_selections": 1,
"allow_skip": false,
"timeout_ms": 300000
}
},
"anchored_view": null,
"tags": ["contacts", "search", "select", "crm"],
"metadata": {
"author": "zakardo-crm-pack",
"created_at": "2026-02-01T10:00:00Z"
},
"execution": {
"timeout_ms": 10000,
"idempotent": true,
"retry_safe": true,
"estimated_duration_ms": 200
}
}

15.3 DESTRUCTIVE Capability: Delete User Account

Section titled “15.3 DESTRUCTIVE Capability: Delete User Account”
{
"name": "delete_user_account",
"version": "1.0.0",
"description": "Permanently deletes a user account and all associated data. This is irreversible. Requires confirmation from the user before execution.",
"effect_class": "DESTRUCTIVE",
"boundary": "LOCAL",
"input_schema": {
"type": "object",
"required": ["user_id"],
"properties": {
"user_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the user account to delete"
},
"reason": {
"type": "string",
"description": "Reason for deletion (for audit trail)"
}
},
"x-zakardo": {
"kind": "capability-input",
"version": "1.0.0",
"description": "User ID to delete. Irreversible operation."
}
},
"output_schema": {
"type": "object",
"required": ["deleted", "deleted_at"],
"properties": {
"deleted": { "type": "boolean", "description": "Whether the account was deleted" },
"deleted_at": {
"type": "string",
"format": "date-time",
"description": "When the deletion occurred"
},
"records_removed": {
"type": "integer",
"description": "Number of associated records removed"
}
},
"x-zakardo": {
"kind": "capability-output",
"version": "1.0.0",
"description": "Deletion confirmation with timestamp and count of removed records."
}
},
"interaction_spec": {
"interaction_type": "CONFIRM",
"description": "Confirm permanent deletion of this user account. This action cannot be undone.",
"data_mapping": {
"source": "$.input",
"presentation_fields": ["user_id", "reason"]
},
"preferred_blocks": ["ConfirmationCard"],
"response_schema": {
"type": "object",
"required": ["confirmed"],
"properties": {
"confirmed": {
"type": "boolean",
"description": "Whether the user confirmed the deletion"
}
},
"x-zakardo": {
"kind": "interaction-response",
"version": "1.0.0"
}
},
"constraints": {
"allow_skip": false,
"timeout_ms": 600000
}
},
"anchored_view": null,
"tags": ["user", "account", "delete", "destructive", "admin"],
"metadata": {
"author": "zakardo-core",
"created_at": "2026-02-01T10:00:00Z"
},
"execution": {
"timeout_ms": 30000,
"idempotent": false,
"retry_safe": false
}
}

Note: This capability will also trigger a policy-driven Gate (APPROVAL type) due to the DESTRUCTIVE effect class. The Gate happens before the capability executes. The Interaction Spec’s CONFIRM happens before the destructive action begins. In practice, the user sees: (1) Gate approval (“Do you approve running a plan that deletes a user?”), then (2) Capability confirmation (“Are you sure you want to delete user X?”). The Gate is policy-level governance; the confirmation is capability-level UX.

15.4 REMOTE Capability with Anchored View: List Open Deals

Section titled “15.4 REMOTE Capability with Anchored View: List Open Deals”
{
"name": "list_open_deals",
"version": "1.0.0",
"description": "Fetches all open deals from the CRM for the current user. Returns deal name, value, stage, expected close date, and owner.",
"effect_class": "READ",
"boundary": "REMOTE",
"input_schema": {
"type": "object",
"properties": {
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Filter by deal owner. If omitted, returns all open deals."
},
"min_value": {
"type": "number",
"description": "Minimum deal value filter"
}
},
"x-zakardo": {
"kind": "capability-input",
"version": "1.0.0",
"description": "Optional filters for fetching open deals from CRM."
}
},
"output_schema": {
"type": "object",
"required": ["deals", "total_value"],
"properties": {
"deals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "description": "Deal ID" },
"name": { "type": "string", "description": "Deal name" },
"value": { "type": "number", "description": "Deal value" },
"stage": { "type": "string", "description": "Current pipeline stage" },
"close_date": {
"type": "string",
"format": "date",
"description": "Expected close date"
},
"owner": { "type": "string", "description": "Deal owner name" }
}
},
"description": "List of open deals"
},
"total_value": {
"type": "number",
"description": "Sum of all deal values"
},
"summary": {
"type": "object",
"properties": {
"count": { "type": "integer", "description": "Number of open deals" },
"avg_value": { "type": "number", "description": "Average deal value" },
"nearest_close": {
"type": "string",
"format": "date",
"description": "Nearest expected close date"
}
},
"description": "Summary statistics"
}
},
"x-zakardo": {
"kind": "capability-output",
"version": "1.0.0",
"description": "Open deals list with total value and summary statistics."
}
},
"interaction_spec": null,
"anchored_view": {
"view_id": "open_deals_dashboard",
"display_name": "Open Deals",
"description": "Dashboard showing all open deals with summary statistics and filterable grid",
"template": {
"layout": "dashboard",
"blocks": [
{
"block_type": "SummaryCard",
"data_mapping": { "source": "$.output.summary" },
"position": { "row": 0, "col": 0, "span": 3 }
},
{
"block_type": "DataGrid",
"data_mapping": {
"source": "$.output.deals",
"presentation_fields": ["name", "value", "stage", "close_date", "owner"]
},
"position": { "row": 1, "col": 0, "span": 3 },
"config": {
"sortable": true,
"filterable": true,
"page_size": 25
}
}
]
},
"route_hint": "/deals"
},
"tags": ["crm", "deals", "pipeline", "sales", "dashboard"],
"metadata": {
"author": "zakardo-crm-pack",
"created_at": "2026-02-01T10:00:00Z"
},
"execution": {
"timeout_ms": 15000,
"idempotent": true,
"retry_safe": true,
"estimated_duration_ms": 800
}
}

Capability-level constraints are governance rules declared on the capability itself, separate from system-level policies. They are the capability author’s way of saying “this capability has specific requirements beyond its effect class and boundary.”

While system-level policies (Policy Engine) apply cross-cutting rules about effect classes, boundaries, and tags, capability-level constraints express domain-specific governance that the capability author knows about.

{
"constraints": {
"required_roles": ["admin", "account_owner"],
"rate_limit": {
"max_per_user_per_hour": 10
},
"preconditions": [
{
"description": "User must have an active subscription",
"check": "user.subscription_status == 'active'"
}
]
}
}
ConstraintFieldEvaluated ByEffect on Planner
Role requirementrequired_roles (string array)Planner (pre-generation), Execution Engine (per-step)If the user lacks all required roles, the Planner treats this as a policy block and searches for alternatives.
Rate limitrate_limit (object)Execution Engine (per-step)The Planner does not currently pre-check rate limits. Rate limit violations are returned as BUSINESS_ERROR at execution time.
Preconditionpreconditions (array of condition objects)Execution Engine (per-step)Preconditions depend on runtime data and cannot be pre-checked by the Planner.
SurfaceAuthored ByScopeExamples
System-level policyPlatform operators, tenant adminsCross-cutting”DESTRUCTIVE capabilities require approval gate”, “Candidate plans must run in DRY_RUN first”
Capability-level constraintsCapability authorsPer-capability”Only account_owner or admin can call this”, “Max 10 calls per user per hour”

Both are checked. System policies override capability constraints if there’s a conflict (e.g., a system policy that allows all admin capabilities takes precedence over a capability constraint that requires a specific sub-role).

The Planner reads both during backward chaining. If a capability declares required_roles: ["admin"] and the current user’s roles don’t include “admin”, the Planner treats this identically to a system-level policy DENY: search for alternatives, fall back to CONVERSE if none found.


In an intent-based system, users express what they want in natural language. There are no buttons to hide based on role. If a user says “delete customer ABC-123” and the system generates a deletion plan that policy then rejects, the experience is broken — the user did work, the system did work, all for a rejection.

For any capability that may be policy-restricted (typically WRITE_EXTERNAL, DESTRUCTIVE, or any capability requiring specific roles), capability pack authors should provide a companion request capability:

Direct CapabilityRequest Capability
delete_customer_account (DESTRUCTIVE)request_account_deletion (WRITE_INTERNAL)
apply_discount (WRITE_INTERNAL, gated above threshold)request_discount_approval (WRITE_INTERNAL)
initiate_wire_transfer (WRITE_EXTERNAL)request_wire_transfer (WRITE_INTERNAL)
revoke_api_keys (DESTRUCTIVE)request_api_key_revocation (WRITE_INTERNAL)

The request capability:

  • Has a lower effect class (typically WRITE_INTERNAL) so it’s accessible to more users.
  • Creates a request record in the host application’s data store.
  • Triggers a notification to eligible approvers (via the host application’s notification system).
  • Returns a request ID and status (“submitted”, “pending approval”) as its output.
  • Is tagged with the same domain tags as the direct capability, plus "request".

During backward chaining (see Plan IR Specification, Section 1A.2):

  1. Planner identifies the terminal capability (delete_customer_account).
  2. Policy pre-check: user lacks permission. Blocked.
  3. Planner queries the Capability Registry for alternatives with the same domain tags.
  4. Registry returns request_account_deletion — same tags (["customer", "account", "delete"]), lower effect class.
  5. Planner adjusts the goal: “deletion request submitted” instead of “account deleted.”
  6. Planner builds the plan using the request capability.
  7. Plan always succeeds.

16B.4 Linking Direct and Request Capabilities

Section titled “16B.4 Linking Direct and Request Capabilities”

To help the Planner find alternatives, capabilities may declare an optional alternatives field:

{
"name": "delete_customer_account",
"version": "1.0.0",
"effect_class": "DESTRUCTIVE",
"alternatives": [
{
"capability": "request_account_deletion",
"relationship": "request",
"description": "Submits a deletion request for approval instead of deleting directly"
}
]
}

The alternatives field is optional. Even without it, the Planner can discover alternatives via tag-based and schema-based registry queries. But explicit alternatives make discovery faster and more reliable.

16B.5 Example: Request Capability Definition

Section titled “16B.5 Example: Request Capability Definition”
{
"name": "request_account_deletion",
"version": "1.0.0",
"description": "Submits a request to delete a customer account. The request is routed to a manager for approval. The account is not deleted until approved.",
"effect_class": "WRITE_INTERNAL",
"boundary": "LOCAL",
"input_schema": {
"type": "object",
"required": ["customer_id"],
"properties": {
"customer_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the customer account to request deletion for"
},
"reason": {
"type": "string",
"description": "Reason for the deletion request"
}
},
"x-zakardo": {
"kind": "capability-input",
"version": "1.0.0",
"description": "Customer ID and optional reason for deletion. Creates a pending request."
}
},
"output_schema": {
"type": "object",
"required": ["request_id", "status"],
"properties": {
"request_id": {
"type": "string",
"format": "uuid",
"description": "ID of the created deletion request"
},
"status": {
"type": "string",
"enum": ["submitted", "pending_approval"],
"description": "Current status of the request"
},
"approver_notified": {
"type": "boolean",
"description": "Whether the approver was notified"
},
"estimated_response_time": {
"type": "string",
"description": "Estimated time for approval response"
}
},
"x-zakardo": {
"kind": "capability-output",
"version": "1.0.0",
"description": "Deletion request confirmation with request ID, status, and notification details."
}
},
"interaction_spec": null,
"tags": ["customer", "account", "delete", "request"],
"metadata": {
"author": "zakardo-crm-pack",
"created_at": "2026-02-01T10:00:00Z"
},
"execution": {
"timeout_ms": 5000,
"idempotent": true,
"retry_safe": true
}
}

16C. Capability Design Patterns: The Three Tiers

Section titled “16C. Capability Design Patterns: The Three Tiers”

When users express intents that operate on collections (“email all churned customers”, “delete inactive logs”, “launch a recovery campaign”), the system must handle iteration. In Zakardo, capabilities own their iteration logic — exactly as REST APIs and classic backend applications do.

This mirrors the proven pattern from production systems:

Tier 1: Atomic POST /email → Send one email, return receipt.
Tier 2: Batch POST /email/batch → Send N emails, return receipts[].
Tier 3: Async Job POST /email/campaign → Queue 10K emails, return { job_id }.

The Planner selects the appropriate tier during backward chaining based on intent signals, capability descriptions, and schema compatibility. No changes to Plan IR or the Execution Engine are required.

This is the default — every capability defined in this specification. One input, one output, one invocation.

  • Accepts a single item (an object as defined in Section 5).
  • Returns a single result.
  • Called once per plan step.

When the Planner selects Tier 1: The intent targets a single entity (“send alice an email”, “delete customer ABC-123”).

A batch capability accepts an array as part of its input and processes multiple items within a single plan step execution. The iteration logic lives inside the capability implementation.

Design rules:

  1. Input schema accepts an array field (e.g., recipients: { type: "array", items: { ... }, maxItems: 100 }).
  2. Output schema returns aggregate results (e.g., { sent_count: number, failed: Array<{ item: string, error: string }> }).
  3. maxItems is required on the array field. Batch capabilities must declare their upper bound. The Planner uses this to decide between Tier 2 and Tier 3.
  4. Effect class is the same as the atomic equivalent. A batch send_email_batch is still WRITE_EXTERNAL.
  5. Timeout should reflect the batch size. A batch capability processing up to 100 items should set execution.timeout_ms accordingly.
  6. Naming convention: Use _batch suffix (e.g., send_email_batch, delete_logs_batch).

Example definition:

{
"name": "send_email_batch",
"version": "1.0.0",
"description": "Send the same templated email to multiple recipients. Use for small-to-medium groups (up to 100 recipients). For larger campaigns, use start_email_campaign.",
"effect_class": "WRITE_EXTERNAL",
"boundary": "REMOTE",
"input_schema": {
"type": "object",
"required": ["recipients", "template_name"],
"properties": {
"recipients": {
"type": "array",
"items": { "type": "string", "format": "email" },
"maxItems": 100,
"description": "List of recipient email addresses."
},
"template_name": {
"type": "string",
"description": "Name of the email template to use."
},
"template_vars": {
"type": "object",
"description": "Variables to interpolate into the template."
}
},
"x-zakardo": {
"kind": "capability-input",
"version": "1.0.0",
"description": "Batch email input. Recipients array, template name, and optional template variables."
}
},
"output_schema": {
"type": "object",
"required": ["sent_count", "failed"],
"properties": {
"sent_count": { "type": "number", "description": "Number of emails successfully sent." },
"failed": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recipient": { "type": "string" },
"error": { "type": "string" }
}
},
"description": "List of failed recipients with error details."
}
},
"x-zakardo": {
"kind": "capability-output",
"version": "1.0.0",
"description": "Batch email results with sent count and failure details."
}
},
"tags": ["email", "notification", "batch"],
"alternatives": ["send_email", "start_email_campaign"]
}

Implementation guidance: The capability implementation controls the iteration strategy — Promise.all() for parallel HTTP calls, bulk SQL inserts, provider-native batch APIs (SendGrid, SES), or sequential processing with rate limiting. This optimization is opaque to the plan.

When the Planner selects Tier 2: The intent targets a collection that fits within the batch limit (e.g., “email all 12 churned customers”), and the collection size is known or estimated to be within maxItems.

For operations too large or too slow for synchronous plan execution, an async job capability creates a job record and pushes work to a background queue. The plan step completes immediately with a job_id and status.

This is the pattern used by every production system for large-scale operations: Stripe for payouts, SendGrid for campaigns, Shopify for bulk imports.

Design rules:

  1. Output schema always returns a job reference:
    • job_id: string — unique identifier for tracking.
    • status: string — initial status, always one of "queued", "processing", "completed", "failed".
    • Optionally: estimated_count: number, estimated_duration_ms: number.
  2. Effect class is the same as the operation being queued. A campaign that sends emails is WRITE_EXTERNAL.
  3. Naming convention: Use start_ prefix (e.g., start_email_campaign, start_data_export, start_bulk_update).
  4. The capability implementation must: a. Create a job record in persistent storage (database, job table). b. Push the job to a queue (Redis, SQS, BullMQ, or the application’s job system). c. Return the job_id and status immediately.
  5. The worker (background process) picks up the job, performs the iteration, updates the job status, and records results. Worker implementation is outside Zakardo’s capability system — it lives in the Foundation Layer.
  6. A companion check_job_status capability (Tier 1, READ effect class) should be provided to allow future plans to query job progress.

Example definition:

{
"name": "start_email_campaign",
"version": "1.0.0",
"description": "Queue a bulk email campaign for background processing. Returns immediately with a job ID. Use for large recipient lists (100+). The campaign runs asynchronously; use check_job_status to monitor progress.",
"effect_class": "WRITE_EXTERNAL",
"boundary": "REMOTE",
"input_schema": {
"type": "object",
"required": ["filter", "template_name"],
"properties": {
"filter": {
"type": "object",
"description": "Filter criteria for selecting recipients (e.g., { status: 'churned', region: 'US' })."
},
"template_name": {
"type": "string",
"description": "Name of the email template to use."
},
"template_vars": {
"type": "object",
"description": "Variables to interpolate into the template."
}
},
"x-zakardo": {
"kind": "capability-input",
"version": "1.0.0",
"description": "Campaign parameters. Filter selects recipients, template defines content."
}
},
"output_schema": {
"type": "object",
"required": ["job_id", "status"],
"properties": {
"job_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the queued campaign."
},
"status": {
"type": "string",
"enum": ["queued", "processing", "completed", "failed"],
"description": "Current status of the campaign."
},
"estimated_count": { "type": "number", "description": "Estimated number of recipients." }
},
"x-zakardo": {
"kind": "capability-output",
"version": "1.0.0",
"description": "Campaign job reference with status and estimated recipient count."
}
},
"tags": ["email", "campaign", "async", "batch"],
"alternatives": ["send_email_batch", "send_email"]
}

When the Planner selects Tier 3: The intent signals large-scale operations (“launch a campaign”, “export all data”, “bulk update”), or the estimated collection size exceeds the batch capability’s maxItems.

Complex batch operations that require multiple capability invocations per item (e.g., “for each customer, look up their deals and send a personalized email”) are implemented as composite async job capabilities.

The capability implementation internally orchestrates the multi-step logic within the worker:

// Worker: process_personalized_campaign
async function processJob(job: PersonalizedCampaignJob) {
const customers = await db.customers.findMany({ where: job.filter });
for (const customer of customers) {
const deals = await db.deals.findMany({ where: { customer_id: customer.id } });
await emailService.send({
to: customer.email,
template: job.template_name,
vars: { name: customer.name, top_deal: deals[0]?.name },
});
}
}

This follows the same pattern used in classic applications: complex batch logic lives in a worker, not in the API router or orchestration layer. The plan remains a simple two-step sequence: filter → start_campaign.

The Planner does not need special “loop reasoning.” It selects the appropriate tier using the same backward chaining and capability scoring already defined in Section 3.5 of the Planner Specification.

Selection signals:

SignalTier 1 (Atomic)Tier 2 (Batch)Tier 3 (Async Job)
Intent language”send alice an email""email all churned customers""launch a campaign to 5K users”
Collection indicatorsNo collection words”all”, “every”, “each”, small counts”campaign”, “bulk”, “export”, large counts
Prior step outputProduces a single itemProduces an array (compatible with maxItems)Produces an array (exceeds maxItems or unknown size)
Description match”Send a single email""Send email to multiple recipients (up to 100)""Queue a bulk campaign for background processing”

The capability description and alternatives fields are the primary mechanism for tier selection. A well-described capability naturally attracts the right intents. The alternatives field (Section 11) enables the Planner to fall back between tiers.

16C.7 Relationship to Plan IR and Execution Engine

Section titled “16C.7 Relationship to Plan IR and Execution Engine”

This pattern requires no changes to the Plan IR or Execution Engine specifications:

  • Plan IR: Steps remain flat and sequential. A batch capability is a single step that happens to process an array internally. An async job capability is a single step that returns a job reference.
  • Execution Engine: The engine invokes the capability, receives the output, and advances. Whether that output is { receipt } (Tier 1), { sent_count, failed[] } (Tier 2), or { job_id, status } (Tier 3) is transparent to the engine.
  • Outbox: Batch and async capabilities that produce external effects use the Outbox as usual. Each committed effect gets its own outbox entry.

| Decision | Resolution | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Capability definition format | JSON document with required name, version, description, effect class, boundary, input/output schemas, and tags | | Effect classes | Four levels: READ < WRITE_INTERNAL < WRITE_EXTERNAL < DESTRUCTIVE. Exactly one per capability. Immutable within a version. | | Boundaries | Three types: LOCAL, REMOTE, USER_ENV. Exactly one per capability. Immutable within a version. | | Governance model | Two-dimensional matrix: Effect Class x Boundary. Policy Engine evaluates both. | | Input/output schemas | JSON Schema Draft 2020-12 with x-zakardo extensions. Always objects. Every field described. | | Interaction Specs | Optional, declared on the capability. Five types: SELECT, COMPARE, REVIEW, INPUT, CONFIRM. Response schema defines what flows into Execution Context. | | Anchored Views | Optional, declared on the capability. Pre-designed view templates for consistent rendering of common outputs. | | Error model | Standard structure: code, category (5 types), message, details, retryable flag. Not part of output schema. | | Versioning | Semver. Schema changes follow strict rules. Multiple versions may coexist in the registry. | | Plan Enrichment integration | Enrichment resolves capability names, reads schemas for inference and validation, pins versions. The Planner never generates schemas. | | Registry querying | Supports search by output schema, input schema, tags, description, effect class, boundary, alternatives, and combinations. Used by Planner during backward chaining. | | Request Pattern | For gated/restricted capabilities, pack authors should provide companion request capabilities (lower effect class, creates a pending request). The Planner discovers these via alternatives field or tag-based search. | | Plans always succeed | The Planner checks policy before selecting capabilities. If blocked, it finds alternatives (request pattern). Plans are never built with capabilities the user cannot execute. | | Capability-level constraints | Declared on the capability: role requirements, rate limits, preconditions. Read by Planner during pre-generation check. Complements system-level policy. | | Context injection | Capabilities receive services via context.services, not direct imports. Enables mode-aware execution, tracing, and testability. | | TypeScript-first | v1 capabilities are TypeScript modules. REMOTE capabilities are TS functions calling external APIs. Multi-language support is a future direction. | | Implementation contract | execute(input, context) -> Output | Error. Atomic, input-only, no orchestration, effect-honest, uses injected services. | | Packaging | Capability Packs: bundles with definitions, implementations, optional custom A2UI catalogs, Anchored Views, and test fixtures. Manifest in zakardo-pack.json. | | Idempotency | Declared per capability. Outbox uses idempotency key for REMOTE + write/destructive effects. | | Three-tier design patterns | Capabilities handle iteration: Tier 1 (Atomic) for single items, Tier 2 (Batch, _batch suffix) for small-to-medium collections with maxItems, Tier 3 (Async Job, start_ prefix) for large-scale background work. No Plan IR or Execution Engine changes required. |


QuestionDeferred To
What are the complete schemas for all Zakardo Standard A2UI Catalog components?Frontend Architecture Specification
How are Capability Packs signed and verified?Registry and Marketplace Specification
What is the trust scoring model for capabilities?Plan Library and Lifecycle Specification
How does the USER_ENV boundary protocol work?Execution Engine Specification
How are remote HTTP capabilities authenticated?Runtime API and SDK Specification
What are the default policy rules for each governance matrix cell?Policy and Governance Specification