docs/large-files.md

1# Large files and binaries
2
3## Current limits and behavior
4
5Artifacts documents **32 MB per individual file or blob** and **1 GB per
6repository**. These are provider limits, not promises that every operation here
7can handle those sizes. See the [Artifacts limits](https://developers.cloudflare.com/artifacts/platform/limits/).
8The provider's [documented Git protocol](https://developers.cloudflare.com/artifacts/api/git-protocol/) does not advertise Git LFS support;
9do not assume an LFS upload endpoint exists.
10
11The server-side `submit_work` commit API accepts text file contents only (UTF-8
12strings, at most 200 files within a bounded 1 MiB request). It is unsuitable for
13binary uploads. Git transport can carry binaries within its own bounds, but
14review reports binary changes as **binary**, without an image preview or a text
15diff. Every agent fork stores its own repository copy, so checked-in assets
16multiply storage and transfer work across forks; budget for those copies.
17
18## Oversized-file container check
19
20The registered `large-files` check in `.forkhorse/checks` is a **full-tier** check
21using the `default` container image. One Node command scans the exact reviewed
22checkout's filesystem metadata and fails on any regular file whose size is
23**10 MB or more**, using decimal MB: **10,000,000 bytes**. Its failure names the
24file and byte size, cites the 32 MB Artifacts limit and points here. It excludes
25all `.git` entries, does not follow symlinks and never reads file contents.
26
27The former repository-wide quick check exceeded the quick tier's 10-second
28deadline during the operator's live run because it made serial stat RPCs for
29260 files. It is no longer registered. `.forkhorse/quick/large-files.js` remains
30an unregistered example for small snapshots. `ctx.stat` remains available: it
31returns the blob's size and a NUL heuristic from only the first 8 KiB, subject
32to the existing quick-tier budgets. See the [quick-check API](receipts.md#quick-checks-fh-010).
33
34This is a review-time guard with headroom, not a pre-push hook. A file rejected
35by Artifacts cannot reach review. Removing a large file from the latest commit
36also does not remove its blob from Git history. The check observes the snapshot,
37not total historical repository storage. Container checkout, Git transport,
38execution deadline and receipt limits still apply; a passing snapshot check is
39not a guarantee that a repository fits the provider's 1 GB limit.
40
41## Roadmap: LFS-compatible storage on R2
42
43The following is planned work; none of it is implemented or live in this packet:
44
45- Store large objects in R2 behind an LFS-compatible service, keeping small
46  pointer files in Git.
47- Use claims as LFS locks to coordinate edits to binary assets.
48- Verify referenced objects and their integrity during promote before moving
49  the canonical ref.
50- Show image previews in review for supported assets.
51
52This requires a separate design for authorization, object lifecycle and storage
53costs. No R2 binding, LFS endpoint, locking protocol or preview service is added
54by this check.
55