COG-7: Operations

Status:      Draft (Work in Progress)
Version:     0.1
Created:     2025-01-23
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.

Core Principles

Immutable Definitions

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

The Asset ID is the SHA256 hash of the operation's 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:

Definition Trust: The Asset ID guarantees you're invoking the intended operation
Venue Trust: You trust the venue to execute the operation correctly
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 format is {adapter-type} or {adapter-type}:{sub-type}.

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`	LangChain AI model operations
`convex`	Convex blockchain operations
`grid`	Grid meta-operations (invoke, status, etc.)

`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"
        }
      }
    }
  }
}

Execution Model

When a client invokes an operation:

Job Creation: The venue creates a Job to track execution
Input Validation: Inputs are validated against the schema (if provided)
Adapter Dispatch: The venue routes to the appropriate adapter
Execution: The adapter performs the operation
Result Return: Output is returned via the Job

See COG-1: Architecture for details on Jobs.

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": "http:get",
        "name": "Fetch Data",
        "input": {
          "url": ["input", "dataUrl"]
        }
      },
      {
        "op": "jvm:transform",
        "name": "Process",
        "input": [0, "body"]
      }
    ]
  }
}

Each step specifies:

op: Operation identifier (adapter reference or Asset ID)
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

`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": "http:get",
        "name": "Fetch Source",
        "input": {
          "url": ["input", "url"]
        }
      },
      {
        "op": "jvm:transform",
        "name": "Transform Data",
        "input": {
          "data": [0, "body"],
          "format": ["input", "format"]
        }
      }
    ],
    "result": {
      "data": [1, "output"],
      "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 code - should be sandboxed appropriately
orchestrator: Inherits security requirements of child operations

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

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)

Purpose​

Terminology​

Core Principles​

Immutable Definitions​

Verifiable Interfaces​

Federated Execution​

Trust Model​

Specification​

Operation Identification​

Required Metadata Fields​

operation.adapter (REQUIRED)​

operation.input (RECOMMENDED)​

operation.output (RECOMMENDED)​

Execution Model​

Orchestrations​

operation.steps (REQUIRED for orchestrations)​

Input Mapping Syntax​

operation.result (REQUIRED for orchestrations)​

Examples​

HTTP Operation​

Blockchain Query Operation​

Orchestration Operation​

Security Considerations​

Input Validation​

Adapter Security​

Output Trust​

Resource Limits​

Related Specifications​