Connector Manifest Overview

This section is informative.

A connector manifest describes the integration surface that Workfiles can use. It is a portable contract between workflow authors, validators, executors, connector implementations, and deployments. It names actions and triggers, describes their inputs and outputs, and states the operational promises an executor needs in order to handle retries, ambiguity, dry runs, validation, and external effects safely. A manifest is not connector code and does not contain an endpoint, account, access token, or implementation-specific transport recipe.

Several implementations can realize the same manifest, and several deployment connections can configure different accounts for one connector. Portability comes from preserving the published contract while leaving those implementation and deployment choices outside the workflow.

Connectors and Actions

A connector is a named integration contract, such as helpdesk. Its namespace qualifies every action and trigger it publishes. An action is one operation a step can invoke, such as helpdesk.new_ticket. A trigger is an event source a deployment can activate, such as helpdesk.ticket_updated.

The connector manifest defines what these names mean at the Workfile boundary. An implementation behind that boundary might use an HTTP API, a local SDK, a database transaction, or a host application callback. That choice does not change the evaluated arguments, classified outcomes, declared results, or external effects described by the connector contract.

The executor sits between the workflow and connector implementation. It validates arguments, selects the deployment connection, supplies credentials outside workflow scope, applies dry-run and retry policy, fixes idempotency keys, dispatches attempts, validates promised outputs, and turns connector responses into standardized step outcomes. A remote tool gateway can perform some of that work, but the implementation claiming Workfile conformance remains responsible for the behavior at its boundary.

Meaningful reusable operations, rather than raw fragments of transport machinery, make suitable connector actions. An action can internally paginate, transact, or batch when that is part of delivering its declared result. Exposing transport cursors or per-record mechanics unnecessarily pushes integration concerns into every Workfile and weakens portability.

Manifests as Operational Contracts

An action declaration answers more than “what parameters does this function take?” It provides the information needed to reason safely about execution:

• Input and output declarations let validators check action calls and later expression paths. Required fields, defaults, enums, patterns, object schemas, and sensitive fields make the boundary explicit.
• The error table maps connector-specific codes to retryable, fatal, or unknown. This separates integration vocabulary from Workfile’s common consequences.
• The retry declaration supplies a default schedule for definite retryable failures. It does not make an ambiguous operation safe to repeat.
• Idempotency states whether repeating an action is inherently safe, safe only with a stable caller-supplied key, or not promised safe. This matters most when an acknowledgement is lost and the executor cannot tell whether an external change occurred.
• effects distinguishes reads from possible writes. Dry-run behavior can then suppress writes or delegate to a connector that explicitly promises a noncommitting simulation.
• deterministic says whether equal declared inputs and context promise equal results, which controls safe caching. validated_output says whether every successful result is promised to satisfy the output declaration, which supports runtime enforcement and stronger static reasoning.

These declarations are promises by the connector, not facts an executor can derive from a request schema. A falsely declared idempotency or effects property can cause external harm even when the Workfile is valid. Deployments therefore need to trust the catalogs and implementations from which manifests are resolved.

The manifest also constrains the connector. An implementation cannot return undeclared shapes while claiming validated output, relabel an ambiguous result as a definite failure, or perform a write through an action declared as a read. A newer compatible manifest version can add optional surface area, but it cannot silently weaken promises on which existing Workfiles rely.

Connections and Credentials

A manifest describes what configuration a connection needs, but not any particular configured connection. For example, a helpdesk connector might declare a subdomain field and OAuth scopes. A deployment then creates connections such as an organization’s production and sandbox accounts, each with its own field values, credentials, granted scopes, and optional schema overlay. Workfiles can select a connection where the language permits, but they cannot read its contents. Credentials and Sensitive Values defines the isolation rule and the connector implementation’s access to selected connection authority.

Connection selection before activation or execution is governed by Deployment Connections. A missing required field, ambiguous default, incompatible connector version, or absent required scope makes the workflow unsupported by that deployment rather than producing a failed run. These are configuration problems that can be discovered before an external operation begins.

Schema overlays handle a related deployment concern. Some integrations have tenant-defined fields whose names and types differ by account. A manifest can mark a schema as connection-defined, and the selected connection’s overlay refines that region for static validation. The Workfile still sees typed data, while the vendor manifest avoids pretending that one global schema describes every tenant.

