commit 6e497b5779e9db90682cc032540553a53d0bc397
parent bd4798f92408a47f423ccd85549adae301f8b6b4
Author: I Mean I'm Just Saying <imeanimjustsaying@kiwifarms.st>
Date: Wed, 30 Sep 2026 09:34:37 -0400
docs: PUBLISH.md — the history's cap (the newest 10,000 commits: -l, the log's commits' pages only, "the latest N of M"), the render cache in ${XDG_CACHE_HOME:-~/.cache}/archilyzer/source-history, doctor's cache line
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Diffstat:
| M | PUBLISH.md | | | 53 | +++++++++++++++++++++++++++++++++-------------------- |
1 file changed, 33 insertions(+), 20 deletions(-)
diff --git a/PUBLISH.md b/PUBLISH.md
@@ -119,7 +119,7 @@ before `next build`, and:
- the step removes the LAST publish from `homepage/public` (manifest first, then the
mirror, the tree, the history pages, the tarball, `snapshot.json` and the skip key,
- and the history's render cache from the scratch root) — it was audited
+ and the history's render cache) — it was audited
under rules that may not be today's, and the refusal is the best evidence that they
are not. Any outcome but success does this once the rules are loaded (an audit hit,
a limit, a missing tool, a cancel, a crash); `--check` writes nothing, this included;
@@ -235,7 +235,8 @@ must be removed from history by hand.
without pipx it refuses with the install line). gitleaks is optional: without it the
secret scan is skipped with a WARNING and the literal audit still runs. stagit is
optional too (next section). `archilyzer doctor` has a "source publish" block: which
-filter-repo would run, stagit (its path, or not found), gitleaks, the two files (rule
+filter-repo would run, stagit (its path, or not found, and the render cache's path and
+size), gitleaks, the two files (rule
counts and modes, never contents) and the last publish.
The mirror's ids are deterministic for a given filter-repo version; an upgrade that
changes its rewriting changes every id (readers re-clone). The manifest records both
@@ -261,12 +262,14 @@ build, and the next build tries again (a stagit present and no history never ski
What the step does with it:
- It runs after the mirror is built and its objects audited: `stagit -c <cache> -u
- https://archilyzer.pages.dev/source/git/ <the scrubbed bare clone>`. The clone is
+ https://archilyzer.pages.dev/source/git/ <the scrubbed bare clone>` (past the cap,
+ `-l 10000` in place of `-c`, below). The clone is
named `archilyzer.git` (stagit names the repository after its directory); its
`description` is set to "Archilyzer" and its `url` to the clone URL, for stagit's
header. Neither file is published.
- **Only an allowlist is published:** `log.html`, `files.html`, `refs.html`,
- `atom.xml`, `tags.xml`, `commit/<sha>.html`, and a `style.css` the step writes from
+ `atom.xml`, `tags.xml`, the page of each commit the log lists (`commit/<sha>.html`),
+ and a `style.css` the step writes from
`common/styles/tokens.css` (the homepage's two grounds, light and dark; diff
insertions in `--success`, deletions in `--destructive`). **stagit's per-file
pages (`file/…`) are not**: browsing is the raw tree, so every link into `file/` —
@@ -283,26 +286,36 @@ What the step does with it:
source/git/commit/<sha>.html (contents, byte N)`) and never by its bytes. The pages
are rendered from objects the object sweep already read, so a hit there means
something stagit or the step added.
-- The manifest's `history` block has the log's href, the commit count, the head, the
- file count and bytes, a sha256 over the pages, and stagit's identity (the sha256 of
- its binary; it has no version flag). The skip key has stagit's identity and the
- pages' digest.
-- **The render cache.** stagit's `-c` keeps a commit page once rendered, so a publish
- renders only the new commits: 2 s with nothing new against 8 s for every page, at
- 1,834 commits. The cache (the cache file, stagit's output, a key) is
- `archilyzer-source-history/` in the scratch root (`ARCHILYZER_SOURCE_SCRATCH`, the OS
- temp dir by default — on a tmpfs `/tmp` that is about 140 MB of memory).
- It is used only under the same rules, step, filter-repo, stagit and header text, when
- the commit it names is an ancestor of today's head, and after a run that finished;
- one publish holds it at a time. `--force` renders every page again, `--check` never
- touches it, and a refusal removes it.
+- The manifest's `history` block has the log's href, the commits with a page and the
+ commits in all (`commits`, `total`), the head, the file count and bytes, a sha256
+ over the pages, and stagit's identity (the sha256 of its binary; it has no version
+ flag). The skip key has stagit's identity and the pages' digest.
+- **The cap: the newest 10,000 commits** (`SOURCE_HISTORY_MAX_COMMITS`). Past it, stagit
+ runs with `-l 10000`: its log lists the newest 10,000 and ends "N more commits
+ remaining, fetch the repository", and `/source/` says "the latest 10,000 of M
+ commits". `-l` does not cap the pages — stagit still writes one for every commit —
+ so the step publishes the page of each commit the log lists and no other; and stagit
+ refuses `-c` with `-l`, so past the cap every publish computes 10,000 diffstats
+ (about 5 ms each here) where `-c` computes only the new ones. The 15,000-file drop
+ below stays, as the last resort.
+- **The render cache is `${XDG_CACHE_HOME:-~/.cache}/archilyzer/source-history/`**
+ (about 140 MB at 1,872 commits; made on first use; never inside the checkout or the
+ public dir — the step renders without it there, and says so). stagit keeps a commit
+ page once rendered, and `-c` keeps its log lines, so a publish renders only the new
+ commits: 0.6 s of stagit with nothing new against 8 s for every page, at 1,834
+ commits. It holds stagit's `-c` file, its output and a key. Its pages are kept only
+ under the same rules, step, filter-repo, stagit and header text, and after a run that
+ finished; its log lines only when they end at an ancestor of today's head. One
+ publish holds it at a time. `--force` renders every page again, `--check` never
+ touches it (it renders in its own scratch), and a refusal removes it. `archilyzer
+ doctor` ends its stagit line with `cache: <path>, <size>`.
- **Its size, and the limit ahead.** At 1,872 commits (2026-09-30): 1,878 files,
141.3 MB, the largest page 5.0 MB (stagit prints "Diff is too large, output
suppressed" past 1,000 files or 100,000 lines in one commit); the whole publish is
4,396 files, and `homepage/out` 4,576. One file per commit counts against the step's
- 15,000 (of Pages' 20,000): the history is dropped with a WARNING, never the publish,
- when it would cross it. At the pace of September 2026 (about 100 commits a day) that
- is some three months away.
+ 15,000 (of Pages' 20,000); the cap keeps it at 10,006 at most. Should the rest of the
+ publish ever grow past 5,000 files, the history is dropped with a WARNING, never the
+ publish.
**Cloudflare Pages, and the traps it sets.**
