# 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 |
| POST | `/llm/factory/runs/:id/cancel` | Cancel one live run |
| 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 |
| POST | `/llm/factory/controller/wakes` | Run one bounded manual controller wake pass |

## Live v0 Behavior

The live run lifecycle is:

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

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.

Run records include nullable controller identity fields:
`controller_room_id` and `controller_agent`. These fields bind at most one
controller room to the run. They do not replace `factory_assignments`, which
continues to describe bounded worker and verifier execution placement.

Controller wake records are processed by
`POST /llm/factory/controller/wakes`. The first runner is manual and bounded:
it claims due wakes, posts one controller-room turn, leaves PI-visible
`factory__*` tool calls to that controller turn, and marks each wake handled,
retrying, or terminal failed.

Failed verification and failed required gates now create or reopen durable
repair issues instead of immediately making the run terminal. Required gates
that need further review persist durable review blockers so controller pause
state is visible from Factory records.

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