The Role of a Catalog

A catalog publishes immutable, versioned connector manifests and filter packages under namespaces. It is a source of integration contracts, not a source of credentials or workflow policy.

Catalog discovery, hosting, authentication, and version-selection interfaces are intentionally outside the format. During resolution, symbolic references in a Workfile are matched to exact artifact versions and content digests. All references to one namespace in a workflow graph select one exact manifest. The resulting resolution is what validation and execution share.

Pinning matters because a change in an action schema, filter implementation, error classification, or idempotency promise can change whether a workflow is valid or safe. Canonical namespaces resolve to the Standard Library edition coupled to the selected Standard revision.

Vendor namespaces belong to their publishers and carry only the semantics in their resolved artifacts. A catalog cannot replace or augment a canonical artifact, publish credentials, select a deployment connection, or grant an execution capability.

A deployment can use several catalogs, a private catalog, or no networked catalog at all. Regardless of transport, equal namespace, exact version, and digest identify the same artifact content.

Catalog content remains untrusted until its document form, namespace ownership, identity, and any required fixtures have been verified.

A Complete Connector Manifest

This example publishes one keyed-idempotency write action, one read action, and one external trigger. It is illustrative; the normative Connector Manifests section defines every field and compatibility rule.

manifest: 1
connector: helpdesk
version: 2.1.0

auth:
  type: oauth2
  scopes: [profile.read]

connection:
  subdomain:
    type: string
    required: true
    source: user
    prompt: Helpdesk subdomain
    in: host
    pattern: "^[a-z0-9-]+$"

schemas:
  ticket:
    type: object
    required: [event_id, id, status, external_id]
    properties:
      event_id: { type: string }
      id: { type: string }
      status: { type: string, enum: [open, pending, closed] }
      external_id: { type: string }

actions:
  new_ticket:
    scopes: [tickets.write]
    input:
      subject: { type: string, required: true, maxLength: 255 }
      body: { type: string }
      external_id: { type: string, required: true }
    output:
      id: { type: string, required: true }
      url: { type: string, required: true }
      status: { type: string, enum: [open, pending, closed], required: true }
    errors:
      400: { class: fatal }
      429: { class: retryable }
      "5xx": { class: retryable }
    retry:
      attempts: 3
      backoff: exponential
      initial: 1s
      max: 1m
      honor_retry_after: true
    idempotency: keyed
    idempotency_input: external_id
    effects: write
    deterministic: false
    validated_output: true

  get_ticket:
    scopes: [tickets.read]
    input:
      id: { type: string, required: true }
    output: { $ref: "#/schemas/ticket" }
    errors:
      404: { class: fatal }
      429: { class: retryable }
      "5xx": { class: retryable }
    retry: { attempts: 3, backoff: exponential, initial: 1s, max: 1m }
    idempotency: inherent
    effects: read
    deterministic: false
    validated_output: true

triggers:
  ticket_updated:
    kind: external
    scopes: [tickets.read]
    binds: ticket
    output: { $ref: "#/schemas/ticket" }
    delivery_id: event_id
    correlate_on: [id, external_id]

The identity at the top says that this is connector-manifest format 1, for connector namespace helpdesk, artifact version 2.1.0. It does not say where a helpdesk service lives.

The connection declaration tells a deployment which account-specific value is needed and constrains how it can contribute to a host. new_ticket is a possible write.

Its required external_id doubles as the idempotency input: a Workfile invoking it supplies an idempotency_key, and the executor fixes that value across safe reissues. Definite rate-limit and server failures can follow the declared retry schedule.

An uncovered error remains ambiguous; retry policy alone does not authorize repeating an unknown write. get_ticket is an inherent read and returns the named ticket schema.

It is not declared deterministic because the external ticket can change between equal requests. It does promise validated output, so a successful result that violates the schema is a broken connector result rather than a new ad hoc shape.

The trigger publishes an external event whose payload uses the same schema. event_id supplies delivery identity for deduplication, while id and external_id are the fields available to workflows for correlation.

The trigger declaration does not create a webhook endpoint or store delivery state; those are responsibilities of a deployment claiming the external-event initiation capability.