# `orchestrator.registry.api.runs`
<!-- generated by `orchestrator understand`; the PKG is source of truth, edits here are advisory -->

[← Episteme](../README.md) · [Architecture](../architecture.md)

**Source:** [`src/orchestrator/registry/api/runs.py`](../../src/orchestrator/registry/api/runs.py)

6 types · 6 functions · python

## Changing this safely

**Tested by** (1): `tests.registry.test_console_and_runs`

**Most depended-upon here** — a change to these reaches the most code (call graph, ≤4 hops):

- [`RunSummary`](../../src/orchestrator/registry/api/runs.py#L48) — reaches **2** symbols
- [`_iso`](../../src/orchestrator/registry/api/runs.py#L151) — reaches **2** symbols
- [`RunArtifact`](../../src/orchestrator/registry/api/runs.py#L158) — reaches **1** symbol · **no test path visible**
- [`RunArtifactsResponse`](../../src/orchestrator/registry/api/runs.py#L167) — reaches **1** symbol · **no test path visible**
- [`RunListResponse`](../../src/orchestrator/registry/api/runs.py#L59) — reaches **1** symbol · **no test path visible**
- [`StartRunResponse`](../../src/orchestrator/registry/api/runs.py#L97) — reaches **1** symbol · **no test path visible**
- [`_summarize`](../../src/orchestrator/registry/api/runs.py#L132) — reaches **1** symbol

_4 of the symbols other code depends on here have no test path the graph can see — worth a second look before changing them. Absence of a path is not proof of absence of a test: calls through an attribute chain (`obj.method()`) are skipped rather than guessed at, so indirect coverage is invisible._

## Types

### `RunArtifact`

[`src/orchestrator/registry/api/runs.py:158`](../../src/orchestrator/registry/api/runs.py#L158)

- **Extends** (1): `pydantic.BaseModel`
- **Called by** (1): [`run_artifacts`](../../src/orchestrator/registry/api/runs.py#L174)
- **Fields**: `key`, `kind`, `model_config`, `name`, `resource_id`

### `RunArtifactsResponse`

[`src/orchestrator/registry/api/runs.py:167`](../../src/orchestrator/registry/api/runs.py#L167)

- **Extends** (1): `pydantic.BaseModel`
- **Called by** (1): [`run_artifacts`](../../src/orchestrator/registry/api/runs.py#L174)
- **Fields**: `items`, `model_config`

### `RunListResponse`

[`src/orchestrator/registry/api/runs.py:59`](../../src/orchestrator/registry/api/runs.py#L59)

- **Extends** (1): `pydantic.BaseModel`
- **Called by** (1): [`list_runs`](../../src/orchestrator/registry/api/runs.py#L66)
- **Fields**: `items`, `model_config`

### `RunSummary`

[`src/orchestrator/registry/api/runs.py:48`](../../src/orchestrator/registry/api/runs.py#L48)

- **Extends** (1): `pydantic.BaseModel`
- **Called by** (1): [`_summarize`](../../src/orchestrator/registry/api/runs.py#L132)
- **Fields**: `events`, `last_action`, `model_config`, `sdlc_id`, `started_at`, `state`, `updated_at`

### `StartRunRequest`

[`src/orchestrator/registry/api/runs.py:88`](../../src/orchestrator/registry/api/runs.py#L88)

- **Extends** (1): `pydantic.BaseModel`
- **Fields**: `create_jira`, `model_config`, `source`

### `StartRunResponse`

[`src/orchestrator/registry/api/runs.py:97`](../../src/orchestrator/registry/api/runs.py#L97)

- **Extends** (1): `pydantic.BaseModel`
- **Called by** (1): [`start_run`](../../src/orchestrator/registry/api/runs.py#L107)
- **Fields**: `gates`, `model_config`, `sdlc_id`, `task_queue`, `workflow_id`

## Functions

### `_iso`

[`src/orchestrator/registry/api/runs.py:151`](../../src/orchestrator/registry/api/runs.py#L151)

- **Called by** (1): [`_summarize`](../../src/orchestrator/registry/api/runs.py#L132)

### `_summarize`

[`src/orchestrator/registry/api/runs.py:132`](../../src/orchestrator/registry/api/runs.py#L132)

- **Called by** (1 production · 3 test): [`list_runs`](../../src/orchestrator/registry/api/runs.py#L66), [`test_summarize_denied_and_failed`](../../tests/registry/test_console_and_runs.py#L92), [`test_summarize_derives_merged_state`](../../tests/registry/test_console_and_runs.py#L76), [`test_summarize_running_when_no_terminal_action`](../../tests/registry/test_console_and_runs.py#L87)
- **Calls** (2): [`RunSummary`](../../src/orchestrator/registry/api/runs.py#L48), [`_iso`](../../src/orchestrator/registry/api/runs.py#L151)

### `download_run_artifact`

[`src/orchestrator/registry/api/runs.py:201`](../../src/orchestrator/registry/api/runs.py#L201)

- **Calls** (2): `fastapi.HTTPException`, `fastapi.Response`

### `list_runs`

[`src/orchestrator/registry/api/runs.py:66`](../../src/orchestrator/registry/api/runs.py#L66)

- **Calls** (3): [`RunListResponse`](../../src/orchestrator/registry/api/runs.py#L59), [`_summarize`](../../src/orchestrator/registry/api/runs.py#L132), `sqlalchemy.select`
- **Documented in**: `docs/specs/python-frontend-parity.md#1-the-evidence`, `docs/specs/python-frontend-parity.md#51-phase-1-endpoint-exposes`, `docs/specs/python-frontend-parity.md#53-phase-3-reads-writes-separate-pr`, `docs/specs/python-frontend-parity.md#design-plan-python-front-end-parity-endpoint-entity-readswrites`

### `run_artifacts`

[`src/orchestrator/registry/api/runs.py:174`](../../src/orchestrator/registry/api/runs.py#L174)

- **Calls** (4): [`RunArtifact`](../../src/orchestrator/registry/api/runs.py#L158), [`RunArtifactsResponse`](../../src/orchestrator/registry/api/runs.py#L167), `sqlalchemy.or_`, `sqlalchemy.select`

### `start_run`

[`src/orchestrator/registry/api/runs.py:107`](../../src/orchestrator/registry/api/runs.py#L107)

- **Calls** (3): [`StartRunResponse`](../../src/orchestrator/registry/api/runs.py#L97), `fastapi.HTTPException`, [`start_run`](../../src/orchestrator/sdlc/run_control.py#L49)

## Imports

`__future__.annotations`, `fastapi.APIRouter`, `fastapi.HTTPException`, `fastapi.Request`, `fastapi.Response`, `fastapi.status`, [`orchestrator.registry.api.deps`](../../src/orchestrator/registry/api/deps.py#L1), [`orchestrator.registry.db.models`](../../src/orchestrator/registry/db/models.py#L1), [`orchestrator.sdlc.run_control`](../../src/orchestrator/sdlc/run_control.py#L1), `pydantic.BaseModel`, `pydantic.ConfigDict`, `pydantic.Field`, `sqlalchemy.or_`, `sqlalchemy.select`, `typing.Any`

## Imported by

[`orchestrator.registry.api.app`](../../src/orchestrator/registry/api/app.py#L1), [`orchestrator.registry.api.stream`](../../src/orchestrator/registry/api/stream.py#L1), [`tests.registry.test_console_and_runs`](../../tests/registry/test_console_and_runs.py#L1)
