Production Integration

Applications do not integrate directly with distributed infrastructure.

They integrate with execution contracts.

Forge provides a stable execution interface that allows applications to express computational intent while the runtime preserves deterministic execution, verification, replay, and computational evidence.

This guide explains how production applications communicate with the Forge execution runtime.

It assumes familiarity with:

Quickstart
Runtime Concepts
Kernel Execution Model

Integration Philosophy

A Forge integration is intentionally simple.

Applications define what should be computed.

The runtime determines how that computation executes.

Conceptually, every integration follows the same lifecycle.

text

Application
        │
        ▼
Execution Contract
        │
        ▼
Forge Runtime
        │
        ▼
Execution Evidence
        │
        ▼
Application

Applications remain responsible for business logic.

Forge remains responsible for execution integrity.

Runtime Responsibilities

Applications:

construct execution contracts
define workload arguments
select execution policies
preserve replay references when required
consume computational results

The Forge runtime:

validates execution authority
validates execution contracts
performs deterministic planning
schedules distributed execution
verifies execution
performs deterministic reduction
preserves execution evidence
records replay metadata
finalizes execution accounting

Applications never communicate directly with execution agents.

All interaction occurs through the public runtime surface.

Authentication

Production Endpoint

text

https://api.forgepool.io

Every execution request requires:

http

Authorization: Bearer <API_KEY>
Content-Type: application/json

Alternative deployments may also support:

http

X-FORGE-API-KEY: <API_KEY>

Project API keys are:

scoped to individual projects
revocable
rate limited
associated with billing and quota policies

Authentication grants permission to submit execution contracts.

It does not influence execution semantics.

See:

Authentication

Submitting Computational Intent

Every execution begins by submitting an immutable execution contract.

The canonical execution endpoint is:

http

POST /api/v0/ops/execute

Every request contains five conceptual sections:

execution context
operation definition
seed behavior
execution policy
workload arguments

Example:

json

{
  "ctx": {
    "job_id": "app-req-001",
    "trace_id": "trace-001",
    "billing": {
      "mode": "billable"
    }
  },
  "op": {
    "name": "mc",
    "version": 1,
    "profile": "insurance.v1"
  },
  "seed": {
    "mode": "explicit",
    "value": "ROOT_SEED_001"
  },
  "policy": {
    "target": "cpu",
    "min_agents": 1,
    "max_agents": 50,
    "verify": "spotcheck"
  },
  "args": {
    "iterations": 10000000,
    "claim_freq": 2.0,
    "claim_severity_mu": 6.0,
    "claim_severity_sig": 1.0
  }
}

Applications express computational intent.

The runtime transforms that intent into distributed execution.

What Happens Next

Submitting a request initiates the complete execution lifecycle.

text

Execution Contract
        │
        ▼
Job Registration
        │
        ▼
Deterministic Planning
        │
        ▼
Shard Construction
        │
        ▼
Distributed Execution
        │
        ▼
Verification
        │
        ▼
Deterministic Reduction
        │
        ▼
Execution Evidence
        │
        ▼
Replay Metadata
        │
        ▼
Response

The API response represents only the visible result of a significantly larger execution process.

Example Execution

bash

curl -X POST https://api.forgepool.io/api/v0/ops/execute \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Example response:

json

{
  "ok": true,
  "job_id": "01K...",
  "status": "COMPLETED",
  "hub": {
    "metrics": {
      "wall_ms": 37317,
      "agents_used": 10,
      "shards": 10
    },
    "output": {
      "loss": {
        "mean": 1853.46,
        "variance": 22930414.49
      }
    },
    "replay": {
      "root_seed": "ROOT_SEED_001"
    }
  },
  "billing": {
    "credits": 1.42,
    "eur": 0.17
  }
}

Applications receive:

aggregated computational output
execution metrics
replay references
execution identifiers
billing information

The runtime retains considerably richer execution evidence for replay, verification, and observability.

Deterministic Execution

Applications do not implement determinism.

Applications define execution contracts.

The Forge runtime preserves deterministic execution through:

immutable execution contracts
deterministic planning
controlled seed discipline
deterministic reduction
replay preservation

Equivalent execution contracts therefore produce reproducible computational behavior within the documented execution model.

Replay

Production systems should preserve:

job identifiers
execution contracts
explicit seeds
replay references
artifact references when applicable

Replay allows execution to be independently inspected long after computation has completed.

Replay evaluates execution semantics rather than infrastructure identity.

Execution Policies

Execution policies influence runtime behavior without changing computational identity.

Typical policy controls include:

execution target
parallelism
verification level
scaling boundaries

Execution policy affects:

cost
latency
verification strength
infrastructure selection

Execution policy never changes workload semantics.

Runtime Memory Surfaces

Advanced execution workflows may interact with persistent runtime surfaces.

Examples include:

Blob Storage
KV
VMem
execution snapshots
replay artifacts

These surfaces support:

multi-stage execution
artifact persistence
cached computation
execution references
replay

Memory surfaces extend execution.

They do not replace execution contracts.

Observability

Every execution remains observable through Forge HQ.

Typical inspection surfaces include:

execution contracts
shard allocation
participating agents
verification status
replay metadata
execution metrics
billing records
execution artifacts

Observability is an intrinsic property of execution rather than an optional monitoring feature.

Production Readiness

Before deploying production workloads, verify that your application:

uses explicit seeds where reproducibility matters
preserves execution identifiers
stores replay references
validates failure handling
monitors execution policies
understands verification behavior
reviews execution evidence
monitors resource consumption

Production readiness depends on preserving execution context—not merely handling API responses.

Practical Mental Model

A useful way to understand Forge integration is:

text

Business Logic
        │
        ▼
Execution Contract
        │
        ▼
Forge Runtime
        │
        ▼
Execution Evidence
        │
        ▼
Replay
        │
        ▼
Computational Trust

Applications define computational intent.

Forge preserves execution integrity.

Where to Go Next

Once your application can successfully submit execution contracts, continue with:

Providers Guide — understand how distributed execution capacity is supplied.
Forge Studio — compose execution systems visually.
HQ — inspect execution, replay, and operational state.
Observability — monitor distributed execution in production.
Trust Layer — understand verification, replay, and execution evidence in depth.

Together these documents describe the complete lifecycle of a production Forge deployment.

Final Thought

Applications should never need to understand distributed scheduling, heterogeneous infrastructure, or execution coordination.

They should describe the computation they require.

Forge transforms that computational intent into deterministic distributed execution while preserving the evidence required to understand, verify, and replay it long after execution has completed.

Production Integration ​

Integration Philosophy ​

Runtime Responsibilities ​

Authentication ​

Production Endpoint ​

Submitting Computational Intent ​

What Happens Next ​

Example Execution ​

Deterministic Execution ​

Replay ​

Execution Policies ​

Runtime Memory Surfaces ​

Observability ​

Production Readiness ​

Practical Mental Model ​

Where to Go Next ​

Final Thought ​

Production Integration

Integration Philosophy

Runtime Responsibilities

Authentication

Production Endpoint

Submitting Computational Intent

What Happens Next

Example Execution

Deterministic Execution

Replay

Execution Policies

Runtime Memory Surfaces

Observability

Production Readiness

Practical Mental Model

Where to Go Next

Final Thought