serve: /api/v1/artifacts silently truncates at limit=1000 (repo has 1017) — no truncation signal in the response

[avrabe]

Summary

/api/v1/artifacts caps limit at 1000 (rivet-cli/src/serve/api.rs:459, same
at :630). The rivet repo now holds 1017 artifacts. A client asking for
everything gets 1000 rows back with no indication that 17 were dropped.

Reproduce

$ rivet serve --port 8791 &
$ curl -s "http://127.0.0.1:8791/api/v1/artifacts?limit=1000&origin=all" \
    | python3 -c "import sys,json; d=json.load(sys.stdin); \
        print('total:', d['total'], 'returned:', len(d['artifacts']))"
total: 1017 returned: 1000

Why this is a weak-green defect, not just a cap

A cap is fine. A silent cap is not. The response carries total: 1017 next to
a 1000-element array, so the data needed to detect truncation is present — but
nothing in the response says "this is a partial view", and every consumer that
reads artifacts as the full set is silently wrong. This is the same shape as
the v0.33.0 gate work: the call succeeds, the payload looks complete, and the
missing part is invisible.

Two concrete consequences already visible:

1. Tests can encode a false premise. serve_integration.rs:569 asserts
   externals_unscoped > 0 on origin=all&limit=1000, i.e. it assumes that
   window contains every artifact. It does not. The externals happen to sit at
   positions 0–3 today, so it passes — by luck of ordering, not by construction.
