COG-7: Operations

Status:      Draft (Work in Progress)
Version:     0.3
Created:     2025-01-23
Updated:     2026-07-16
Authors:     Mike Anderson

Work in Progress

This specification is under active development. Structure and details may change significantly based on implementation experience and community feedback.

This standard specifies Operations - executable assets on the Covia Grid that provide compute capabilities with defined interfaces, enabling trusted and composable computation across venues.

Purpose

Operations are the compute foundation of the Grid, representing executable functions that:

• Define Interfaces: Explicit input/output schemas enable interoperability
• Enable Composition: Operations can be chained into workflows
• Support Federation: The same operation can be executed by multiple venues
• Provide Verifiability: Operation definitions are immutable and content-addressable

Operations transform the Grid from a data repository into a distributed compute platform where clients can invoke capabilities without managing infrastructure.

Terminology

See COG-1: Architecture for definitions of Grid terminology including Operation, Adapter, Job, and Orchestration. See COG-8: Jobs for the full job lifecycle specification.

Core Principles

Immutable Definitions

Like all assets, operation metadata is immutable and content-addressable:

• The Asset ID is the Value ID of the operation's metadata (see COG-5: Asset Metadata)
• The same Asset ID always refers to the same operation definition
• Changes to an operation create a new asset with a new ID

This immutability ensures:

• Reproducibility: Invoking an operation by Asset ID guarantees consistent behaviour
• Auditability: Job records can reference the exact operation definition used
• Safe Caching: Operation definitions can be cached indefinitely

Verifiable Interfaces

Operations declare their interfaces through JSON Schema:

• Input Schema: Defines expected parameters and their types
• Output Schema: Defines the structure of results

These schemas enable:

• Validation: Inputs can be validated before execution
• Documentation: Interfaces are self-describing
• Tooling: IDEs and clients can provide assistance based on schemas
• Composition: Orchestrations can verify compatibility between steps

Federated Execution

Operations support execution across multiple venues:

• Portable Definitions: Operation metadata can be replicated to any venue
• Adapter-Based Execution: Venues implement adapters that execute operations
• Consistent Results: Same inputs produce same outputs regardless of venue

This enables:

• Load Distribution: Clients can choose from multiple venues
• Resilience: Operations remain available if some venues are down
• Geographic Optimisation: Execute operations close to data or users

Trust Model

Trust in operations comes from multiple sources:

1. Definition Trust: The Asset ID guarantees you're invoking the intended operation
2. Venue Trust: You trust the venue to execute the operation correctly
3. Result Verification: For deterministic operations, results can be verified

Different use cases require different trust levels - a simple HTTP fetch needs less trust than financial computation.

Specification

Operation Identification

Operations are identified following COG-2: Decentralised ID:

did:web:venue.example.com/a/7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b

Required Metadata Fields

Operations MUST include an operation object in their metadata. See COG-5: Asset Metadata for the complete metadata specification.

operation.adapter (REQUIRED)

Identifies the adapter responsible for executing this operation:

{
  "operation": {
    "adapter": "http"
  }
}

The adapter string is routed on its first colon: the segment before it selects the adapter, and everything after it is an adapter-defined suffix that MAY itself contain further colons (e.g. http, langchain:openai, mcp:tools:call). Adapters define their own suffix conventions, and MAY likewise define additional adapter-specific fields inside the operation object (such as the mcp adapter's remoteToolName and server below).

Standard adapters include:

Adapter	Description
http	HTTP request operations
jvm	JVM-based local operations
orchestrator	Multi-step workflow execution
mcp	Model Context Protocol integration
langchain	LLM inference (OpenAI, Ollama, Gemini, DeepSeek, etc.)
convex	Convex blockchain queries and transactions
grid	Grid meta-operations (invoke, status, federation)
agent	Stateful agent lifecycle (create, message, run loop)
llmagent	LLM-backed agent transitions (conversation history, multi-turn)
test	Echo, delay, error simulation for development and testing
covia	Internal venue operations

note

The agent and llmagent adapters support the agent lifecycle model described in COG-11: Agent Lifecycle. These adapters are under active development and their operation interfaces may evolve.

operation.input (RECOMMENDED)

JSON Schema defining expected input parameters:

{
  "operation": {
    "input": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "Search query"
        },
        "limit": {
          "type": "integer",
          "description": "Maximum results",
          "default": 10
        }
      },
      "required": ["query"]
    }
  }
}

