T1 persistence: save/load/invalidate the universal registry cache (implementation plan)

[StefanKarpinski]

Implementation plan for persisting the T1 artifact, written so a fresh Claude instance (or human) can execute it without further design work. Prereqs all merged: #49 (Problem/constraints as resolve-time data), #50 (T1 = universal per-registry cache; provider has zero query-dependent parameters), plus the caching design notes on #47 (two comments: "cache T1, everything else per-resolve" and the make-style T0/T1 tiering).

What to build

Two cache tiers, make-style dependencies (see #47):

• T0, per registry: the parsed provider output for ONE registry — the expensive part (~2.3s parse for General). Keyed by identity header (registry UUID, registry tree hash, T0 format version). A registry changes → re-parse that one T0.
• T1, per active registry SET: the pkg_info output for all packages (dependency closure of everything + arc-consistency + interchangeability classes) built from the merged T0s. ~1–1.5s to rebuild registry-wide. Its cache record stores the list of T0 identity headers it was built from plus a T1 builder version. Staleness check = header comparison, no content hashing at check time. Any mismatch or set change → rebuild T1 (cheap, per the numbers in Caching design for Pkg integration: tiers, artifacts, and open questions #47/T1 preprocessing: a universal per-registry cache #50).

Post-#50, the T1 artifact is query-independent (ordering, compat, pins, prereleases, yanked, julia bound are all per-resolve), so ONE artifact per registry state serves every resolve — the correctness model is requirement-subset monotonicity (T1 built for all packages serves any reqs; theory in docs/src/theory/layered.md, "filtering for a larger requirement set" + the rewritten cache-tier paragraph).

Where things are

• src/PkgInfoFiles.jl: existing versioned serialization (format v2) for pkg-info dicts — extend, don't replace. Note PkgInfo gained a classes field in T1 preprocessing: a universal per-registry cache #50, recomputed on load via the 4-arg constructor (it's a function of the conflicts matrix). Decision to make: keep recomputing (~0.45s registry-wide, pass 2 of the class scan is 11–15× pass 1) or bump the format and store class ids. Storing is probably right for a cache whose entire point is amortization — measure both, say which won.
• bin/Registries.jl: the provider. T0 = its per-registry parse. Today it merges all reachable_registries() up front; the T0 tier needs the parse decomposed per registry with merge-on-load (the merge is cheap; parsing is not). Registry tree hash: Pkg.Registry.RegistryInstance exposes the registry's tree info (reg.tree_info; verify the field name on both supported Pkg versions — bin/ has established patterns for Pkg version differences).
• bin/resolve.jl: wiring + a --cache[=dir] flag (default e.g. ~/.julia/scratchspaces/<Resolver-UUID>/t1cache via Scratch-like layout — but bin/ avoids extra deps; a dot-dir under DEPOT_PATH[1] is fine).

Blocker

Whole-registry pkg_info currently crashes on Python_jll's malformed compat entry — see the dedicated issue (#54). Fix that first (one-line tolerance in compat_uuid_pairs).

API sketch

cached_pkg_info(; cache_dir = default_cache_dir()) :: Dict{UUID,PkgInfo}

1. Enumerate active registries → current T0 identity headers.
2. T1 record exists AND its stored headers == current headers AND builder version matches → load T1, done.
3. Else: for each registry whose T0 is stale/missing, re-parse and save T0 (atomic rename); build T1 from T0s; save with the header manifest; return.

Concurrency: write-to-temp + atomic rename for both tiers; a stale reader never sees a torn file. No locking needed beyond that (last writer wins; content is deterministic for identical inputs).

Tests

1. Roundtrip equality: resolves from a loaded T1 are identical to from-scratch resolves — reuse T1 preprocessing: a universal per-registry cache #50's one-artifact-serves-every-query harness (orderings × admission settings × julia bounds × reqs).
2. Invalidation: mutate one T0 header → exactly that registry re-parses and T1 rebuilds; unchanged headers → pure cache hits (assert via timing or a parse counter).
3. Set change: add/remove a registry from the active set → T1 rebuild.
4. Format version bump → clean rebuild, no crash on old files.
5. Atomicity: a truncated/corrupt cache file → falls back to rebuild, never errors out of resolve.

Numbers to report

Cold (no cache) vs. warm (T1 hit) vs. registry-bumped (one T0 stale) end-to-end bin/resolve.jl times; cache file sizes (whole-registry T1 was unmeasurable pre-#54 — the DiffEq-closure artifact is 17 MiB in memory as a reference point).

🤖 Opened with Claude Code at Stefan's request.
https://claude.ai/code/session_016p2sckwc5Gjjg5LG6gdEk7

[StefanKarpinski]

Two things in this plan have changed since it was written; the plan is otherwise still the plan.

The blocker is cleared. #54 (Python_jll's compat entry naming a non-dependency) is closed, and there is a regression test for it in bin/test/runtests.jl ("compat naming a non-dependency is inert"). Whole-registry pkg_info no longer crashes, so the "fix that first" step is done.

The representation changed underneath the format decision. The plan says PkgInfo gained a classes field in #50, recomputed on load via the 4-arg constructor, and poses the open question of whether to store class ids instead. #71 then made interchangeability classes the representation rather than an annotation on a version-indexed structure — one matrix row per class, member filtering per resolve, deactivation for empty classes. So the question is no longer "recompute or store a derived field" but "what is the on-disk form of the class-space artifact", which is a different and slightly larger design question. The measure-both-and-say-which-won instruction still applies; the two things being measured are different.

Also worth noting for whoever picks this up: the artifact is more reusable than the plan assumed. #75 established that a universe filtered for a query is valid for every relaxation of that query (Theorem C), so a persisted artifact serves not only any requirement subset but any relaxation of the constraints it was built under.

Everything else — the T0/T1 tiering, the identity-header staleness check, per-registry parse decomposition in bin/Registries.jl, the --cache flag — is unaffected.

[StefanKarpinski]

Still unstarted on main (d59bcd2): there is no cached_pkg_info, no --cache flag, and bin/Registries.jl still merges all reachable_registries() up front, so nothing is decomposed per registry. Every resolve pays the full parse and build.

One thing the plan poses as an open question has partly answered itself. The 2026-08-17 update said the format question had changed shape — from "recompute or store the derived classes field" to "what is the on-disk form of the class-space artifact". Since then src/PkgInfoFiles.jl has been carried forward through the representation changes and is at format v4, storing classes, members, and (since #90) each class's shadows. So the serialization already is class-space-shaped and already survived two representation changes without being rewritten. Whoever picks this up should extend v4 rather than treat the on-disk form as an open design question.

The measure-both instruction still applies and now has a concrete pair: load-and-recompute versus load-as-stored, on an artifact that has grown shadows since the numbers in the plan were taken.

Why this is the one that matters for shipping. #62 lists this as a parity gap, and it is now the only remaining one — #61 (weak deps) closed with #82. For julia-downgrade-compat, which runs in CI and pays a cold start every time, and for interactive Pkg use, a full registry parse per resolve is the difference between usable and not. Nothing else on the roadmap has a comparable effect on how the resolver feels to use.

Everything else in the plan — T0/T1 tiering, identity-header staleness checks, atomic rename, the test list, the numbers to report — is unaffected and still the plan.

---

🤖 Triaged with Claude Code.

[StefanKarpinski]

Measured what a resolve actually pays, because this plan's headline numbers (~2.3s to parse General, ~1–1.5s to rebuild T1) are whole-registry figures from the #47 artifact experiments, and a normal resolve never builds the whole-registry artifact. On main + #115:

import Pkg + Resolver        311 ms
include Registries.jl       3981 ms   stdlib tables + julia_versions.json (+ JIT)
enumerate registry pkgs      465 ms
registry_provider            0.9 ms   (a 1149 ms first call is JIT, not work)

                          cold      warm    closure
Plots     pkg_info         132 ms    83 ms   443 pkgs
          prepare           23 ms    20 ms
          resolve            21 ms    21 ms
Makie     pkg_info         473 ms   186 ms   632 pkgs
          prepare            34 ms    34 ms
          resolve            59 ms    61 ms
DiffEq    pkg_info         485 ms   388 ms   822 pkgs
          prepare            98 ms   133 ms
          resolve           111 ms   100 ms

Three corrections to how this issue has been justified (mine, in earlier comments, not the plan's):

1. It is not a parity gap with Pkg. Pkg does not cache parsed registry data either. package_info(entry) in bin/Registries.jl is Pkg.Registry.init_package_info!, and pkg_info(reg, problem) walks only the requirement closure — so Resolver is exactly as lazy as Pkg, using Pkg's own per-package parse and cache. I called this the last remaining parity gap; that was wrong, and #82 closing weak deps left no parity gap of this kind at all.

2. The closure is small. Even DifferentialEquations touches 822 packages of ~14,000. The whole-registry cost this plan is built around is not on the path.

3. A registry cache would not address the expensive part. The eager per-process cost is dominated by include(Registries.jl) — the 2 MB julia_versions.json parse and the HistoricalStdlibVersions tables — which are registry-independent. A T0/T1 registry cache touches none of it. (I cannot cleanly separate JIT from real work in that 3981 ms without more effort; some fraction is compilation, which is a precompilation question rather than a caching one.)

What the cache would actually buy

The registry-dependent, cacheable work is pkg_info plus prepare: ~105 ms (Plots) to ~520 ms (DifferentialEquations) per query, warm. Against a ~5 s cold process that is small; against a warm repeated resolve of the same closure it is roughly half the time, since resolve itself is only 20–100 ms.

So this is a real but modest optimization — a few hundred milliseconds on repeated resolves of the same closure — not the difference between usable and not, which is what I claimed on 2026-09-09. It stays open because the win is real and the design is sound; it is no longer first on #64's list.

What would justify scheduling it

A number nobody has: how much of the eager ~4 s is work rather than JIT, and whether the thing worth caching is the registry data at all or the julia_versions.json/stdlib tables beside it. If it is the latter, that is a different and much smaller change than this plan — and it would help every invocation rather than only repeats.

Held to the same bar as #60 and #91: measure first, then schedule.

Everything in the plan body — T0/T1 tiering, identity-header staleness, atomic rename, the test list — remains sound as a design. It is the priority that was wrong, not the approach.

---

🤖 Measured with Claude Code.