Generated from
cat-harness/sdlc/processes/cache.bpmnbygen-processes-viz.ts— do not edit here. All processes · cat-harness processes
The cache process: restore and save every cache a run can use
Process_Cache · advisory · 9 step(s)
One optional process for every cache in the harness, used by render, CI, publish and every other consumer, whose components run in parallel where they are independent and in order where they are not. The rule every component follows is the skill cache-first-ci: a step is a pure function of its inputs; the key is DERIVED from them (cache:key, a lock digest, key.sh), never hand-listed; on a hit restore and skip, on a miss build and save; the full set still runs on main and nightly.
OPTIONAL, AND SKIPPING IS ALWAYS CORRECT. Every consumer — the render pipeline, the code-quality gates, feature staging and the preview, publish, the docs-site publish, the merge train, and a committer’s local mount — may call it as a call activity, once with phase restore before its own work and once with phase save after that work came back green. A consumer that does not call it, or a run that cannot reach a store, simply builds: every component’s miss is the consumer doing its own work, so this process can cost a run time, never correctness.
PARALLEL WHERE INDEPENDENT, IN ORDER WHERE NOT. The layers come first, because every other component reads mounted content. Then the prepared image and node_modules, the bun/pip downloads, the gate results and the generated sets restore side by side. Then the compiled Lean artefacts. Then the render seed (derive:publish’s writer records) and the FHIR IG ASTs side by side; the IG ASTs in their own lane, as the FHIR IG layer’s Process_IgAstCache, whose “valid for this commit?” is the component’s verify and whose AST refresh is its save. The Jekyll cache is last, because it caches the rendering of what the rest produce.
ONLY WHAT THE TARGET NEEDS, ONLY WHAT IS STALE (owner, 2026-11-05: “not all rendering/CI/merge processes need all caches. be optimal in what needs caching” and “… be optimal in which caches need to be updated to perform a specific render”). A component runs only when the plan (cache:plan, the first gateway) marks it needed for this target; a component the target does not read is passed through untouched, neither restored nor refreshed. A needed component that is fresh is RESTORED, never rebuilt. A needed component that is stale, or whose staleness cannot be determined, is REFRESHED, incrementally where its node says so (the changed writers, the changed Lean modules over the restored .oleans, the IG AST delta, the moved layers), never wholesale when a delta is valid. A stale component no target here needs is left for the next target that needs it, or for main’s run. The plan and what actually happened are both reported (cached-step phase report), and the daily report flags a component restored and never read.
EACH COMPONENT, BOTH PHASES. Restore: look up the derived key, verify the entry by its trust class — (a) against a reference derived from THIS tree, so a bad entry is only a miss; (a′) a bundle’s own manifest plus a source rule; (b) a committer’s verdict, honoured then re-verified off the critical path; (c) main-only entries, by exact key — and report hit, warm or miss with why. Save: only after the consumer’s work is green, only from main or into the run’s own ref scope, never from pull_request_target. Each component is a cache node in the knowledge graph (key recipe, derived inputs, producer, consumers, trust class, location, budget), and the cache viewer compares its current key with the key today’s pins imply, so staleness is computed, never claimed.
How it connects
- Called by: Incremental IG build
- Calls: none
- Presented on: no docs page section shows this diagram
- Running instances: none recorded
Lanes — who acts
| lane | role | what it does here |
|---|---|---|
| Build pipeline | build-pipeline | The run that consumes the caches: a CI job, a render, a publish, a preview, or a committer’s local mount. |
| FHIR IG AST cache (the FHIR IG layer) | publication-manager | the FHIR IG layer’s Process_IgAstCache, whose site build and AST refresh sit under the publication manager: the component’s verify is that process’s “valid for this commit?”, and its save is that process’s refresh dispatch. |
Steps
Every one of the 9 step(s) is documented.
| step | lane | skill / sub-process | what it does |
|---|---|---|---|
Layers ref: restore / saveTask_Layers | Build pipeline | cache-first-ci | Component 1, which everything else needs. RESTORE: mount-from-lock replays the lock from refs/cat/layers/<key> (key = sha256 of the lock’s layers), verifying every layer’s tree digest, declaration and asset sha256 against the committed lock — class (a), verified against THIS tree, so a bad entry is only a miss, and a stale refs/cat/layers/main still serves every layer that did not move. SAVE: the committer (layers:publish, run by mount:remote after it changes the lock), with the re-pin train and main as fallbacks. Not wrapped in cached-step: its per-layer verify is finer than one hit. Owner role: the layers-ref session (CI speed 13). cache node: layers. It reports one line in cached-step’s format — cached-step <step>: hit\|warm\|miss (<trust>) — <why>. Key <key>. — to the job summary, which the daily hit-rate report counts. |
Prepared image + node_modulesTask_Image | Build pipeline | cache-first-ci | Component 2a. RESTORE: the prepared CI image ghcr.io/<owner>/<repo>-ci, keyed by .github/ci-image/key.sh (the lock, bun.lock, package.json, the recipe files, the bun version and ImageOS) — computed BEFORE anything is mounted, so it is not cache:key; cache:key --check image asserts the two agree. Each layer’s sha256 is checked as it streams and mount:lock:check re-hashes the result: class (a). SAVE: main or a dispatch only (the one job with packages: write). Owner role: the prepared-image session (CI speed 9). cache node: ci-image. It reports one line in cached-step’s format — cached-step <step>: hit\|warm\|miss (<trust>) — <why>. Key <key>. — to the job summary, which the daily hit-rate report counts. |
bun / pip dependenciesTask_Deps | Build pipeline | cache-first-ci | Component 2b. RESTORE: the package managers’ download caches, keyed by the lockfile digest (bun.lock; the pip requirements file) and the tool version — never by a hand-listed version string. A restored download is re-verified by the package manager against the lockfile’s integrity hashes: class (a). SAVE: main; a PR into its own ref scope. Owner role: the integrator (CI speed 14). cache node: bun-deps, pip-deps. It reports one line in cached-step’s format — cached-step <step>: hit\|warm\|miss (<trust>) — <why>. Key <key>. — to the job summary, which the daily hit-rate report counts. |
Gate results: restore / saveTask_Gates | Build pipeline | cache-first-ci | Component 2c. RESTORE: the result store (build/result-store/) and the CI cone records, by prefix — a WARM start: the cone (ci-cone.ts) then matches each stored entry exactly (fingerprint from cache:key --base, every recorded path state, every replayed git answer) and only an exact match is reported SKIPPED, never passed. A committer’s local gate record is class (b): honoured on the critical path, then re-verified off it. SAVE: main only (class c for CI’s records). Owner roles: the gate-reuse session (CI speed 8) and the committer-side session (CI speed 3). cache nodes: result-store, ci-cone, local-gate-records. It reports one line in cached-step’s format — cached-step <step>: hit\|warm\|miss (<trust>) — <why>. Key <key>. — to the job summary, which the daily hit-rate report counts. |
Generated sets: QA copy, pagesTask_Sets | Build pipeline | cache-first-ci | Component 2d. RESTORE: the QA working copy and the publish-time pages, keyed by bundle-cache.sh digest (the tree and the exact tool versions). A bundle is checked against the manifest it carries AND a source rule (the source run’s head is this head, a parent, or a commit with this tree; or a main-scoped save) — class (a′), because a manifest alone proves a bundle intact, not built from these inputs. Hits across commits wait on the producers being byte-reproducible (the determinism audit). SAVE: the run that built it, recorded; main’s records are read by every branch. Owner role: the generated-sets session (CI speed 10); the preview’s copy, the preview session (CI speed 2). cache nodes: qa-working-copy, publish-pages. It reports one line in cached-step’s format — cached-step <step>: hit\|warm\|miss (<trust>) — <why>. Key <key>. — to the job summary, which the daily hit-rate report counts. |
Lean .oleans: restore / saveTask_Lean | Build pipeline | compiled-artefact-cache | Component 3, after the layers (the Lean packages are mounted content). RESTORE: the compiled .oleans of each declared Lean package, keyed by the package, the toolchain AND the lake manifest (the Mathlib revision) — the manifest is part of the key, so an entry from another revision is a miss. lake build re-checks every restored module’s trace, so a stale module is rebuilt, not trusted: class (a). SAVE: main; a contributor’s warm build may be offered back (compiled-artefact-cache) and is accepted only through that same trace check. Owner role: the integrator (CI speed 14). cache node: lean-oleans. It reports one line in cached-step’s format — cached-step <step>: hit\|warm\|miss (<trust>) — <why>. Key <key>. — to the job summary, which the daily hit-rate report counts. |
Render seed: writer recordsTask_RenderSeed | Build pipeline | incremental-render | Component 4a, the seed of CI’s render (owner, 2026-11-05: CI does not run render; its render is derive:publish). SAVE: main’s writer-records.yml records each publish-time writer under trace (writer-cone): its read set, the state of every path it read, and the outputs it wrote. RESTORE: a run with CAT_WRITER_SKIP=1 (a pull request, staging, the preview) skips every writer whose recorded reads all still match and puts back main’s recorded outputs; a writer whose reads moved runs. The key is the writer’s recorded read set; trust (a′): the outputs are the recording’s own, so their PROVENANCE is checked — they come only from main’s recording run, never from a run a pull request could write. Owner roles: the integrator and the preview session (CI speed 2). cache node: writer-records. It reports one line in cached-step’s format — cached-step <step>: hit\|warm\|miss (<trust>) — <why>. Key <key>. — to the job summary, which the daily hit-rate report counts. |
FHIR IG ASTs: Process_IgAstCacheTask_IgAst | FHIR IG AST cache (the FHIR IG layer) | — | Component 4b, in its own lane: the FHIR IG layer’s IG AST cache, Process_IgAstCache (declared by that layer), integrated, not replaced. It is drawn as a task because this layer may not name a process of a layer above it; the steps are that process’s. RESTORE: read the cached AST from its branch store and judge it — that process’s “valid for this commit?” IS this component’s verify (class a: the AST is judged against this commit’s IG sources and tooling); valid → the site is built from it. SAVE: that process’s own path, not cached-step — a miss dispatches an AST refresh on a Java runner with 10 GB, which rewrites the branch store. The branch store is a cache node (fhir-ast, fhir-harness caches/fhir-ast.cache.json). Owner: CI speed 12, the IG layers’ session. It reports one line in cached-step’s format — cached-step <step>: hit\|warm\|miss (<trust>) — <why>. Key <key>. — to the job summary, which the daily hit-rate report counts. |
Jekyll cache: restore / saveTask_Jekyll | Build pipeline | cache-first-ci | Component 5, last: it caches the rendering of what the components above produce. RESTORE: .jekyll-cache, keyed by the theme, the layouts, includes and plugins, Gemfile.lock and the Ruby version, by exact key only. Jekyll invalidates an entry whose source changed, but a template change is not visible to it, which is why the templates are in the key. SAVE: main only — class (c). Owner role: the preview session (CI speed 2). cache node: jekyll-cache. It reports one line in cached-step’s format — cached-step <step>: hit\|warm\|miss (<trust>) — <why>. Key <key>. — to the job summary, which the daily hit-rate report counts. |
Decisions
Every one of the 1 decision(s) is documented.
| decision | what decides it | branches |
|---|---|---|
cache:plan: anything needed?GW_Enabled | Run bun run cat cache:plan <target>. For each cache node it decides NEEDED (derived: the target’s recorded read set, from the CI cone and the writer cone, touches what the node materializes, plus the needs closure), FRESH or STALE (the node’s key against the key today’s inputs imply; undetermined counts as stale), and so restore, refresh or skip. nothing needed when the plan needs no node, when the target has no recorded read set (it could not be derived: the safe direction is to build), when the consumer does not call this process, cannot reach a store, or is told not to (a forced cold run). Skipping is ALWAYS correct: every component’s miss path is the consumer building what it needs, so a skip costs time and never correctness. | needed → Layers ref: restore / save nothing needed → Skipped: the consumer builds |