initial commit

2026-05-23 16:41:20 -04:00
commit 8fde024281
15 changed files with 803 additions and 0 deletions
@@ -0,0 +1,53 @@
+# ADR-0006: Artifact handling and transport
+
+**Status:** Accepted — 2026-05-23
+
+## Context
+
+Jobs must "transmit artifacts when done." For a chat completion the obvious
+artifact is the assistant's text/tool-call output, but the term is deliberately
+broader: a job may produce structured data, multiple named outputs, or content
+too large to embed comfortably in a webhook body.
+
+## Decision
+
+An **artifact** is a named, typed blob attached to a completed job:
+
+```json
+{ "name": "completion", "content_type": "application/json", "size": 1234,
+  "inline": { ... }, "url": null }
+```
+
+- The primary completion is always emitted as an artifact named `completion`
+  (the native-Ollama response shape), so there is one consistent access pattern.
+- Additional artifacts use distinct names.
+
+### Transport: inline vs fetch
+
+- **Small artifacts** (under a configurable threshold, default ~256 KB) are
+  delivered **inline** in the `done` webhook (`inline` populated, `url` null) and
+  in `GET /jobs/{id}`.
+- **Large artifacts** exceed the threshold: the webhook/`GET` carries metadata
+  plus a `url` (`GET /jobs/{id}/artifacts/{name}`), and the bytes are fetched
+  on demand. This keeps webhook payloads bounded and avoids shipping megabytes
+  through a callback POST.
+
+### Retention
+
+Artifacts are stored alongside the job in SQLite (ADR-0008) and pruned with the
+job after a configurable TTL. No separate blob store in v1; revisit only if
+artifact sizes outgrow SQLite comfort (single-digit MB).
+
+## Consequences
+
+- One uniform way to read output (`completion` artifact), extensible to richer
+  jobs later without protocol changes.
+- Webhook bodies stay small; large outputs don't bloat or break delivery.
+- A pull endpoint for artifacts means a missed/oversized webhook never loses data.
+
+## Alternatives considered
+
+- **Always inline.** Simple but risks huge webhook bodies and SQLite row bloat in
+  the hot path. Rejected.
+- **External object store (S3/MinIO) from day one.** Over-engineered for the
+  expected sizes; deferred behind the TTL/threshold knobs.