Execute API

The Execute API defines the canonical execution contract of the Forge Pool execution platform.

Every distributed workload—regardless of primitive family, execution profile, or runtime implementation—is submitted through the same public execution interface.

The endpoint itself is intentionally simple.

The execution contract defines the behavior.

---

Public Execution Endpoint

POST /api/v0/ops/execute

This is the only public endpoint used to submit distributed execution requests.

Workload selection is expressed entirely through the execution contract rather than through workload-specific routes.

As new primitive families and execution capabilities are introduced, the public endpoint remains unchanged.

---

Execution Contract

Every execution request conforms to the same canonical structure.

Execution Request
    ↓
Operation Identity
    ↓
Execution Parameters
    ↓
Execution Policy
    ↓
Deterministic Seed
    ↓
Execution Context
    ↓
Artifact Preferences

This contract remains stable across every execution capability exposed by Forge Pool.

---

Canonical Request Envelope

{
  "op": {},
  "args": {},
  "policy": {},
  "seed": {},
  "ctx": {},
  "artifacts": {}
}

Each section serves an independent responsibility.

Section	Responsibility
op	Defines the computational identity of the workload
args	Supplies profile-specific execution parameters
policy	Expresses execution preferences and constraints
seed	Controls deterministic execution
ctx	Associates execution with caller context
artifacts	Requests optional execution artifacts

Only op and args define workload semantics.

The remaining sections influence execution behavior without changing the computational meaning of the request.

---

Operation Identity

The op object uniquely identifies the workload to be executed.

{
  "op": {
    "name": "mc",
    "version": 1,
    "profile": "insurance.loss_distribution_surface.v1"
  }
}

Operation identity consists of:

• primitive family
• primitive version
• execution profile

Together these fields define the computational semantics of the request.

---

Execution Parameters

The args object contains the parameters defined by the selected execution profile.

Its structure is intentionally profile-specific.

Forge Pool does not define a universal argument schema across all execution capabilities.

Instead, each profile documents its own execution parameters while preserving a common execution contract.

---

Execution Policy

Execution policy communicates execution preferences rather than execution semantics.

Typical policy controls include:

• preferred execution target
• execution parallelism
• verification policy
• execution constraints

Changing execution policy may influence how execution is planned, but it does not change the computational meaning of the workload.

---

Deterministic Seed

Deterministic execution is governed through the execution seed.

Two execution modes are supported:

• explicit root seed
• deterministic seed derivation

Equivalent execution contracts evaluated under the same seed and execution doctrine must produce reproducible execution behavior.

---

Execution Context

Execution context associates workloads with external systems.

Typical metadata includes:

• client job identifiers
• tracing information
• billing mode
• caller-specific correlation identifiers

Context never changes workload semantics.

It exists solely to associate execution with external operational systems.

---

Artifact Preferences

Artifact preferences express which execution artifacts should be returned or persisted when supported.

The runtime may generate additional artifacts required for execution verification, replay, auditing, or inspection regardless of caller preferences.

Artifact generation therefore remains verification-aware rather than request-driven.

---

Execution Lifecycle

Every execution submitted through the public API follows the same lifecycle.

Declare
    ↓
Validate
    ↓
Plan
    ↓
Execute
    ↓
Verify
    ↓
Reduce
    ↓
Respond

The public execution lifecycle remains stable regardless of runtime implementation.

---

Successful Response

A successful execution returns a normalized execution result.

{
  "ok": true,
  "job_id": "...",
  "status": "COMPLETED",
  "billing": {},
  "execution": {
    "metrics": {},
    "executions": [],
    "output": {},
    "artifacts": [],
    "replay": {}
  }
}

The public response intentionally abstracts internal runtime implementation.

---

Execution Metadata

Execution metadata provides the information required to inspect and validate execution.

Typical metadata includes:

• execution metrics
• shard summaries
• execution identifiers
• artifact references
• replay references

Execution metadata supports operational inspection without exposing internal orchestration components.

---

Determinism

Forge Pool defines determinism at the execution contract level.

Equivalent execution contracts evaluated under the same execution doctrine must produce equivalent results regardless of:

• infrastructure placement
• execution routing
• participating runtime nodes
• execution ordering

Determinism is therefore a property of the execution contract rather than the underlying infrastructure.

---

Verification

Verification is an integral part of execution.

Execution responses provide the metadata required to:

• inspect execution
• validate artifacts
• perform deterministic replay
• verify execution outcomes independently

Verification is treated as part of the execution contract rather than a separate operational concern.

---

Billing

Execution and billing remain intentionally independent.

The execution runtime reports execution metrics.

The public platform determines customer-visible billing using those metrics together with project policy and billing configuration.

This separation preserves deterministic execution behavior while allowing billing policy to evolve independently.

---

Error Model

Failures return a normalized public error surface.

{
  "ok": false,
  "status": "FAILED",
  "error": {
    "code": "invalid_request",
    "message": "..."
  }
}

Errors are classified into stable public categories regardless of their internal runtime origin.

Typical categories include:

• authentication
• authorization
• validation
• quota
• execution
• temporary runtime availability

---

What This API Is Not

The Execute API is not:

• a workload-specific endpoint
• a generic RPC interface
• an internal runtime interface
• a direct infrastructure control surface
• an agent management API

It is the canonical public execution contract of the Forge Pool execution platform.

---

Related Documentation

Continue with:

Execution

• Execution Model
• Determinism
• Replay

Verification

• Verification Overview
• First Verified Execution

Examples

• Capability Examples

---

Continue in Forge Studio

This document defines the canonical execution contract.

To execute workloads using this contract:

• Explore available capabilities in Capability Explorer
• Inspect execution blocks in Block Registry
• Execute workloads interactively in Forge Studio
• Verify execution using replay metadata and runtime artifacts

Trust should be established through independent verification rather than documentation alone.

---

Final Note

The Execute API does not define how the execution platform is implemented.

It defines the public contract that every implementation must honor.

By separating execution semantics from runtime implementation, Forge Pool provides a stable interface for distributed execution while allowing the execution platform itself to evolve continuously.