operation.output (RECOMMENDED)

JSON Schema defining the result structure:

{
  "operation": {
    "output": {
      "type": "object",
      "properties": {
        "results": {
          "type": "array",
          "description": "Search results"
        },
        "total": {
          "type": "integer",
          "description": "Total matches found"
        }
      }
    }
  }
}

operation.default (OPTIONAL)

A map of argument values merged under the caller's input at dispatch — defaults fill in fields the caller omits:

{
  "name": "Report Covia Bug",
  "operation": {
    "adapter": "mcp:tools:call",
    "remoteToolName": "create_issue",
    "server": "https://mcp.github.example",
    "default": { "owner": "covia-ai", "repo": "covia" },
    "input": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "body": { "type": "string" }
      },
      "required": ["title"]
    }
  }
}

Semantics:

• Caller wins: a caller-supplied value always overrides the default.
• Any value type: defaults may be strings, numbers, booleans, arrays, or objects.
• Shallow merge: top-level keys only. Defaults apply to object inputs; a null input becomes the defaults map, and a non-object input passes through untouched.
• Applied once at dispatch, before capability checks and job creation — authorisation decisions rule on, and the job record stores, the effective input.
• Defaulted keys SHOULD be omitted from the input schema's required list so callers know they may omit them.

Defaults let a generic operation be published as a purpose-shaped one — the example above turns a five-field create_issue into a two-field bug reporter. They are purpose-shaping, not policy: a caller can override any default, so enforcement of argument values belongs to the venue's capability layer (see COG-13: Agent Capabilities), not to defaults. Credentials MUST NOT be placed in defaults — operation metadata persists in plain form; credentials belong in secret references.

Execution Model

When a client invokes an operation:

1. Argument Defaults: entries in operation.default fill in input fields the caller omitted (caller-supplied values win)
2. Job Creation: The venue creates a Job to track execution — its record holds the effective input
3. Input Validation: Inputs are validated against the schema (if provided)
4. Adapter Dispatch: The venue routes to the appropriate adapter
5. Execution: The adapter performs the operation
6. Result Return: Output is returned via the Job

See COG-8: Jobs for the full job lifecycle, status transitions, and observation mechanisms.

Orchestrations

Operations can compose other operations using the orchestrator adapter:

operation.steps (REQUIRED for orchestrations)

An ordered array of steps to execute:

{
  "operation": {
    "adapter": "orchestrator",
    "steps": [
      {
        "op": "v/ops/http/get",
        "name": "Fetch Data",
        "input": {
          "url": ["input", "dataUrl"]
        }
      },
      {
        "op": "v/ops/langchain/openai",
        "name": "Process",
        "input": { "prompt": [0, "body"] }
      }
    ],
    "result": {
      "processed": [1, "content"],
      "source": [0, "headers"]
    }
  }
}

Each step specifies:

• op: Operation reference (catalog path, Asset ID, or DID URL)
• name: Human-readable step name
• input: Input mapping (see below)

Input Mapping Syntax

Syntax	Description
["input"]	Entire orchestration input
["input", "field"]	Specific field from input
[0]	Output of step 0
[1, "field"]	Field from step 1's output
["const", value]	Literal constant value (embeds value verbatim, even if it is a vector)
["concat", parts...]	String concatenation of the resolved parts
["array", elems...]	Array whose elements are each resolved

Only JSON arrays are interpreted as mapping expressions; maps are resolved value-by-value, and any other value (string, number, boolean) is a literal. Expression arguments nest — ["concat", "Convert to ", ["input", "format"], ":\n", [0, "body"]] mixes literal strings with resolved references. See COG-12: Orchestrations for the full orchestration model.

operation.result (REQUIRED for orchestrations)

Maps step outputs to the final result:

{
  "operation": {
    "result": {
      "data": [1, "output"],
      "metadata": [0, "headers"],
      "originalInput": ["input"]
    }
  }
}

Examples

HTTP Operation

A simple HTTP GET request:

