mif-docs: Hydrate Schema & Ontology Caches

1. Overview

This runbook refreshes the two cached inputs the mif-docs plugin validates against: the canonical MIF JSON Schema (pulled from mif-spec.dev/schema) and the mif-docs ontology (pulled from the sibling modeled-information-format/ontologies repo). Both are caches, never the authority — the plugin hydrates them, records the resolved version, and falls back to the last hydrated copy when offline.

It covers a routine re-hydrate and the validation that proves it took. It does not re-litigate why the ontology lives in a separate repo — that is the decision record adr-0002-ontologies-separate-repo. Use this when the schema or ontology has moved and your local cache is behind.

2. Prerequisites & Access

Confirm these before you start.

Local checkout of the mif-docs-plugin repo with npm ci already run.
Network reachability to https://mif-spec.dev/schema (for the schema) — see section 6 for offline behaviour.
A sibling checkout of modeled-information-format/ontologies at ../ontologies relative to the plugin repo (the path hydrate-ontology reads from).

3. When to re-hydrate

Re-hydrate when any of these holds — otherwise the cache is fine and you should not churn it:

A schema version bump on mif-spec.dev/schema (the canonical schema moved to a new version).
An ontology version bump in the ontologies repo.
mif-validate emits a schema-resolution warning (it fell back to a stale or missing cache).
You are about to cut a release — vendor a fresh copy into the artifact rather than shipping a stale cache (see the release runbook).

4. Hydrate the schema

Fetch the canonical schema into the local cache and record the resolved version.

npm run hydrate-schema

Expected result: the schema is written under schema/.cache/<version>/ and the resolved version is recorded in schema/VENDOR.lock. Confirm the lock advanced:

git diff -- schema/VENDOR.lock

A changed VENDOR.lock (new version / resolved source) confirms the hydrate took. If VENDOR.lock is unchanged, you were already current — that is fine.

5. Hydrate the ontology

Pull the mif-docs ontology from the sibling ../ontologies repo into the local ontology cache.

npm run hydrate-ontology

Expected result: the ontology is refreshed from ../ontologies. If the command errors that the sibling path is missing, clone or update modeled-information-format/ontologies at ../ontologies and re-run — this is the most common failure, and it is a path problem, not a schema problem.

6. Offline behaviour (read vs release)

Hydration is fail-safe for reads: if mif-spec.dev/schema is unreachable, hydrate-schema (and any validation that triggers it) falls back to the last hydrated copy and emits a warning rather than failing. You can keep validating docs offline against the cached schema.

This is only safe for read/validate. Before a release, you must re-hydrate online so the artifact vendors a current schema — a release built on a stale fallback cache may attest the wrong schema version. If you see the fallback warning during release prep, stop and restore network before continuing.

This fallback works because a failed hydrate-schema never rewrites schema/VENDOR.lock — it stays pointed at whatever version was last successfully hydrated, whose cache is still on disk. mif-validate itself never triggers a hydrate or warns; it just reads whatever VENDOR.lock already points to. That means a plugin instance that has never been hydrated at all (a fresh install, before npm run hydrate-schema has ever run on this machine) has no last-known-good copy to fall back to — there is nothing to be stale relative to. mif-validate reports that case as a distinct, non-fallback error (exit 3) telling you to hydrate for the first time, rather than a schema-resolution warning.

7. Verification

Prove the refreshed ontology is internally consistent and the caches resolve.

npm run validate-ontology

Expected result: validate-ontology exits 0 — the ontology YAML conforms and the namespaces/subtypes are intact. As an end-to-end check, run mif-validate on any shipped exemplar and confirm there is no schema-resolution warning:

node scripts/mif-validate.mjs skills/sre-runbook/templates/good.md --level 3

Expected result: RESULT: VALID with schema: <new-version> and no fallback warning, confirming docs now validate against the freshly hydrated schema.

8. Detection & symptoms

Stale VENDOR.lock. git diff schema/VENDOR.lock shows no change after a known upstream bump → the hydrate did not reach the new version. Check network to mif-spec.dev/schema; you are likely on the offline fallback (section 6).
Schema-resolution warning from mif-validate. The cache is missing or behind → run section 4, then re-verify (section 7).
Validation drift — a doc that passed yesterday now fails (or vice versa) with no edit to the doc → the resolved schema/ontology version changed under you. Re-hydrate both caches, re-run validate-ontology, and re-validate the affected docs so the verdict is reproducible against a known version.
hydrate-ontology cannot find the source → the ../ontologies sibling checkout is missing or on the wrong branch; fix the path and re-run.