# `orchestrator.registry.api.jobs`
<!-- 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/jobs.py`](../../src/orchestrator/registry/api/jobs.py)

3 types · 10 functions · python

## Changing this safely

**Tested by** (2): `tests.registry.test_capabilities_and_jobs`, `tests.registry.test_phase_b`

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

- [`_audit`](../../src/orchestrator/registry/api/jobs.py#L74) — reaches **7** symbols
- [`_artifact_store`](../../src/orchestrator/registry/api/jobs.py#L69) — reaches **6** symbols
- [`_run`](../../src/orchestrator/registry/api/jobs.py#L113) — reaches **5** symbols
- [`CapabilityResult`](../../src/orchestrator/registry/api/jobs.py#L56) — reaches **4** symbols
- [`start_capability_job`](../../src/orchestrator/registry/api/jobs.py#L90) — reaches **4** symbols
- [`JobSummary`](../../src/orchestrator/registry/api/jobs.py#L192) — reaches **3** symbols · **no test path visible**
- [`_iso`](../../src/orchestrator/registry/api/jobs.py#L307) — reaches **3** symbols · **no test path visible**
- [`_fetch_job_rows`](../../src/orchestrator/registry/api/jobs.py#L238) — reaches **2** symbols · **no test path visible**

_5 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

### `CapabilityResult`

[`src/orchestrator/registry/api/jobs.py:56`](../../src/orchestrator/registry/api/jobs.py#L56)

- **Called by** (4 production · 1 test): [`adapter`](../../src/orchestrator/registry/api/capabilities.py#L325), [`adapter`](../../src/orchestrator/registry/api/capabilities.py#L295), [`adapter`](../../src/orchestrator/registry/api/capabilities.py#L261), [`adapter`](../../src/orchestrator/registry/api/capabilities.py#L218), [`adapter`](../../tests/registry/test_capabilities_and_jobs.py#L61)
- **Fields**: `body`, `content_type`, `filename`, `summary`

### `JobListResponse`

[`src/orchestrator/registry/api/jobs.py:206`](../../src/orchestrator/registry/api/jobs.py#L206)

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

### `JobSummary`

[`src/orchestrator/registry/api/jobs.py:192`](../../src/orchestrator/registry/api/jobs.py#L192)

- **Extends** (1): `pydantic.BaseModel`
- **Called by** (1): [`_summarize`](../../src/orchestrator/registry/api/jobs.py#L212)
- **Fields**: `error`, `events`, `has_artifact`, `job_id`, `kind`, `model_config`, `started_at`, `state`, `summary`, `updated_at`

## Functions

### `_artifact_store`

[`src/orchestrator/registry/api/jobs.py:69`](../../src/orchestrator/registry/api/jobs.py#L69)

- **Called by** (2): [`get_job_artifact`](../../src/orchestrator/registry/api/jobs.py#L280), [`start_capability_job`](../../src/orchestrator/registry/api/jobs.py#L90)
- **Calls** (1): `orchestrator.runtime.artifact_store_from_env`

### `_audit`

[`src/orchestrator/registry/api/jobs.py:74`](../../src/orchestrator/registry/api/jobs.py#L74)

- **Called by** (3 production · 1 test): [`_run`](../../src/orchestrator/registry/api/jobs.py#L113), [`drain`](../../src/orchestrator/registry/api/jobs.py#L124), [`start_capability_job`](../../src/orchestrator/registry/api/jobs.py#L90), [`test_artifact_409_before_completion`](../../tests/registry/test_capabilities_and_jobs.py#L147)
- **Calls** (1): [`AuditLogRepo`](../../src/orchestrator/registry/repositories.py#L161)

### `_fetch_job_rows`

[`src/orchestrator/registry/api/jobs.py:238`](../../src/orchestrator/registry/api/jobs.py#L238)

- **Called by** (2): [`get_job`](../../src/orchestrator/registry/api/jobs.py#L272), [`get_job_artifact`](../../src/orchestrator/registry/api/jobs.py#L280)
- **Calls** (1): `sqlalchemy.select`

### `_iso`

[`src/orchestrator/registry/api/jobs.py:307`](../../src/orchestrator/registry/api/jobs.py#L307)

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

### `_run`

[`src/orchestrator/registry/api/jobs.py:113`](../../src/orchestrator/registry/api/jobs.py#L113)

- **Called by** (1): [`start_capability_job`](../../src/orchestrator/registry/api/jobs.py#L90)
- **Calls** (6): `Queue`, [`_audit`](../../src/orchestrator/registry/api/jobs.py#L74), `create_task`, `orchestrator.runtime.make_job_artifact_id`, `suppress`, `to_thread`

### `_summarize`

[`src/orchestrator/registry/api/jobs.py:212`](../../src/orchestrator/registry/api/jobs.py#L212)

- **Called by** (2): [`get_job`](../../src/orchestrator/registry/api/jobs.py#L272), [`list_jobs`](../../src/orchestrator/registry/api/jobs.py#L253)
- **Calls** (2): [`JobSummary`](../../src/orchestrator/registry/api/jobs.py#L192), [`_iso`](../../src/orchestrator/registry/api/jobs.py#L307)

### `get_job`

[`src/orchestrator/registry/api/jobs.py:272`](../../src/orchestrator/registry/api/jobs.py#L272)

- **Calls** (3): [`_fetch_job_rows`](../../src/orchestrator/registry/api/jobs.py#L238), [`_summarize`](../../src/orchestrator/registry/api/jobs.py#L212), `fastapi.HTTPException`

### `get_job_artifact`

[`src/orchestrator/registry/api/jobs.py:280`](../../src/orchestrator/registry/api/jobs.py#L280)

- **Calls** (4): [`_artifact_store`](../../src/orchestrator/registry/api/jobs.py#L69), [`_fetch_job_rows`](../../src/orchestrator/registry/api/jobs.py#L238), `fastapi.HTTPException`, `fastapi.Response`

### `list_jobs`

[`src/orchestrator/registry/api/jobs.py:253`](../../src/orchestrator/registry/api/jobs.py#L253)

- **Calls** (3): [`JobListResponse`](../../src/orchestrator/registry/api/jobs.py#L206), [`_summarize`](../../src/orchestrator/registry/api/jobs.py#L212), `sqlalchemy.select`

### `start_capability_job`

[`src/orchestrator/registry/api/jobs.py:90`](../../src/orchestrator/registry/api/jobs.py#L90)

- **Called by** (4 production · 3 test): [`pkg_export`](../../src/orchestrator/registry/api/capabilities.py#L321), [`pkg_extract`](../../src/orchestrator/registry/api/capabilities.py#L291), [`state`](../../src/orchestrator/registry/api/capabilities.py#L253), [`understand`](../../src/orchestrator/registry/api/capabilities.py#L214), [`test_job_failure_is_recorded_not_raised`](../../tests/registry/test_capabilities_and_jobs.py#L101), [`test_job_runs_streams_progress_and_stores_artifact`](../../tests/registry/test_capabilities_and_jobs.py#L82), [`test_jobs_endpoints_list_status_and_download`](../../tests/registry/test_capabilities_and_jobs.py#L116)
- **Calls** (5): [`_artifact_store`](../../src/orchestrator/registry/api/jobs.py#L69), [`_audit`](../../src/orchestrator/registry/api/jobs.py#L74), [`_run`](../../src/orchestrator/registry/api/jobs.py#L113), `create_task`, `uuid4`

## Imports

`__future__.annotations`, `asyncio`, `collections.abc.Callable`, `contextlib`, `dataclasses.dataclass`, `dataclasses.field`, `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.registry.repositories`](../../src/orchestrator/registry/repositories.py#L1), [`orchestrator.runtime`](../../src/orchestrator/runtime/__init__.py#L1), `pydantic.BaseModel`, `pydantic.ConfigDict`, `queue`, `sqlalchemy.select`, `typing.Any`

## Imported by

[`orchestrator.registry.api.app`](../../src/orchestrator/registry/api/app.py#L1), [`orchestrator.registry.api.capabilities`](orchestrator.registry.api.capabilities.md), [`tests.registry.test_capabilities_and_jobs`](../../tests/registry/test_capabilities_and_jobs.py#L1), [`tests.registry.test_phase_b`](../../tests/registry/test_phase_b.py#L1)
