ADR-A88: Ontology import resolution for consumers

Status: Accepted Date: 2026-09-25 (proposed), 2026-09-25 (accepted) Related: ADR-A86 (ontology semantic versioning), ADR-A77 (repository topology) Unit: applied-ontology-readiness

Context

Every LATTICE layer imports its dependencies by exact owl:versionIRI (ADR-A86). An applied ontology does the same. Neither can load its import closure with standard tooling today:

• The version IRIs under https://www.nebularis.org/neuro-semantic/lattice/ do not dereference to the documents.
• The six catalog-v001.xml files under ontology/ are Protégé by-products. They name pre-reset IRIs (foundation/0.0.7, party/0.0.3), point at absolute paths on one machine from before the ontology/ relocation, and map none of the current version IRIs.
• Nothing checks that an owl:imports target inside ontology/ is declared by some document in the tree. The generated ontology/surface/execution/job-family/ modules still import the retired surface/0.0.1 IRI.

A consumer must therefore write and maintain its own mapping from every LATTICE IRI to a file, and repeat that work after each upgrade.

Decision

1. One generated, repository-relative catalog. ontology/catalog-v001.xml (OASIS XML Catalogs) maps every ontology IRI and every owl:versionIRI declared under ontology/ to its file by a path relative to the catalog. A tool generates it from the documents’ own headers. It is never edited by hand.
2. Directory stubs for editors. Protégé reads the catalog beside the document it opens. Each directory holding an owl:Ontology document gets a generated stub catalog whose only entry is a nextCatalog pointing at the root catalog. The existing hand-made catalogs are replaced by these stubs.
3. A resolution check. A check fails when an owl:imports target inside ontology/ in a LATTICE namespace has no catalog entry, when a catalog entry names a file that does not declare that IRI, or when the committed catalog differs from a fresh generation. External imports (PROV-O, SKOS) are listed explicitly with their published locations.
4. A consumer pattern, documented, not imposed. An applied ontology pins a LATTICE commit (submodule, vendored copy or package, at its choice) and chains its own catalog to LATTICE’s with nextCatalog. The guide states the upgrade procedure: move the pin, enumerate changed version IRIs, cascade owl:imports per the ADR-A86 checklist, re-run the consumer’s own gate. At major version zero every LATTICE bump is treated as potentially breaking.
5. Publication at the IRIs is deferred. Serving documents at their version IRIs is compatible with this decision and remains open. The catalog is required either way for offline and pinned use.

Consequences

• Tools that honour catalogs (Protégé, the OWL API) load any LATTICE document from a checkout with no local configuration. Python tooling uses a small resolver in the same tool, since rdflib has no catalog support.
• Adding or bumping an ontology document requires regenerating the catalog in the same change. The check enforces it.
• The job-family modules must be regenerated before the check can pass.
• Whether ontology IRIs (…/neuro-semantic/<layer>) should move under the …/lattice/ base used by version IRIs is left to the ADR-A86 follow-up. The catalog maps both forms, so the question does not block this decision.
• No new directory is introduced.

Open questions

• Does Protégé’s catalog implementation honour nextCatalog with a relative path in the version this repository targets? The implementing slice verifies this before deleting the existing catalogs. The fallback is full per-directory catalogs, generated by the same tool.