{
  "name": "HTTP GET",
  "description": "Performs an HTTP GET request and returns the response",
  "dateCreated": "2025-01-27T10:00:00Z",
  "operation": {
    "adapter": "http",
    "input": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "URL to fetch"
        },
        "headers": {
          "type": "object",
          "description": "Optional request headers"
        }
      },
      "required": ["url"]
    },
    "output": {
      "type": "object",
      "properties": {
        "status": {
          "type": "integer",
          "description": "HTTP status code"
        },
        "body": {
          "type": "string",
          "description": "Response body"
        },
        "headers": {
          "type": "object",
          "description": "Response headers"
        }
      }
    }
  }
}

Blockchain Query Operation

A read-only Convex blockchain query:

{
  "name": "Convex Query",
  "description": "Execute a read-only query against the Convex network",
  "dateCreated": "2025-01-27T10:00:00Z",
  "operation": {
    "adapter": "convex:query",
    "input": {
      "type": "object",
      "properties": {
        "peer": {
          "type": "string",
          "description": "Convex peer endpoint",
          "default": "peer.convex.live:18888"
        },
        "address": {
          "type": "string",
          "description": "Account address for context (e.g., #123)"
        },
        "source": {
          "type": "string",
          "description": "Convex Lisp code to execute"
        }
      },
      "required": ["source"]
    },
    "output": {
      "type": "object",
      "properties": {
        "result": {
          "type": "string",
          "description": "Query result as Convex data"
        },
        "value": {
          "description": "Result converted to JSON"
        },
        "errorCode": {
          "type": "string",
          "description": "Error code if query failed"
        }
      }
    }
  }
}

Orchestration Operation

A multi-step workflow combining operations:

{
  "name": "Fetch and Transform",
  "description": "Fetches data from a URL and applies a transformation",
  "dateCreated": "2025-01-27T10:00:00Z",
  "operation": {
    "adapter": "orchestrator",
    "input": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "Data source URL"
        },
        "format": {
          "type": "string",
          "description": "Output format",
          "default": "json"
        }
      },
      "required": ["url"]
    },
    "output": {
      "type": "object",
      "properties": {
        "data": {
          "description": "Transformed data"
        },
        "source": {
          "type": "string",
          "description": "Original source URL"
        }
      }
    },
    "steps": [
      {
        "op": "v/ops/http/get",
        "name": "Fetch Source",
        "input": {
          "url": ["input", "url"]
        }
      },
      {
        "op": "v/ops/langchain/openai",
        "name": "Transform Data",
        "input": {
          "prompt": ["concat", "Convert the following to ", ["input", "format"], ":\n", [0, "body"]]
        }
      }
    ],
    "result": {
      "data": [1, "content"],
      "source": ["input", "url"]
    }
  }
}

Security Considerations

Input Validation

Venues SHOULD validate inputs against the declared schema before execution. This prevents:

• Injection attacks through malformed inputs
• Resource exhaustion from unexpected input sizes
• Type confusion errors

Adapter Security

Adapters have different security profiles:

• http: Can make external network requests — venue policies should restrict targets
• jvm: Executes local code — should be sandboxed appropriately
• orchestrator: Inherits security requirements of child operations
• langchain, llmagent: Make outbound API calls to LLM providers — credentials must be handled securely
• mcp: Connects to external MCP servers — venue policies should restrict allowed endpoints
• agent: Maintains persistent state — resource limits on agent count, inbox size, and lifetime apply

Output Trust

Operation outputs should be treated according to the trust level of the executing venue:

• Verify deterministic results where possible
• Use multiple venues for critical computations
• Consider cryptographic attestations for high-value operations

Resource Limits

Venues SHOULD impose resource limits on operation execution:

• Timeout limits
• Memory limits
• Network request limits
• Nested orchestration depth limits

Related Specifications

• COG-1: Architecture - Overall Grid architecture, Jobs, and Adapters
• COG-2: Decentralised ID - Operation identification
• COG-5: Asset Metadata - Common metadata format
• COG-6: Artifacts - Data assets (contrast with operations)
• COG-8: Jobs - Job lifecycle, status transitions, and execution tracking
• COG-11: Agent Lifecycle - Stateful agent creation, run loop, and state transitions