Skip to content

Latest commit

 

History

History
139 lines (108 loc) · 6.95 KB

operator-contract.md

File metadata and controls

139 lines (108 loc) · 6.95 KB

Operator contract

Status: accepted framing and target semantic model, 2026-09-06. This document replaces the former Ability value proposition. It does not rename the current v1 wire contract or certify unimplemented product features.

Definition

An Operator is a named, versioned callable operation with an explicit input/output contract, executed through a provider binding under Runtime admission and Invocation lifecycle rules.

An Operator may wrap SQL, a function, a CLI command, an API, a model or a data job. These are implementation choices, not new kinds of protocol target. One Operator denotes one callable operation; a provider or package can expose several Operators. An Operator can orchestrate child Invocations when its published contract represents one business operation.

Statefulness, accumulated memory and non-portability are not requirements. A stateless revenue.monthly_summary operation is valid. Data, model weights or credentials can be bound to an execution environment without claiming the operation's code cannot be deployed elsewhere.

Vocabulary and ownership

Term Meaning Owner
Resource Identified data, model or system involved in an operation Downstream resource/context integration; generic address grammar belongs to Axon
Operator One callable execution contract Generic semantics in Axon; data-specific declarations downstream
Descriptor Contract identity, version and declared callable shape Canonical contract layer; current descriptor types must not be conflated
Provider Implementation host that executes the operation Runtime/provider integration
Provider binding Explicit association between a contract and an executable provider Runtime
Resource binding Association between an operation deployment and concrete resource access Product/provider; distinct from provider routing
Invocation One admitted execution attempt and its lifecycle Axon canonical runtime
Receipt Verifiable recorded execution facts on supported signed paths Axon facts; product presentation downstream
Capability Descriptive term for what a system can do Vocabulary, not another execution entity
Agent A possible caller or planner Consuming product; existing Axon identity rules remain unchanged

Do not rename unrelated uses of operator meaning a human administrator, capability meaning a permission/control feature, or language operators.

Definition, binding and invocation are separate

The proposed product model distinguishes a reusable operation definition from its deployment and from a single execution:

Operator definition: revenue.monthly_summary @ version
  input: region, month
  output: RevenueReport
          |
Resource binding: Singapore finance data
Provider binding: finance provider in Singapore Runtime
          |
Invocation: caller + authority + exact target + arguments
          |
Receipt facts + output resource references

Resource associations are many-to-many. One operation can consume orders, refunds and FX rates; one dataset can participate in many operations. Do not copy an Operator definition for every table merely to render a catalog tree. Different resource-bound deployments can have distinct routable identities. Their definition identity and deployment identity must remain distinguishable.

Executability and discovery

An Operator definition alone is not an available execution endpoint. Discovery must distinguish declared operations from bound and currently invocable deployments. A metadata record can describe an Operator but does not supply a provider, routing, admission, execution limits or terminal evidence. These requirements motivate the distributed execution product; discovery is its entry surface. See product framing.

Data operation declarations: target product contract

Before a catalog can accurately show what a caller may execute, it needs:

  • Stable resource identities and supported schema/version information.
  • Typed input/output contracts and explicit read/write/external side effects.
  • Resource access scope, execution environment and credential references.
  • Caller-specific authorization and output/export constraints.
  • Supported retry/idempotency behavior and bounded execution limits.
  • Observed input/output resource versions and provenance when available.

These are design requirements, not fields claimed to exist in today's AbilityDescriptor. The Rust registry's observable descriptor contains name, call options, registration time and active invocation count. Other descriptor references carry different binding evidence; migration must inventory each type.

A catalog result is not an authorization grant. Re-evaluate exact target, resource scope and authority at admission. Mutable policy and resource changes between discovery and invocation must produce an explicit decision, never an implicit entitlement based on a stale catalog row.

Lifecycle boundaries

Operator deployment lifecycle, resource lifecycle and Invocation lifecycle have separate owners. Do not combine registration, execution and resource mutation into one status enum.

The current wire Invocation progression is:

Accepted → Admitted → Dispatched → Running
                                   → Completed | Failed | TimedOut | Cancelled

This is the main progression, not a complete transition table. Rejection and failure can occur before running; canonical admission/error semantics remain in force. A failed call does not itself retire an Operator. Provider loss must not erase an existing Invocation's identity or evidence. Retry is governed by idempotency and side-effect semantics, not by an assumption that failure means nothing happened. Unknown external effects require reconciliation before retry.

Claims and limits

Executing near a resource can avoid centralizing its raw data. It does not prevent disclosures through results, logs, errors, network access or exports. Egress restrictions require enforcement at the provider/data boundary.

A signed Receipt attests its recorded facts under a verifier's trust assumptions. It does not alone establish correct revenue accounting, complete lineage, absence of PII or successful external rollback. Missing evidence must remain unknown; do not render it as verified.

Current API mapping

Operator is the new semantic term. Current examples must still use real APIs: AbilityTarget, AbilityDescriptor, AbilityDescriptorRef, list_abilities and the existing /ability/ URA role where required. These are current public identifiers, not a second conceptual execution system.

The existing target has both ability_name and function_name. Therefore a future rename must resolve package/operation granularity before projecting Operator names into that target. A string substitution is not a specification. No /operator/ URI or list_operators API is introduced by this document.

See migration sequence.