Declare a unified operation

A unified operation is one logical SDK or MCP operation that calls several provider operations, waits for declared dependencies, and compensates the successful ones when a later step fails. The caller makes one call; the ordering, mapping, and unwinding happen in the Engine.

Unified operations work in TypeScript or Python kind: sdk configs and in kind: mcp configs. Go SDK generation does not support them. MCP exposes each token-authorized authored name through search_docs and executes it through the existing execute tool.

They wrap operations already selected in services. They grant no new scope and carry no credentials.

To draft a sequential operation from a goal, use prompt. It resolves exact provider operations and shows the proposed order, inputs, mappings, and output before apply. You can still author the full configuration directly below.

The shape

unified_operations sits at the top level, beside services:

apiVersion: fused/v1
kind: sdk
name: issues
version: "1.0.0"
language: typescript
services:
  github: {operations: [createIssue, deleteIssue]}
  gitlab: {operations: [createIssue]}

unified_operations:
  issues.create:
    input:
      type: object
      required: [title]
      properties: {title: {type: string}}
    bindings:
      github:
        operation: createIssue
        input: {title: "${input.title}"}
        rollback: {operation: deleteIssue, input: {id: "${response.github.id}"}}
      gitlab: createIssue

For MCP, use kind: mcp, omit language, and keep the same unified_operations block. In an SDK, dot-separated names become the generated namespace: issues.create produces sdk.unified.issues.create. MCP preserves issues.create as the exact operation name returned by search_docs and accepted by execute.

Operation properties

Property	Required	What it does
`input`	Yes	JSON Schema for the logical operation’s public input
`bindings`	Yes	Map of step names to selected provider operations; max 16
`output`	No	Final projection. Its constructed object becomes the exact return value
`description`	No	Metadata retained with the immutable definition

An SDK or MCP app version may declare at most 64 unified operations.

Binding properties

A binding is either a bare operation ID or an expanded object.

bindings:
  gitlab: createIssue          # compact: step key also selects the service
  github:                      # expanded
    service: github
    operation: createIssue
    input: {title: "${input.title}"}
    depends_on: [gitlab]
    rollback:
      operation: deleteIssue
      input: {id: "${response.github.id}"}

Property	What it does
`service`	The configured service key. Omitted, it defaults to the binding key
`operation`	Exact case-sensitive `operationId`, already selected for that service
`input`	Maps unified input and direct dependency responses into the provider request
`depends_on`	Makes this step wait for the named steps
`rollback.operation`	An operation on the same service that compensates this one
`output`	Optional projection for this step’s result

Each binding key is a unique step name used by depends_on, response references, caller targets, and the returned result.target. It does not have to match a service key — several steps may use one service, and they stay separate steps with separate results. Quote a provider-qualified service that starts with @, like "@acme/github".

How execution runs

Steps run as their dependencies settle, several at a time. Once every forward call has finished, rollback runs in reverse dependency order. A failed step compensates only its successful direct dependencies that declare rollback.

An output-mapping error happens after the provider call succeeded, so it neither triggers rollback nor blocks dependants.

depends_on values must be exact binding keys — self-dependencies, duplicates, unknown targets and cycles are all rejected. There is no on_failure; application code owns fallback.

Mapping values

Values in bindings.<step>.input, rollback.input, and output projections can reference the operation’s input and earlier responses. Operation-level input is plain JSON Schema. A complete reference keeps its JSON type — `${response.drive.files}` stays an array — while a reference mixed into a string interpolates. Two operators are available: ?? takes the first non-null value, and a trailing ? omits a missing one. What each location may read:

Location	Can reference
`bindings.<step>.input`	`input.`, `target`, and `response.<direct-dependency>.`
`rollback.input`	`input.`, `target`, and that step’s own `response.<step>.`
Operation `output`	`input.` and `response.<declared-target>.` after bindings settle
Binding `output`	`input.`, `target`, and that binding’s raw `response.<step>.`

Shaping the return value

Without output, the call returns the all-settled {results, rollbacks} envelope. With it, your constructed object is the return value — no data wrapper, no envelope.

    output:
      type: object
      required: [primary_id, title, provider_ids]
      properties:
        primary_id: "${response.github.id}"
        title: "${response.github.issue.title}"
        provider_ids:
          type: array
          value: ["${response.github.id}", "${response.gitlab.iid}"]
          items: {type: string}

Binding outputs run first and become the response values the operation output reads. Scalar shorthand infers its type from the authored JSON scalar; expanded scalars use {type, value}. Arrays take one value plus optional schema-only items. The {schema, mapping} form is invalid — use only the recursive output tree.

Plan before you apply

Plan validates the local config before its first Engine request, so one command covers both the recursive output contract and the remote change preview:

# SDK
fused-cli sdk plan -f .fused/sdks/issues.yaml --no-input --json

# MCP
fused-cli mcp plan -f .fused/mcps/issues.yaml --no-input --json

Use the standalone validate commands only for offline checks that must not contact an Engine. Unified operations live inside an immutable SDK or MCP app version like everything else. Changing one under an existing version returns app_version_immutable — publish a new version.

Call a unified operation

Targets, selectors, and reading the results envelope.

Get Started

Guides

Advanced

Reference

Declare a unified operation

The shape

Operation properties

Binding properties

How execution runs

Mapping values

Shaping the return value

Plan before you apply

Call a unified operation

​The shape

​Operation properties

​Binding properties

​How execution runs

​Mapping values

​Shaping the return value

​Plan before you apply

Call a unified operation

The shape

Operation properties

Binding properties

How execution runs

Mapping values

Shaping the return value

Plan before you apply