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.

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.