Refresh an IG’s AST cache on a runner

Dispatch an IG repository’s ig-ast-refresh.yml, which calls fhir-harness’s reusable .github/workflows/ig-ast-refresh.yml: mount the layers the IG’s index.lock.json pins, restore and judge the cache for ref, and when it is not valid (or force) run the caller’s optional pre-export overlay command and build the IG with the pinned Publisher AST exporter (the AST is recorded against the clean commit’s inputs, the overlay’s changes put back), check the new AST is valid for its commit, and seed cat/fhir-harness/fhir-ast/<package id> with ig-cache seed --push — only from a commit on the default branch with the tip’s inputs. Builds no site, writes no gh-pages, dispatches nothing.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

ig-build-pipeline

The bare FHIR IG pipeline — FSH to SUSHI to the IG Publisher to a pages branch, with no pre-processing and no post-processing. What this layer runs, what it emits, and the list of things it deliberately refuses to know about. Owns the AST cache lifecycle: an IG site is built from the AST on its cache branch, the publish refuses a stale one, and the reusable ig-ast-refresh.yml is the one writer. Owns what an IG reader may read: contentTypes.ig.include in the repository’s index.config.json, and the legacy warning for a repository that declares none. Read before adding anything to fhir-harness, before onboarding, converting or changing the workflows of an IG repository, and before publishing an IG site.

Source: fhir-harness/skills/fhir-ig-base/ig-build-pipeline.md.

Also satisfied by: build-ig-site, fhir-core, ig-artifact-jsonld, ig-index-build, ig-page-render-qa, ig-pages, ig-publisher-i18n, ig-repo-site, ig-site-data, ingest-ig-menu, jsonld-vocabularies, logical-model-schemas, stage-ig-sites, strip-library-binaries, strip-library-content, terminology-index, valueset-schemas.

The skill declares no I/O contract (schemas/skills/ig-build-pipeline/{input,output}.schema.json).

compiled-artefact-cache

The general pattern for caching expensive compiled artefacts (Lean .oleans, FHIR ASTs) across builds. Defines branch-based storage, validity checking, exit code protocol, safety guards, and the restore→build→contribute loop.

Source: cat-harness/skills/process/process-core/compiled-artefact-cache.md.

Also satisfied by: ig-cache.

The skill declares no I/O contract (schemas/skills/compiled-artefact-cache/{input,output}.schema.json).

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
inrepositoryRepoFullNameyesThe IG repository that carries the caller (owner/repo).string · pattern ^[A-Za-z0-9][A-Za-z0-9._-]*\\/[A-Za-z0-9][A-Za-z0-9._-]*$ · A forge repository’s full name, owner/name
inrefBranchWhat to build; default main. Only a commit on the default branch with the tip’s inputs is seeded.string · pattern ^[A-Za-z0-9][A-Za-z0-9._/-]*$ · A git branch name
inforceFlagRebuild even when the cache is valid.boolean · A boolean switch — projects to a bare flag, with no value word
outresultTextThe run’s verdict before (valid, stale, cannot-tell, missing) and whether it seeded; the AST as a run artifact when it did not.string · A short single-line human string. Not admissible as a command-line argument.

Processes and tasks

Steps this Tool can carry out, because each names a skill it satisfies:

processsteplanevia skill
The cache process: restore and save every cache a run can useLean .oleans: restore / saveBuild pipelinecompiled-artefact-cache
An IG site, built from the AST on its cache branchRestore and judge the cached ASTSite build (agent, stage-local)ig-build-pipeline
An IG site, built from the AST on its cache branchBuild and publish the site from the ASTSite build (agent, stage-local)ig-build-pipeline
An IG site, built from the AST on its cache branchDispatch AST refreshPublication manager (owner, or the agent the owner delegates to)ig-build-pipeline
An IG site, built from the AST on its cache branchSeed the cache branchAST refresh (GitHub runner: IG Publisher with the AST exporter)compiled-artefact-cache
Each IG, composed into a host docs site and rendered with just-the-docsBuild each IG’s artefact indexHost docs site build (CI runner)ig-build-pipeline
Each IG, composed into a host docs site and rendered with just-the-docsGenerate each IG instance’s artefact pagesHost docs site build (CI runner)ig-build-pipeline
Each IG, composed into a host docs site and rendered with just-the-docsClone each IG at its recorded commit and stage itHost docs site build (CI runner)ig-build-pipeline

