Workflow

Workflow objects

The schema id and top-level shape of each object. The Registry column reads spec/schemas/registry.json.

SkillGrant

A SkillGrant authorizes an agent to execute a named skill. Where a tool grant authorizes one call, a skill grant binds the whole tool sequence under one authorization and one shared budget envelope.

Schema

The Rust struct is SkillGrant in grant.rs. The optional fields are omitted from the JSON when absent, and a missing strict_ordering deserializes as true.

Step authorization

A step is authorized when "server_id:tool_name" appears in the authorized_steps list. Invocations of tools not in the list MUST be rejected. SkillGrant::authorizes_step makes this check.

Ordering modes

When strict_ordering is true (the default), each step MUST execute at index equal to the number of previously completed steps. A step submitted out of order MUST be rejected with StepOutOfOrder.

When strict_ordering is false (relaxed mode), steps may execute in any order. All steps MUST still be in the authorized_steps list. SkillGrant::is_step_in_order returns true for every index in relaxed mode.

SkillManifest

A SkillManifest is authored by the skill developer and declares the full execution plan for a skill.

Schema

SkillStep

IoContract

An IoContract describes the data that flows between steps. Each list field deserializes as empty when absent.

I/O contract validation

Implementations MUST validate that I/O contracts form a consistent data flow. SkillManifest::validate_io_contracts walks the steps in order and applies these rules:

• For each step after the first, every field in input_contract.required_fields MUST appear in the output_contract.produced_fields of some preceding step.
• The first step's input requirements come from the caller; validation leaves them unchecked.
• A violation reports the step index, the tool name, and the missing field name.

Tool dependencies

The manifest's tool dependencies are the "server_id:tool_name" strings derived from its steps, returned by SkillManifest::tool_dependencies. begin checks every manifest step against the grant before an execution starts.

WorkflowReceipt

A WorkflowReceipt records one skill execution in one signed receipt.

WorkflowReceiptBody

chio.workflow-receipt.v1 is the only workflow receipt schema a verifier accepts. Verifiers MUST reject unknown schema values fail-closed: WorkflowReceipt::verify returns false for any other schema value before it checks the signature.

Signed WorkflowReceipt

The signed WorkflowReceipt inlines every field of WorkflowReceiptBody and adds a signature field, an Ed25519 signature over the canonical JSON of the body. The signature MUST be computed over canonical_json_bytes(body) using RFC 8785 canonical JSON; the crate signs through Keypair::sign_canonical.

The receipt MAY also carry vendor_signatures, a list of WorkflowVendorSignature entries with the camel-case fields vendorId, publicKey, and signature; the list is omitted when empty. Each vendor co-signature signs the same canonical workflow body as the kernel signature. WorkflowReceipt::verify_vendor_signatures takes the required vendor signers and, per signer and in this order, rejects a missing vendor signature, a public key that differs from the required one, and a signature that fails verification.

WorkflowOutcome

The enum serializes with a status tag in snake case; the variant fields sit beside it.

StepRecord

Every optional field is omitted from the JSON when absent. record_step fills tool_receipt_id, cost, and output_hash from its input and leaves the remaining optional fields unset. The specification requires a destructive step to be backed by a live capability lease and a matching governance receipt when the verifier's action-class policy marks the step as receipt-backed.

StepOutcome

StepOutcome serializes as one of four snake-case values:

• success: the step completed successfully.
• denied: policy denied the step.
• failed: the step failed during execution.
• skipped: the workflow aborted before reaching the step.

Signature verification

WorkflowReceipt::verify reconstructs the WorkflowReceiptBody from the receipt fields and verifies the Ed25519 signature over its canonical JSON serialization using the embedded kernel_key. A tampered receipt (any field modified after signing) MUST fail verification.

WorkflowAuthority lifecycle

The host drives the lifecycle: begin once, validate before each tool invocation, record each outcome, and finalize the trace. The authority checks and records. Dispatching tools, authenticating the enclosing capability token, and enforcing a step's I/O schema belong to the host's integration and the tool's kernel execution path.

The WorkflowAuthority holds the kernel signing key, counts the executions it has started, and keeps a per-capability reservation table for grants that carry max_executions. These counters are local to the authority instance and are lost when it is recreated. The signatures below are quoted from the specification; the numbered behavior is the crate's.

begin

begin(manifest, grant, agent_id, capability_id, session_id)
  -> Result<WorkflowExecution, WorkflowError>

Preconditions, checked in this order:

1. grant.skill_id == manifest.skill_id and grant.skill_version == manifest.version. Fail: UnauthorizedSkill.
2. Every step in the manifest MUST be authorized by the grant: grant.authorized_steps contains "step.server_id:step.tool_name" for each step. Fail: UnauthorizedStep.
3. If grant.max_executions is set, the authority reserves one execution for the capability_id; completed plus in-flight executions for that capability MUST be below the limit. Fail: ExecutionLimitReached.

On success the authority increments its execution count and returns a WorkflowExecution with:

• Budget limit from grant.budget_envelope or manifest.budget_envelope (grant takes precedence).
• Time limit from grant.max_duration_secs or manifest.max_duration_secs (grant takes precedence).
• An id of the form wf-{started_at}-{sequence}-{agent_id}, where the sequence is a per-authority counter so two executions begun in the same second get distinct ids.
• active set to true.
• Empty step_records and zero budget_spent.

validate_step

validate_step(execution, step, grant) -> Result<(), WorkflowError>

Preconditions, checked in order:

1. execution.active MUST be true. Fail: InvalidState.
2. The step MUST be authorized by the grant. Fail: UnauthorizedStep.
3. If strict ordering is enabled, step.index == execution.completed_steps(), where completed_steps counts the records whose outcome is success. Fail: StepOutOfOrder.
4. If a time limit is set, elapsed time MUST be less than the limit. Fail: TimeLimitExceeded.

This check does not reserve money for the upcoming call. Budget checks run when the host records the step’s cost. For a spending ceiling that must prevent dispatch, also use the kernel’s budget admission.

record_step

record_step(execution, step, StepExecutionRecordInput {
  outcome, duration_ms, cost, tool_receipt_id, output_hash
})
  -> Result<(), WorkflowError>

The host supplies a StepExecutionRecordInput. The authority records the reported tool receipt id and output hash without checking them against the tool receipt. Behavior:

1. If execution.active is false, return InvalidState.
2. Evaluate, without returning yet: whether the time limit has elapsed; whether cost.currency differs from the currency of step.budget_limit or of the execution budget; and whether cost.units exceeds step.budget_limit.units.
3. Unless the currency mismatched, add cost.units (if present) to execution.budget_spent using saturating addition.
4. Append a StepRecord to execution.step_records. The record is always appended, even when a check below fails, so the finalized receipt carries the offending step.
5. Return the first failure that applies, each of which sets active to false: a currency mismatch returns BudgetCurrencyMismatch and records a Denied outcome; a per-step limit breach returns BudgetExceeded; budget_spent > budget_limit.units returns BudgetExceeded; an elapsed time limit returns TimeLimitExceeded and records a TimedOut outcome.
6. If outcome is failed or denied, set active to false.

finalize

finalize(execution) -> Result<WorkflowReceipt, WorkflowError>

Finalization signs the records supplied to this authority. A Completed outcome means the recorded trace has no failure selected by the rules below. The authority keeps no copy of the manifest's step count, so to judge completeness, compare the recorded steps with the manifest and verify each linked tool receipt.

Behavior, in the order the specification numbers:

1. Set execution.active to false.
2. Determine the WorkflowOutcome, in this precedence:
   • If any step record has outcome failed or denied, the outcome is StepFailed with that step's index.
   • Otherwise a terminal outcome that record_step recorded (Denied, BudgetExceeded, or TimedOut) stands; a time limit that elapsed by finalize time also yields TimedOut.
   • Otherwise, if budget_spent > budget_limit.units, the outcome is BudgetExceeded.
   • Otherwise the outcome is Completed.
