FabledCurator/ci-requirements.md

# CI Requirements — FabledCurator

> Spec: https://git.fabledsword.com/bvandeusen/CI-runner/src/branch/main/docs/process.md

## Runtime image

git.fabledsword.com/bvandeusen/ci-python:3.14

## Image deps used

- python 3.14
- ruff (analyzer for `backend/`, `tests/`, `alembic/`, `agent/`, `scripts/`)
- node (frontend job: `npm install` + vitest + vite build)
- docker CLI + buildx (`.forgejo/workflows/build.yml`: build-web, build-ml, build-agent — Fabled-Git registry push, and `imagetools inspect`/`create` for the reuse path)

## Secondary runtime image

node:24-bookworm-slim — `.forgejo/workflows/extension.yml` only.

`.forgejo/workflows/release.yml` runs on `ci-python:3.14` like everything else
and installs nothing: it needs git and stdlib python, and builds no image.

The extension lane is the one job that does NOT run on `ci-python:3.14`: it
needs a current Node for `web-ext` and vitest and nothing Python at all. Kept
on the upstream slim image rather than adding a Node toolchain to `ci-python`,
per `docs/process.md`'s "add deps to the image when used by >1 project".

## Per-job tool installs

- `pip install -r requirements.txt pytest pytest-asyncio` — in `backend-lint-and-test` and `integration` jobs
- `npm install --no-audit --no-fund` — in `frontend-build` job
- `npm install --no-audit --no-fund` — in `extension.yml`'s `lint` job (web-ext + vitest)
- `unzip` — in `extension.yml`'s "Verify XPI contents" step, installed via apt
  only when absent (`node:24-bookworm-slim` may or may not carry it). Debian
  package, ~2s. Not worth baking into a shared image for a single consumer, per
  `docs/process.md`'s ">1 project" rule.

## Notes

- Integration wall time ~3 min, dominated by pgvector container start + the
  `pip install` step (~30-45s on cold cache) + alembic + 300+ integration tests.
- The `pip install` in two jobs is intentional and per `docs/process.md`'s
  "add deps to image when used by >1 project" rule: FC alone is one Python
  project, so the deps live in `requirements.txt` and install per-job.
  Reconsider when a second Fabled-family Python backend lands.
- Integration uses Fabled-Git Actions `services:` + socket-discovered bridge IPs
  because `act_runner` (swarm-runner v0.6+) puts services on the default
  bridge with no embedded DNS. The pattern is documented in the rulebook's
  `fabled-git.md` "CI philosophy" section and FC's `build.yml` integration lane
  is the canonical example.
- No `package-lock.json` is tracked yet (FC's `feedback_no_local_runs`
  memory bans `npm install` locally). Using `npm install` rather than
  `npm ci` until a lockfile lands.
- No `imagemagick` / `pandoc` per-job installs needed.
- `extension/`'s vitest specs load `lib/*.js` by evaluating the real file as a
  classic script (`test/helpers/loadLib.js`) rather than adding `module.exports`
  shims to production code — the libs ship as `background.scripts`, not ES
  modules, so the specs exercise exactly the bytes packaged into the XPI.
- **`extension/scripts/packaging.sh` is the single definition of what ships
  inside the XPI.** Three consumers read from it rather than keeping their own
  copy: web-ext's `--ignore-files` (`extension/package.json`), the `git log`
  pathspec inside the script's own version derivation, and `scripts/artifacts.sh`,
  which appends the extension's set to web's because the web image bundles the
  signed XPI. Hand-kept copies of that one fact is what allowed issue #2397, so
  `extension/test/version.spec.js` asserts no workflow has reintroduced a
  literal `:(exclude)extension/…`.
