> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alakazam.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Forge concepts

> The campaign, the six-step spine, the miner, the gates, and what a delivery actually is.

<div className="forge-kicker">◆ FORGE · concepts</div>

The forge has one unit of work (the **campaign**) and one rule underneath
everything: nothing is fabricated, and nothing advances on your behalf. This
page is the mental model behind the [quickstart](/forge-quickstart)'s calls.

## Campaign

A campaign is one walk of a dataset through the pipeline: an owner-scoped
record tying the source dataset, its health report, the sampled episodes, the
transform plan, the run jobs, your review verdicts, and the delivery state.

* **Per-user tenancy.** Campaigns belong to the account that created them.
  A campaign id that isn't yours reads as `404`: the API never confirms a
  foreign resource exists (see [errors](/forge-errors)).
* **Monotonic stage.** `stage` is the furthest step you've reached; it never
  rolls back. You can leave and re-enter anywhere; re-saving an earlier step
  doesn't undo a later one.
* **Three ways to start one:** open a curated [sample](/forge-testing),
  upload a LeRobot dataset, or point at a Hugging Face `repo_id`.

## The six-step spine

| Step          | What it produces on the campaign                         |
| ------------- | -------------------------------------------------------- |
| **Overview**  | detected classes + the selected target class             |
| **Source**    | `health`: the eligibility funnel, per-episode verdicts   |
| **Sample**    | `sample.selected`: the source episodes you chose         |
| **Transform** | `plan.transformations`, operations + readiness           |
| **Run**       | `run_ids`, gated render jobs with per-episode verdicts   |
| **Deliver**   | `delivery` + `billed_episodes`: the exported, billed set |

## Target class and eligibility

Health detects the dataset's classes and measures everything against one
**target class** (the engine's certified default, or one you switch to, switching recomputes health for that class). Per episode, eligibility for
new-trajectory work requires a clean **grasp → carry → place** arc:

* **on-target class**: off-target episodes are excluded outright;
* **grasp on the certified arm**: the wrong arm is an exclusion, with the
  arm named;
* **a real release**: no place event means no splice point;
* **travel above the jitter threshold**: a "release" that barely moved is
  noise, not a placement.

Every exclusion carries its exact reason in the funnel and on the episode
grid. The detected annotations, `grasp_frame`, `splice_frame` (the release),
`pre_release_frame`, `travel_deg`, are yours to read per episode at
`…/episodes/{ep}/actions.json`, overlaid on the native action stream.

## The miner

New trajectories are **head × tail splices**: episode A's scene, reach, and
grasp continued with episode B's carry and place. The miner scores every
eligible (A, B) pair of the target class on three axes:

* **divergence**: how differently the two post-grasp arm paths move
  (RMS joint distance over time-resampled paths). Candidates must sit inside
  the engine's **divergence band**: different enough to be a new behavior,
  close enough that the render model obeys.
* **end\_divergence**: how differently the two episodes *place* (distance
  between placement configurations). Within the band, pairs are ranked by
  this: it's the visible drama.
* **n\_blend**: seam feasibility: the minimum blend frames so no action
  dimension jumps faster than the dataset's own 99th-percentile step.

Results are de-duplicated under per-head and per-tail caps, and, when the
campaign has prior runs, re-weighted toward heads that historically pass the
gates. The playground's **precise splice** is this same miner pinned to one
head; its `partners` records are full pair dicts you POST back verbatim.

## Machine verdict and gates

Every rendered candidate is scored by an **action-consistency verifier**: does
the video's implied motion match the trajectory that was asked for? Three
readings, each against a per-engine calibrated threshold:

| Gate  | Reading                          | Passes when          |
| ----- | -------------------------------- | -------------------- |
| ratio | post/pre-splice error ratio      | `ratio <= ratio_max` |
| corr  | implied-vs-commanded correlation | `corr >= corr_min`   |
| mae   | mean absolute error, normalized  | `mae <= mae_max`     |

Two more checks ride along: a **task gate** (did the pick-and-place actually
complete?) and an **identity gate** (zero frames of object-identity drift).
The machine verdict is `accept` only when all five hold. A task check that
can't run **abstains**, recorded as not-run, never counted as a failure. A
render that fails outright is rejected with the reason recorded; garbage is
never gated. Thresholds and readings are on every episode and in its
delivered certificate.

## Confirm, overrule, and the kept set

Verdicts exist only for **graded** episodes (machine `accept` or `reject`);
reviewing an ungraded one returns `409`. Two verbs:

* **confirm**: you agree with the machine;
* **overrule**: you flip it: keeping a machine-reject, or dropping a
  machine-accept. Overrules are recorded as yours, with a timestamp, on the campaign
  record (the certificate carries the machine's readings).

The **kept set** is the machine verdict with your overrules applied.
Unreviewed episodes trust the machine: an unreviewed machine-accept is kept.
Reviewing is free, so grade honestly, not strategically.

## Delivery and the billed set

Deliver freezes the kept set at request time, drops any episode whose render
artifacts are no longer on disk (billing you for a phantom would be worse than
a `409`), then debits **1 credit per kept episode that has never been billed
on this campaign**, atomically, before anything is exported. The paid set
persists on the campaign as `billed_episodes`, so re-delivering after new
keeps charges only the additions, and nothing ever bills twice. The archive
contains exactly the billed set: per-view mp4s, action streams at both fps,
and a provenance certificate per episode. Full rules in
[billing](/forge-billing).

## Playground refs: `wb/<campaign>/<episode>`

A **described change** in the [playground](/forge-playground) becomes a real
scenario batch bound to its exact source episode by reference:

```
wb/camp_1a2b3c4d5e6f/17
```

`wb/` marks a workbench campaign episode; the campaign id scopes it to you;
the trailing integer is the episode index. Batches carrying a `wb/` ref render
with the campaign's engine and verify like any campaign run.

## What runs today

Honestly, per transform:

* **New trajectories**: live end to end: mine, compose, render, verify,
  deliver. This is the engine both playground verbs use.
* **Object swap**: preview. The shared action verifier applies, but the
  general video swap backend isn't connected to the workbench yet; the
  Transform step shows the exact readiness steps.
* **Environment restyle**: blocked on a fidelity floor: on our reference
  batch, restyled output scored below the verifier's acceptance line. We show
  that reading instead of shipping it.

The Transform step's readiness checklist is the source of truth per
deployment: a run that isn't ready is refused with the missing step named,
not queued and quietly failed.