3. Construct WorkflowReceiptBody with all execution data: completed_at and duration_ms from the clock, total_cost as budget_spent in the envelope's currency when spend is positive and an envelope exists, and kernel_key as the authority's public key.
4. Sign the body: keypair.sign_canonical(body). Fail: SigningFailed.
5. For a grant with max_executions, move the capability's reservation from in-flight to completed. begin already incremented the authority's execution count.
6. Return the signed WorkflowReceipt.

WorkflowError

Example

Section 7 of spec/WORKFLOW.md pairs the grant in the synopsis with this manifest for the two-step search-and-summarize skill. The second step requires the results field the first step produces, so the manifest passes I/O contract validation:

# Skill Manifest
schema: chio.skill-manifest.v1
skill_id: search-and-summarize
version: "1.0.0"
name: Search and Summarize
steps:
  - index: 0
    server_id: search-srv
    tool_name: search
    label: Search
    output_contract:
      produced_fields: [results]
  - index: 1
    server_id: llm-srv
    tool_name: summarize
    label: Summarize
    input_contract:
      required_fields: [results]
    output_contract:
      produced_fields: [summary]
budget_envelope:
  units: 1000
  currency: USD

Execution flow, in the order the specification lists it:

1. authority.begin(manifest, grant, agent, capability, session): validates that the grant matches the manifest and creates the execution.
2. authority.validate_step(execution, step_0, grant): checks authorization, ordering, and time.
3. Invoke search-srv:search and collect the result.
4. authority.record_step(execution, step_0, Success, 100ms, $0.50): records the cost and checks the budget.
5. authority.validate_step(execution, step_1, grant): checks authorization, ordering, and time.
6. Invoke llm-srv:summarize and collect the result.
7. authority.record_step(execution, step_1, Success, 200ms, $1.00): records the cost and checks the budget.
8. authority.finalize(execution): signs the receipt and completes the execution reservation.

Schema registration

The crate carries chio.skill-grant.v1, chio.skill-manifest.v1, chio.workflow-receipt.v1 as constants in the module that defines each object, outside spec/schemas/registry.json.

The registry's chio-workflow family holds the preflight plan the CLI reads and the report it prints:

CLI command

The help text for chio workflow reads: Validate read-only workflow planning evidence before dispatch. The command plans and validates: it runs no skill, spends no budget, and signs no workflow receipt.

An accepted plan prints a chio.workflow.preflight-report.v1 report with verdict accepted and evidence class planning, and the command exits 0:

$ chio workflow preflight --plan ./valid-plan.json | jq .

{
  "schema": "chio.workflow.preflight-report.v1",
  "id": "workflow-preflight-report-workflow-preflight-valid-child-scope",
  "issued_at": "2026-06-10T00:00:00Z",
  "plan_id": "workflow-preflight-valid-child-scope",
  "verdict": "accepted",
  "evidence_class": "planning",
  "verified_claims": [
    "claim.workflow.preflight_child_scope_bounded",
    "claim.workflow.preflight_planning_only"
  ],
  "rejected_checks": [],
  "live_authority_claims": []
}

A plan whose child task requests an action outside the parent scope is rejected: the command names the rejected check on stderr and exits 1:

$ chio workflow preflight --plan ./broader-plan.json

error[CHIO-KERNEL-OUT-OF-SCOPE-TOOL]: workflow preflight rejected the plan: child task task-child-payment requests payment.capture, which its parent's scope does not grant
  help: narrow task-child-payment to actions its parent grants, or widen the parent's scope in the plan
  code: urn:chio:error:capability:scope-exceeded
  docs: https://chio.computer/docs/reference/errors#error-capability-scope-exceeded

The full option list is in the CLI reference.