feat(acms): implement UKO Layer 1 Domain Ontologies (uko-code, uko-doc, uko-data, uko-infra) #617

Merged

hamza.khyari merged 2 commits from feature/m6-uko-layer1-domain-ontologies into master

2026-03-06 23:34:13 +00:00

hamza.khyari commented

2026-03-06 15:41:58 +00:00

Member

Summary

Implements issue #574: the four Layer 1 domain-specific OWL/Turtle ontology vocabularies that specialize Layer 0 universal concepts for specific knowledge domains, plus a Python ontology registry, spec-complete DetailLevelMap presets, and full BDD + Robot tests.

Closes #574.

Changes

Ontology — `docs/ontology/uko.ttl`

uko-doc: — 17 classes (Document, Part, Chapter, Section, Subsection, Paragraph, Sentence, CodeBlock, Citation, Figure, Table, Footnote, Annotation, Bookmark, CrossReference, PageBreak, SectionBreak), 5 properties, 4 relationships. All with rdfs:subClassOf from Layer 0.
uko-data: — 13 classes (Schema, Table, Column, View, StoredProcedure, Constraint, Index, ForeignKey, Trigger, Annotation, Bookmark, PartitionBoundary, ShardBoundary), 6 properties, 5 relationships.
uko-infra: — 7 classes (Service, Network, Endpoint, ConfigKey, Volume, FirewallRule, SubnetBoundary), 2 relationships.

Domain Registry — `ontology_registry.py` (~514 lines)

DomainDescriptor dataclass with namespace IRI, prefix, layer, class inventories, superclass mappings, and DetailLevelMap.
Registry API: get_domain(), list_domains(), get_layer1_domains(), build_detail_map_chain().
Turtle validation: validate_turtle(), validate_turtle_file(), TurtleValidationError — no rdflib dependency.
DetailLevelMap data inlined in domain layer for DIP compliance (no application-layer imports).

DetailLevelMap Presets — `depth_breadth_projection.py`

code_detail_map: 10 levels (depths 0–9), spec §41934–41971
docs_detail_map: 11 levels (depths 0–10), spec §42023–42083
database_detail_map: 12 levels (depths 0–11), spec §42167–42230
infra_detail_map: 9 levels (depths 0–8), spec §42297–42331

Tests

features/uko_ontology_registry.feature — 31 BDD scenarios: domain lookup (4 domains), DetailLevelMap completeness (all named levels for all 4 domains), inheritance chain verification, Turtle validation (valid + malformed + empty), Universal View Guarantee, negative/edge cases (unknown domain, empty prefix, boundary depths).
features/steps/uko_ontology_registry_steps.py — Step definitions (~464 lines) with uniquely prefixed patterns to avoid collisions.
robot/uko_ontology_registry.robot + robot/helper_uko_ontology_registry.py — 6 Robot Framework integration smoke tests.
Updated features/depth_breadth_projection.feature: TABLE_LISTING depth 0→1, added SCHEMA_LISTING at depth 0.
Updated features/uko_ontology.feature: Layer 1 node count 8→67.

Ancillary

acms/__init__.py — 8 new exports (DomainDescriptor, TurtleValidationError, 6 functions).
vulture_whitelist.py — 20 new entries for ontology registry public API.
CHANGELOG.md — Added unreleased entry for #574.

Spec Compliance

Per docs/specification.md §41830–42332 (UKO Ontology Hierarchy, Layer 1). All class inventories, property definitions, relationships, and DetailLevelMap presets match the specification exactly.

## Summary Implements issue #574: the four Layer 1 domain-specific OWL/Turtle ontology vocabularies that specialize Layer 0 universal concepts for specific knowledge domains, plus a Python ontology registry, spec-complete DetailLevelMap presets, and full BDD + Robot tests. Closes #574. ## Changes ### Ontology — `docs/ontology/uko.ttl` - **`uko-doc:`** — 17 classes (Document, Part, Chapter, Section, Subsection, Paragraph, Sentence, CodeBlock, Citation, Figure, Table, Footnote, Annotation, Bookmark, CrossReference, PageBreak, SectionBreak), 5 properties, 4 relationships. All with `rdfs:subClassOf` from Layer 0. - **`uko-data:`** — 13 classes (Schema, Table, Column, View, StoredProcedure, Constraint, Index, ForeignKey, Trigger, Annotation, Bookmark, PartitionBoundary, ShardBoundary), 6 properties, 5 relationships. - **`uko-infra:`** — 7 classes (Service, Network, Endpoint, ConfigKey, Volume, FirewallRule, SubnetBoundary), 2 relationships. ### Domain Registry — `ontology_registry.py` (~514 lines) - `DomainDescriptor` dataclass with namespace IRI, prefix, layer, class inventories, superclass mappings, and DetailLevelMap. - Registry API: `get_domain()`, `list_domains()`, `get_layer1_domains()`, `build_detail_map_chain()`. - Turtle validation: `validate_turtle()`, `validate_turtle_file()`, `TurtleValidationError` — no rdflib dependency. - DetailLevelMap data inlined in domain layer for DIP compliance (no application-layer imports). ### DetailLevelMap Presets — `depth_breadth_projection.py` - `code_detail_map`: 10 levels (depths 0–9), spec §41934–41971 - `docs_detail_map`: 11 levels (depths 0–10), spec §42023–42083 - `database_detail_map`: 12 levels (depths 0–11), spec §42167–42230 - `infra_detail_map`: 9 levels (depths 0–8), spec §42297–42331 ### Tests - **`features/uko_ontology_registry.feature`** — 31 BDD scenarios: domain lookup (4 domains), DetailLevelMap completeness (all named levels for all 4 domains), inheritance chain verification, Turtle validation (valid + malformed + empty), Universal View Guarantee, negative/edge cases (unknown domain, empty prefix, boundary depths). - **`features/steps/uko_ontology_registry_steps.py`** — Step definitions (~464 lines) with uniquely prefixed patterns to avoid collisions. - **`robot/uko_ontology_registry.robot`** + **`robot/helper_uko_ontology_registry.py`** — 6 Robot Framework integration smoke tests. - Updated `features/depth_breadth_projection.feature`: `TABLE_LISTING` depth 0→1, added `SCHEMA_LISTING` at depth 0. - Updated `features/uko_ontology.feature`: Layer 1 node count 8→67. ### Ancillary - **`acms/__init__.py`** — 8 new exports (DomainDescriptor, TurtleValidationError, 6 functions). - **`vulture_whitelist.py`** — 20 new entries for ontology registry public API. - **`CHANGELOG.md`** — Added unreleased entry for #574. ## Spec Compliance Per `docs/specification.md` §41830–42332 (UKO Ontology Hierarchy, Layer 1). All class inventories, property definitions, relationships, and DetailLevelMap presets match the specification exactly.

Rows
Columns