How it is deployed and reached

  • Command line. From the repository root: gh workflow run ig-ast-refresh.yml --repo <owner/repo> --ref main -f ref=main [-f force=true].
  • GitHub Actions. No workflow in this checkout runs its command.

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimegh
networkyes

When a host it reaches is refused:

host / errorremedy
github.comnone: The Tool IS a workflow dispatch on GitHub, and the build it starts runs on a GitHub runner; offline there is no arm. ig-cache restores an AST already seeded.
when to choose it
whenAn IG site publish refused a stale or missing AST, or the IG’s source changed on its default branch. Dispatched by a person, or by an agent the owner named for that run — never by an agent on its own.
limitsNeeds the IG repository to carry the caller and an index.lock.json that mounts fhir-harness. A merge that changes an input during the build leaves the cache unseeded (the run says so). A pre-export command is the caller’s, in its own workflow file, never a dispatch input; a failing one exports nothing. The no-shrink gate refuses a candidate under 90% of the incumbent.
costOne GitHub runner for the Publisher build: about 25 minutes cold for a ~700-resource IG, less with the restored txcache.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/fhir-harness/tools/ig-ast-refresh.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/fhir-harness/tools/ig-ast-refresh.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
  "name": "ig-ast-refresh",
  "title": "Refresh an IG's AST cache on a runner",
  "description": "Dispatch an IG repository's `ig-ast-refresh.yml`, which calls fhir-harness's reusable `.github/workflows/ig-ast-refresh.yml`: mount the layers the IG's index.lock.json pins, restore and judge the cache for `ref`, and when it is not valid (or `force`) run the caller's optional `pre-export` overlay command and build the IG with the pinned Publisher AST exporter (the AST is recorded against the clean commit's inputs, the overlay's changes put back), check the new AST is valid for its commit, and seed `cat/fhir-harness/fhir-ast/<package id>` with `ig-cache seed --push` — only from a commit on the default branch with the tip's inputs. Builds no site, writes no gh-pages, dispatches nothing.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "gh workflow run ig-ast-refresh.yml --repo <owner/repo> --ref main -f ref=main [-f force=true]"
  },
  "io": {
    "inputs": [
      {
        "name": "repository",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoFullName",
        "description": "The IG repository that carries the caller (`owner/repo`).",
        "required": true
      },
      {
        "name": "ref",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Branch",
        "description": "What to build; default `main`. Only a commit on the default branch with the tip's inputs is seeded.",
        "required": false
      },
      {
        "name": "force",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Rebuild even when the cache is valid.",
        "required": false
      }
    ],
    "outputs": [
      {
        "name": "result",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
        "description": "The run's verdict before (`valid`, `stale`, `cannot-tell`, `missing`) and whether it seeded; the AST as a run artifact when it did not."
      }
    ]
  },
  "satisfies": [
    "ig-build-pipeline",
    "compiled-artefact-cache"
  ],
  "requirements": {
    "runtime": [
      "gh"
    ],
    "network": true
  },
  "remedies": [
    {
      "host": "github.com",
      "none": "The Tool IS a workflow dispatch on GitHub, and the build it starts runs on a GitHub runner; offline there is no arm. `ig-cache` restores an AST already seeded."
    }
  ],
  "selection": {
    "when": "An IG site publish refused a stale or missing AST, or the IG's source changed on its default branch. Dispatched by a person, or by an agent the owner named for that run — never by an agent on its own.",
    "limits": "Needs the IG repository to carry the caller and an index.lock.json that mounts fhir-harness. A merge that changes an input during the build leaves the cache unseeded (the run says so). A `pre-export` command is the caller's, in its own workflow file, never a dispatch input; a failing one exports nothing. The no-shrink gate refuses a candidate under 90% of the incumbent.",
    "cost": "One GitHub runner for the Publisher build: about 25 minutes cold for a ~700-resource IG, less with the restored txcache."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev