# LLM Factory Protocol

Factory is the durable orchestration surface for tenant-scoped delivery runs in
Abbotik.

It lives beside rooms under `/llm/*`: rooms are the bounded execution
primitive, while factory tracks planning, stages, issues, verification, gates,
checkpoints, and review bundles across a run.

This v0 HTTP surface is intentionally run-level.

Public callers can start runs, inspect durable state, request advancement,
execute verification, persist gate verdicts, and author durable checkpoints,
stages, and issues directly through `/llm/factory`.

Verification command execution is a root-only administrative surface. Non-root
callers may still inspect factory state, but they cannot persist or execute
host verification commands.

## Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/llm/factory/runs` | List visible factory runs |
| POST | `/llm/factory/runs` | Start a new factory run |
| GET | `/llm/factory/runs/:id` | Fetch one run |
| GET | `/llm/factory/runs/:id/status` | Read aggregate run status |
| GET | `/llm/factory/runs/:id/checkpoints` | List checkpoint records |
| POST | `/llm/factory/runs/:id/checkpoints` | Create a checkpoint record |
| GET | `/llm/factory/runs/:id/stages` | List stage records |
| POST | `/llm/factory/runs/:id/stages` | Create a stage record |
| PATCH | `/llm/factory/runs/:id/stages/:stage_id` | Update one stage record |
| GET | `/llm/factory/runs/:id/issues` | List issue records |
| POST | `/llm/factory/runs/:id/issues` | Create an issue record |
| PATCH | `/llm/factory/runs/:id/issues/:issue_id` | Update one issue record |
| GET | `/llm/factory/runs/:id/artifacts` | List emitted artifacts |
| POST | `/llm/factory/runs/:id/advance` | Advance the run state machine |
| POST | `/llm/factory/runs/:id/verify` | Execute verification commands and store a report |
| POST | `/llm/factory/runs/:id/gate-check` | Evaluate and persist a gate verdict |
| GET | `/llm/factory/runs/:id/review` | Read the latest review bundle |

## Live v0 Behavior

The live run lifecycle is:

- `planning`
- `implementing`
- `verifying`
- `gated`
- `completed`
- `failed`

The live stage and issue statuses are:

- `pending`
- `ready`
- `running`
- `passed`
- `failed`
- `blocked`

The live checkpoint statuses are:

- `pending`
- `running`
- `ready`
- `failed`

The live emitted artifact types are:

- `interpreted_problem`
- `normalized_spec`
- `stage_graph`
- `verification_report`

Reserved enum values may still exist in the internal package type surface, but
they are not part of the live HTTP contract unless the runtime starts
producing them.