Generated from fhir-harness/processes/content/ig-ast-cache.bpmn by gen-processes-viz.ts — do not edit here. All processes

An IG site, built from the AST on its cache branch

Process_IgAstCache · advisory · 5 step(s)

How an IG repository’s own site is published, and how the AST it is built from is kept current (skill ig-build-pipeline §”The AST cache lifecycle”). Owner, 2026-10-14: “i want AST to be used. it should be in cache branch”, and “that should be in fhir-harness then smart-* all use that”.

THE RULE. An IG site is built from the IG Publisher AST read from the IG repository’s cache branch cat/fhir-harness/fhir-ast/<package id>, never from Publisher HTML. The publish refuses an AST that is not valid for the commit it publishes (ig-cache.sh restore then verify). A later commit that changes no IG input (sushi-config.yaml, ig.ini, input/) does not make the AST stale.

THE REFRESH. The cache is written by ONE thing: fhir-harness’s reusable workflow .github/workflows/ig-ast-refresh.yml, which an IG repository’s Site publish calls as its first job (ast; template templates/ig-repo-site/site-publish.yml). It runs the Publisher through the AST exporter on a GitHub runner (Java, a 10 GB heap, tx.fhir.org), because an agent’s container cannot. It seeds the branch only from a commit on the default branch whose inputs equal the tip’s.

WHAT IT DOES NOT CLAIM. A valid AST is a cache built from these inputs; it is not a release. Every page drawn from it carries the provisional mark (ig-ast-delta).

How it connects

• Called by: no call activity names this process
• Calls: none
• Presented on: no docs page section shows this diagram

Lanes — who acts

lane	role	what it does here
Publication manager (owner, or the agent the owner delegates to)	publication-manager	Wants the IG’s site published, and is the only one who starts a runner: dispatching ig-ast-refresh.yml spends Actions minutes and writes a shared branch, so an agent never dispatches it on its own (feature-staging §”Agent-run repositories”). Accountable for asking for the refresh when the publish refuses a stale AST, rather than for publishing around it.
Site build (agent, stage-local)	build-pipeline	Restores the AST, judges it for the commit being published, and builds and publishes the site from it. Mechanical: it decides nothing a person must own, and it refuses rather than guesses — a stale or cannot-tell AST ends the publish.
AST refresh (GitHub runner: IG Publisher with the AST exporter)	ig-publisher-service	fhir-harness’s ig-ast-refresh.yml, run in the IG repository through its caller. Builds the IG once with the Publisher AST exporter and writes the cache branch. Builds no site, publishes nothing, dispatches nothing.

Steps

Every one of the 5 step(s) is documented.

step	lane	skill / sub-process	what it does
Restore the AST from its cache branch and judge it Task_Restore	Site build (agent, stage-local)	ig-ast-delta ig-build-pipeline	ig-cache.sh restore --ig-root . fetches cat/fhir-harness/fhir-ast/<package id> into output-ast/ (with the Publisher’s txcache/), then ig-cache.sh verify runs ig-ast.ts validity: exit 0 valid, 1 stale-inputs (naming which input), 2 cannot-tell. A restore that finds no branch is a miss, judged as not valid. In an IG repository’s site route this is the first pre step, ig-site:ast (ig-repo-site.ts ast).
Build and publish the site from the AST Task_BuildSite	Site build (agent, stage-local)	ig-render-jekyll ig-build-pipeline	The site route’s steps, provided by the mounted layers and run by stage-local.ts → build-instance-site.ts: the landing layer’s IG API sidecars when it has the step (ig-site:sidecars), the artefact index from the AST and the thin pages with the IG composed at the root (ig-site:compose: ast-to-artifact-index.ts, gen-ig-pages.ts --compiled-data ast-data), the OpenAPI pages when the IG holds them (ig-site:openapi), the AST’s resources served as ast-data/ and the build stamp (ig-site:publisher-pages). Published at the root from the default branch, as a preview otherwise.
Dispatch the IG’s ig-ast-refresh.yml Task_Dispatch	Publication manager (owner, or the agent the owner delegates to)	ig-build-pipeline	Actions → “IG AST refresh (by hand)” → Run workflow on the default branch, inputs ref = the default branch, force = false. The publish refused, so the verdict already says the cache is not valid; force is for a cache that is valid but suspected wrong.
Build the IG with the Publisher AST exporter Task_Export	AST refresh (GitHub runner: IG Publisher with the AST exporter)	ig-publisher-fork	The runner mounts the layers the IG repository’s index.lock.json pins, restores and judges the cache itself, and, when it is not valid, runs the caller’s optional pre-export overlay command, then AstExportCli (Tool ig-ast-export, litlfred/fhir-ig-publisher at the pinned claude/ast-export commit) with -tx. The inputs pre-export changed are put back and the AST is recorded against the clean commit’s input digest (ig-ast.ts source-inputs). The AST just built must itself be valid for the commit, or the run fails.
Seed the cache branch (ig-cache seed –push) Task_Seed	AST refresh (GitHub runner: IG Publisher with the AST exporter)	compiled-artefact-cache	ig-cache.sh seed --ig-root . --push: one commit holding the AST, the Publisher’s expansions and txcache/, its subject recording the package, counts, Publisher version and source commit. Refused when the candidate is under 90% of the incumbent’s resources or edges (the no-shrink gate).

Decisions

Every one of the 2 decision(s) is documented.

decision	what decides it	branches
AST valid for this commit? GW_Valid	Answered by Task_Restore’s verdict. valid takes yes. stale-inputs, cannot-tell and a miss take no: the publish is refused, never drawn from Publisher HTML or from an AST of other inputs. The override (SITE_ACCEPT_STALE_AST=1, read by ig-site:ast) is for a preview only: on the root it still refuses.	yes → Build and publish the site from the AST no — refused: stale, cannot tell, miss → Dispatch the IG’s ig-ast-refresh.yml
On the default branch, with its inputs? GW_Seedable	Yes when the built commit is an ancestor of the default branch’s tip AND sushi-config.yaml, ig.ini and input/ are the same at both. The cache is shared by every build of the IG, so an AST of other inputs never overwrites it.	yes → Seed the cache branch (ig-cache seed –push) no → AST kept as a run artifact; cache unchanged