2. Ordering is non-deterministic on main, so which 17 fall off the end
   varies run to run. Measured over 3 identical runs against the same store, the
   external block came back PROC, REQ, SYS, THR / REQ, THR, SYS, PROC /
   PROC, REQ, SYS, THR. (Overlapping sources make every id collide with itself (184 phantom errors masked 6 real); non-deterministic output order breaks report diffing #746 / fix(validate): dedupe overlapping sources + deterministic diagnostic order (#746) #759 addresses the determinism half.)

Combine the two and you get a silently truncated, non-deterministically ordered
"give me everything" response — which is a bad foundation for a dashboard, an
export, or an assertion.

Suggested fix

Cheapest honest version, in order:

1. Say so in the payload. Add truncated: true (or returned alongside
   total) whenever artifacts.len() < total. Consumers can then fail loudly
   instead of guessing.
2. Make the window deterministic so truncation is at least reproducible —
   stable sort by id when no explicit sort is requested. (Overlapping sources make every id collide with itself (184 phantom errors masked 6 real); non-deterministic output order breaks report diffing #746 / fix(validate): dedupe overlapping sources + deterministic diagnostic order (#746) #759 does this
   for the source/diagnostic side.)
3. Decide the cap deliberately. Either keep 1000 and document it as a
   paging boundary with a working offset/cursor, or let limit=0/limit=all
   mean "no cap" for the machine-readable endpoint.

Step 1 alone converts this from silent to detectable and is worth doing on its
own.

Related

• fix(validate): dedupe overlapping sources + deterministic diagnostic order (#746) #759 / Overlapping sources make every id collide with itself (184 phantom errors masked 6 real); non-deterministic output order breaks report diffing #746 — determinism half; found while diagnosing its CI failure
• Declare cited-source on the verification types (sw/unit/sys-verification) + a native 'named-test-exists' check — make requirement→test evidence drift-checked #556, Silent empty load: a config typo yields 0 artifacts, validate PASSes and coverage reports 100.0% #808 — same "the check passes and checks nothing" family

[avrabe]

Triage note (scheduled routine, first pass on this issue — filed 2026-08-20, no prior comments).

The body pins the defect precisely: the response carries total: 1017 next to a 1000-element artifacts array, so the information to detect truncation is already on the wire — nothing in the payload just says "this is a partial view". That's a one-field fix (Suggested-fix step 1) which converts silent to detectable and is worth landing on its own. Steps 2 and 3 (deterministic sort, decide-the-cap-deliberately) are separable — step 2 overlaps with #746 / #759's determinism half (already in flight as PR #759), and step 3 is a paging/API design call that shouldn't gate step 1.

There's no explicit ## Acceptance Criteria block on the body yet, so the routine can't autopick this without one. Sketch matching the kill-criterion shape used across #468 / #567 / #787 / #809 (drop in / revise):

## Acceptance Criteria — /api/v1/artifacts: signal truncation explicitly

- [ ] Whenever `artifacts.len() < total` for a `GET /api/v1/artifacts`
      response, the JSON payload carries a `truncated: true` field
      (top-level, alongside `total`). When `artifacts.len() == total`,
      `truncated: false` (present, not absent — machine consumers can
      then rely on `if not payload["truncated"]: assume_complete()`
      without a `.get()` dance). Same guarantee at both `api.rs:459`
      and `:630` — the two locations the body identifies.
- [ ] Optionally in the same JSON object: `returned: <int>` (equal to
      `len(artifacts)`) — redundant with `len(artifacts)` but makes a
      pretty-printed / paginated payload self-describing without the
      consumer having to iterate. Cheap; include unless it clashes
      with the existing serve contract.
- [ ] Regression fixture: an integration test under
      `rivet-cli/tests/serve_integration.rs` seeds a store with
      **>1000** artifacts (e.g. via a helper that generates
      N synthetic ids), fires `GET /api/v1/artifacts?origin=all&limit=1000`,
      and asserts (a) `total > 1000`, (b) `len(artifacts) == 1000`,
      (c) `truncated == true`. Companion assertion:
      `?limit=1000` against a <1000-artifact store returns
      `truncated == false`.
- [ ] The existing `serve_integration.rs:569` assertion
      (`externals_unscoped > 0` on `origin=all&limit=1000`) either
      widens the window past the cap for its own precondition, or
      pins the sort so the externals are known to sit inside the
      first 1000 — the body notes this test currently passes by
      luck of ordering. Not blocking on step 2 (determinism) since
      pinning a `sort_by(|a, b| a.id.cmp(&b.id))` at the assertion
      site alone is a one-line hedge that removes the coincidence.
- [ ] `rivet validate` PASS. `cargo test -p rivet-cli --test
      serve_integration` green. `cargo fmt` /
      `cargo clippy --all-targets -- -D warnings` clean.
- [ ] Commit trailers: `Fixes: REQ-NNN` (file a new REQ for
      serve-API completeness signalling if one doesn't already
      exist; else reuse the closest serve-contract REQ) +
      `Refs: #832, #746`.
- [ ] **Explicitly out of scope (file separately if wanted):** the
      `sort_by(|a, b| a.id.cmp(&b.id))` stable-order default across
      the endpoint (Suggested-fix step 2 — overlaps with #746 / #759,
      cleaner to land there than to fork here); the cap-value
      decision itself (Suggested-fix step 3 — keep-1000-and-page
      versus `limit=0`/`limit=all`, both API-surface calls that
      warrant their own issue plus a paging cursor).

Adjacent state worth flagging:

• The determinism half is already tracked and in flight — PR fix(validate): dedupe overlapping sources + deterministic diagnostic order (#746) #759 (fix/issue-746-source-overlap-dedup-and-determinism) covers LifecycleGap.missing sorting and eight store.iter() sites in rivet-core/src/validate.rs. The serve endpoint isn't in its diff, so a sort_by at api.rs:459 / :630 is an independent follow-up rather than a duplicate. If the two land in the same release, the "silently truncated, non-deterministically ordered" combination the body describes disappears cleanly.
• Same "passes and checks nothing" family the body puts this in (ci: Test job silently falls back to cargo test, producing no JUnit XML and losing retries — three stacked silencers #833 / Silent empty load: a config typo yields 0 artifacts, validate PASSes and coverage reports 100.0% #808 / check verification-evidence is useless as a gate: blind to nested workspaces (false fail) + satisfied by an empty stub (false pass) #807 / Declare cited-source on the verification types (sw/unit/sys-verification) + a native 'named-test-exists' check — make requirement→test evidence drift-checked #556) — worth eventually filing a meta-issue that enumerates the remaining silent-degradation surfaces once a few more of these are converted.

Process side-rail: consulted https://pulseengine.eu/blog/ at the start of this run — 200 OK. The closest workflow-relevant post is "Where the seams still show" (toolchain-maturity lens: wired-in-CI / demonstrated-once / still-manual) — this is precisely a "wired-into-serve-but-silently-not-truthful" case, and the truncated flag promotes it from demonstrated-once (via manual curl | jq) to wired-in-response. Nothing on the blog speaks to per-issue AC shape.

Not implemented this run.

---

Generated by Claude Code

[avrabe]

Opened #864 — Step 1 from the issue: /api/v1/artifacts and /api/v1/diagnostics now emit count and truncated alongside total, matching the shape rivet query --format json already uses. Additive-only, so existing consumers reading total + artifacts stay unaffected; new consumers can fail loudly instead of quietly treating a partial view as the full set. Determinism (#746 / #759) and the cap-as-paging-boundary decision are deliberately left for follow-ups.

---

Generated by Claude Code