Forge Pool API

The Forge Pool API is the public execution contract for the Forge Pool Planetary Kernel.

Rather than exposing a collection of workload-specific endpoints, Forge provides a single stable interface for submitting deterministic distributed workloads. Execution semantics are defined by versioned primitives and profiles, allowing the runtime to evolve while preserving a consistent public contract.

This separation between public interface and internal implementation enables the platform to introduce new execution strategies, orchestration mechanisms, and runtime optimizations without changing how clients interact with the system.

---

Public Execution Contract

All distributed workloads are submitted through a single public endpoint:

POST /api/v0/ops/execute

The execution request identifies what should be executed rather than how it should be executed.

Execution behavior is determined by the request envelope, including the selected primitive, version, execution profile, policy, and arguments.

The internal execution topology is intentionally abstracted behind this contract.

---

Design Principles

The public API is designed around five core principles.

Stable Contract

The public execution surface remains stable even as the underlying runtime evolves.

Clients integrate with one execution contract rather than individual execution services.

Deterministic Execution

Equivalent execution requests produce reproducible execution behavior when evaluated under the same execution policy, seed, primitive version, and profile.

Verification First

Execution is designed to be independently verifiable.

Responses include execution metadata, replay references, and artifact information that allow evaluators to validate execution rather than relying solely on documentation.

Versioned Semantics

Execution behavior is defined through versioned primitives and execution profiles instead of endpoint proliferation.

New capabilities extend the execution model without requiring new public APIs.

Runtime Evolution

Planning, scheduling, sharding, reduction, and verification are implementation details.

These components may evolve independently without affecting the public execution contract.

---

Execution Lifecycle

Every request follows the same execution lifecycle.

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

At each stage, the runtime preserves sufficient metadata to support deterministic replay, execution inspection, and runtime verification.

---

Runtime Guarantees

Every public execution benefits from the same execution guarantees.

Forge Pool provides:

• one stable public execution contract
• versioned primitive semantics
• versioned execution profiles
• deterministic execution discipline
• replay-ready execution metadata
• artifact-aware execution
• verification-oriented runtime behavior

These guarantees remain consistent regardless of the underlying execution strategy or runtime implementation.

---

Public Runtime Boundary

From a public API perspective, every execution follows the same conceptual path.

Client
    ↓
Forge Pool API
    ↓
Planetary Kernel
    ↓
Distributed Execution
    ↓
Verification & Reduction
    ↓
Response

The internal orchestration architecture intentionally remains behind the public execution contract.

Clients interact with a stable execution interface rather than individual runtime components.

---

Verification

Verification is treated as part of execution rather than a post-processing activity.

Execution responses expose the metadata required to inspect results, validate execution, perform deterministic replay, and examine generated artifacts.

Independent verification is a fundamental design objective of the platform.

---

Relationship to Studio

Documentation explains the execution model.

The public API executes workloads.

Forge Studio enables interactive exploration, execution, inspection, and verification using the same underlying execution contract.

Together they provide a consistent path from documentation to verified execution.

---

Documentation Map

The following sections describe the public execution surface in greater detail.

Getting Started

• Authentication
• Execute API

Execution Model

• Kernel Overview
• Execution Model
• Determinism
• Replay
• Primitive Families

Primitive References

• Monte Carlo
• Ensemble
• Graph
• Search
• Media

---

Mental Model

The simplest correct mental model is:

1. Submit one canonical execution request.
2. The Planetary Kernel determines how execution is performed.
3. The runtime plans, distributes, verifies, and reduces execution.
4. The response contains both domain output and execution evidence.

Understanding this model is sufficient to understand every execution capability exposed by Forge Pool.

---

Why One Execution API?

Traditional compute platforms often expose different interfaces for different workload types.

Forge Pool instead exposes a single execution contract capable of executing many primitive families.

This approach provides:

• one consistent integration surface
• versioned execution semantics
• deterministic execution behavior
• verification-oriented execution
• long-term API stability

As the runtime evolves, the public contract remains consistent.

---

Final Note

The Forge Pool API does not expose the internal runtime architecture.

It exposes a stable execution contract.

This separation allows the execution platform to evolve while preserving deterministic behavior, replay compatibility, and verification guarantees for every public workload.