# LLM Factory Protocol

Factory is the durable workflow-kernel surface for tenant-scoped 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, dispatch issue prompts, and
author durable checkpoints, stages, issues, and artifacts 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 |
| POST | `/llm/factory/runs/:id/issues/:issue_id/dispatch` | Dispatch an issue with caller-supplied prompt content |
| GET | `/llm/factory/runs/:id/artifacts` | List emitted artifacts |
| POST | `/llm/factory/runs/:id/artifacts` | Create an artifact record |
| 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 |
| POST | `/llm/factory/runs/:id/gates` | Create an externally supplied 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 package-authored artifact types are:

- `problem_interpretation`
- `delivery_spec`
- `repository_context`
- `factory.kernel.stage_graph`
- `factory.kernel.completion_result`
- `verification_plan`
- `failure_report`
- `verification_report`
- `delivery_result`

Artifacts include a provenance envelope: `schema_version`, `version`,
`producer_type`, `producer_id`, `input_artifact_ids`,
`supersedes_artifact_id`, and `payload`.

Artifact types and gate kinds are open durable strings. The package-known
values above, plus gate checks such as `planning` and `merge_readiness`, are
not global allowlists for domain-specific workflow records.
Legacy `stage_graph` artifacts are still accepted as compatibility input for
materialization.

Root callers may author artifacts, gates, and issue dispatch prompts using
domain-specific names and payloads. These routes do not install new domain
policy into the kernel; they persist caller-authored durable records under the
same root-only authoring guard as stages, issues, checkpoints, verification,
and gate checks.

`delivery_result` remains a legacy software-delivery compatibility artifact.
New completion consumers should use `factory.kernel.completion_result`.

Factory also publishes live-only typed events on the LLM live bus as
`factory.event`. These events are not durable history in v1; they complement
the existing durable state and `factory.snapshot` messages.

Stage and issue records include stable durable identity fields
(`stable_key`, `materialized_from_artifact_id`,
`superseded_by_artifact_id`). Room placement is also recorded in
`factory_assignments`; `assigned_room_id` remains visible on stage and issue
responses as a compatibility mirror.

Known compatibility values may still exist in the internal package type
surface, but they are not the whole durable workflow vocabulary.