- **Packaged and version-relevant are two different sets** (#3156). `scripts/`
  is excluded from the XPI and is NOT excluded from the version derivation,
  because `packaging.sh` decides the version string stamped into the packaged
  `manifest.json`. The membership test is *"can changing this file change the
  published bytes?"*, not *"is this file copied in?"* — which is why the script
  keeps two lists rather than one.
- **The shipped extension version is derived, not committed.** It is the commit
  TIME of the newest packaged-extension change, rendered `YYYY.M.D.HHMM` UTC
  (family rules 148/149 — never a commit count, which orders by branch rather
  than by recency). `build.yml`'s `sign-extension` computes it and stamps it
  into `extension/manifest.json` + `package.json` in the working tree before
  signing; the stamp is never committed. The version in the repo is **wholly
  inert** — since milestone 318 step 8 there is no hand-set MAJOR.MINOR either.
- **The extension is the one artifact that does not zero-pad, and that is not a
  drift** (#3138). Mozilla's grammar for AMO is
  `^(0|[1-9][0-9]{0,8})([.](0|[1-9][0-9]{0,8})){0,3}$` — a segment is the single
  digit `0` or starts 1-9, and there are at most four. `2026.08.29.0201` is
  rejected; `2026.8.29.201` is the same value one character narrower per
  segment, and rule 148 defines comparison as numeric per segment, so nothing is
  reordered. `build.yml`'s `extension-version` lane asserts the derived string
  against that exact regex, plus a `YYYY.M.D.HHMM` shape check that would catch
  a regression to the pre-318 `1.0.<minutes>` — which AMO would accept and which
  orders below everything already signed. Checking here is the whole point: AMO
  409s on re-signing, so a version it rejects is burned and cannot be reused.
  `scripts/artifacts.sh version extension` **delegates** to `packaging.sh` so
  the two cannot answer differently.
- Every job that derives anything checks out with `fetch-depth: 0` — all four
  publishing `build.yml` jobs, its `extension-version` and `backend-lint-and-test`
  lanes
  (for `tests/test_artifact_paths.py` and `test_artifact_identity.py`), and
  `release.yml`, which additionally walks the tag graph. A depth-1 clone sees
  one commit and derives a wrong, too-low value **rather than failing**, so the
  full-history checkout is load-bearing rather than incidental.
- **`scripts/artifacts.sh` is the same shape one level up: one definition per
  artifact of what it is built from, and the two values derived from it.**
  `revision` (12 hex of the newest commit touching that set) and `version`
  (`YYYY.MM.DD.HHMM` UTC, rule 148). Three artifacts, three independent
  answers, so a push touching only `agent/` leaves web and the extension alone.
  `tests/test_artifact_paths.py` reads each Dockerfile and asserts every COPY
  source is covered, so adding a COPY without updating the script fails CI.
- **A file that DECIDES an artifact's identity belongs in its set even though it
  is copied into nothing** — `packaging.sh` for the extension and web (#3156),
  and `artifacts.sh` itself for web (#3202), which decides the `FC_VERSION`
  baked into that image. Only web needs the second entry: every artifact stamps
  a revision, but a revision has a backstop (a changed derivation stops matching
  the published label and forces a rebuild) and a version has none, because
  nothing compares it to anything. `tests/test_artifact_paths.py`'s `DERIVERS`
  table is the guard.
- **Builds are skipped when the content is already published.** Each image
  carries its revision as an `fc.revision` LABEL, and `build.yml` reads that
  label back off the moving channel tag (`imagetools inspect --format`). Equal
  to the derived revision means the bytes are already published, so the job
  repoints the remaining tags at the existing manifest instead of rebuilding.
  Two things this depends on: an inspect that errors for ANY reason reads as a
  MISS so no needed build is ever skipped, and the repoint must EXCLUDE the
  source tag — `imagetools create` wraps its source in a manifest index, and
  config labels do not resolve through an index, so writing the channel tag
  from itself destroys the label the next run reads (#3183).
- **The build pushes exactly ONE tag — the channel's — and every other tag is
  written registry-side afterwards** (#3190). buildx on this runner pushes the
  first tag to the registry and then re-pushes the rest through the docker
  driver, out of a local image store that a registry-direct build never fills;
  it fails intermittently with `tag does not exist`. On `dev` that only reddens
  a job, but on `main` it silently skips `:c-<sha>` while `:latest` publishes
  fine — a missing rollback tag has no consumer that fails, so nothing but the
  red job would notice until somebody needs to roll back. `imagetools create`
  has no local store to be absent from, and it is the code the reuse path
  already ran, so both paths now share one proven route. The cost: `:c-<sha>`
  is an index rather than a plain image, so `fc.revision` does not resolve
  through it — nothing reads it there, and the index names the same manifest.
- **The image builds run on a `docker-container` buildx builder, and
  `provenance`/`sbom` are explicitly OFF** (milestone 326 step 1). The builder
  is what makes a registry layer cache possible at all — the default `docker`
  driver cannot export one (#3114) — and it is #3190's leading suspect, since
  it is the driver that resolves image metadata against a local store a
  registry-direct push never fills. **The attestation flags are load-bearing,
  not tidiness:** on the container driver `build-push-action@v5` defaults
  `provenance` to true when pushing, an attestation manifest makes the pushed
  tag a manifest INDEX, and config labels do not resolve through an index — so
  leaving them on would make every push read `fc.revision=<none>`, miss, and
  rebuild forever with every lane green. Same failure as #3183, different door.
  These jobs run inside a container against a mounted docker socket, so the
  buildkit container is a sibling rather than a child.
- **All three images import and export a registry layer cache**
  (`<image>:buildcache`, `mode=max`). This is not an optimisation bolted onto
  the driver change — it is the other half of it. The `docker-container`
  driver gets a fresh buildkit instance per job and therefore has **no local
  layer store at all**, where the old `docker` driver at least reused whatever
  the runner's dockerd happened to hold. Measured on run 4896, the first builds
  after the driver moved: web 3m44s (was 2m23s), ml 3m49s (was 3m20s), agent
  11m12s (was 9m26s) — every one slower. (`ml` was its own build then; #4311
  retired it once it became the same bytes as web under a second name.) A `:buildcache` tag is read by every
  build that runs, is one moving ref per image, holds cache blobs rather than a
  shippable artifact, and is overwritten in place, so it is not a return of the
  per-version tags milestone 318 withdrew (#3114).
- **`build.yml` accepts a `workflow_dispatch` with `force_build`**, which
  bypasses the reuse check for all three images. It exists because
  skip-if-exists makes its own build path untestable: `agent/` has not changed
  since 2026-07-17, so the agent build has not run in six weeks and cannot be
  exercised on demand — and #3190 lives on exactly that path. Editing
  `build.yml` does not force a build either, deliberately: the workflow is not
  shipped bytes and is in no artifact's path set. The flag is read through
  `github.event.inputs` into an env var rather than interpolated into a run
  block, and it is checked inside the reuse step so that one decision drives
  both the build and the repoint.
- **A weekly `schedule` rebuilds all three images against fresh base layers**
  (Sunday 06:00 UTC, milestone 326 step 4, #3154). Skip-if-exists is keyed on
  OUR source, so an artifact whose source stops moving stops picking up base
  updates — `agent/` has not changed since 2026-07-17 and would otherwise serve
  that day's `nvidia/cuda` layers forever. Four things make it work:
  - It **builds `main`, not the branch that triggered it.** Forgejo registers a
    cron from the DEFAULT branch (`dev` here), so a scheduled run arrives with
    `github.ref` on dev. The ref is decided once in a top-level `env:
    BUILD_REF` that every checkout in the file takes, rather than per job —
    otherwise `sign-extension` would derive dev's extension version while
    `build-web` bundled main's, and the release download would 404 on a version
    that exists perfectly well. Every job then ASSERTS its checkout is `main`
    before doing anything, because `env` inside `with:` is not a context this
    runner is known to evaluate — if it silently resolved to empty, checkout
    would fall back to the triggering ref and the refresh would publish dev's
    source to `:latest` with every lane green.
  - It **publishes only `:latest`.** `:c-<sha>` for main's HEAD already names
    the bytes that commit built; re-pushing it over refreshed layers would
    break the one tag rule 145 makes immutable, and it is the rollback unit.
    The repoint step needs no schedule case for this — the tag list is the
    channel tag alone, so SOURCE is the only entry, it is excluded as always,
    and the step correctly does nothing.
  - **`:latest` and `:c-<sha>` therefore diverge between a refresh and the next
    `main` push, by design.** They re-converge on that push: it hits reuse (a
    refresh does not move `fc.revision`, because it does not touch the source),
    and the repoint writes the NEW `:c-<sha>` from the refreshed `:latest`. The
    push path needed no change for this, because the repoint already excluded
    the source tag — the same rule that keeps the label readable also keeps a
    refresh from being undone.
  - **`pull: true` on the scheduled path only** is the mechanism: a moved base
    tag changes the `FROM` layer's cache key and everything above it rebuilds.
    It did not always make the unmoved case free. Measured on the first real
    fire (run 4934, 2026-08-30): every content step reported `CACHED` and the
    bases resolved to unchanged digests, yet all three `:latest` tags got a NEW
    manifest digest, because buildkit stamps a fresh image config per run and
    republishes identical layers under it — so `:latest` was rewritten weekly
    whether or not anything changed, and a digest change stopped meaning
    anything (#3265).
  - **`SOURCE_DATE_EPOCH` is what makes it free.** Set on each build step from
    `artifacts.sh epoch <artifact>` — the unix timestamp of the same commit
    `revision` and `version` name, so all three are views of one `newest()`
    lookup and cannot drift into disagreeing. With the config's `created` field
    and history timestamps pinned to the content rather than to the wall clock,
    identical source produces an identical manifest digest and the push is a
    registry no-op. That restores the property the whole scheme rests on: a
    channel tag's digest changes when, and only when, its content does.
    Separately not caught: a Debian package update inside the `apt-get install`
    layer while the base tag stands still — a lag rather than a hole, since the
    official python/cuda images rebuild with those updates baked in.
- **`FC_CHANNEL` and `FC_VERSION` are build args, not runtime settings.**
  `build.yml` passes them to the web image only — the ml and agent images have
  nothing to report them to. `/api/health` returns both, the foot of Settings
  renders them, and `/api/extension/manifest` reports the channel beside the
  extension version so an install can be traced to a channel. With no version image tags, that
  self-report is the ONLY answer to "which build is this?" — which is why a
  missing version renders `unknown` rather than a blank: an empty footer reads
  as "no version", a different and false claim.
  Both are declared LAST in the Dockerfile on purpose: an ARG invalidates every
  layer below it, and these are the values that differ between the dev and main
  builds of identical source, so placing them earlier would stop the two
  channels ever sharing a cached `pip install`. Empty by default — a local build
  then reports nothing rather than claiming a channel it is not on.
- **The channel is never folded into the version.** A `-dev` suffix makes the
  extension's per-segment `parseInt` comparator read that segment as 0, so every
  dev build compares equal to every other — issue #2993 exactly (rule 149).
  `frontend/test/systemBuild.spec.js` pins the rendered version to the bare
  number.
- Callers MUST `set -f` before substituting the script's output. Without it the
  shell expands `test/**` against the working tree and silently narrows the
  pattern to whatever files exist at that moment — a failure that looks like
  nothing until dev files start appearing in the XPI. `test/version.spec.js`
  asserts every `--ignore-files` consumer sets it, and that no consumer has
  quietly reinstated a hardcoded list.