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

New issue

Closed

opened 2026-03-04 23:42:40 +00:00 by freemo · 0 comments

freemo commented

2026-03-04 23:42:40 +00:00

Owner

Metadata

Field	Value
Commit Message	`feat(acms): implement UKO Layer 1 Domain Ontologies (uko-code, uko-doc, uko-data, uko-infra)`
Branch	`feature/m6-uko-layer1-domain-ontologies`

Summary

Implement the four Layer 1 domain-specific OWL/Turtle ontology vocabularies that specialize the Layer 0 universal concepts for specific knowledge domains: general software (uko-code:), documents (uko-doc:), data schemas (uko-data:), and infrastructure (uko-infra:).

Spec Reference

Section: Architecture > ACMS > Universal Knowledge Ontology (UKO) > Ontology Hierarchy > Layer 1
Lines: ~41830-42332

Current State

Layer 0 (uko:) base classes exist conceptually (referenced in the spec as uko:InformationUnit, uko:Container, uko:Atom, uko:Boundary, uko:Relationship, uko:dependsOn, uko:contains, etc.) but no OWL/Turtle files exist in the codebase.
No Layer 1 vocabulary files exist anywhere in the project.
The domain/models/acms/ directory has Python stubs for BAL backends (TextBackend, VectorBackend, GraphBackend), ScopedBackendView, CRP, and tiers — but no UKO vocabulary definitions.

Description

The specification defines four Layer 1 domains, each with its own namespace prefix, class hierarchy, and DetailLevelMap:

`uko-code:` (General Software)

Classes: Module, Callable, TypeDefinition, Import, Variable
Properties: calls, imports, defines, exportsSymbol
DetailLevelMap: MODULE_LISTING(0), MEMBER_LISTING(2), SIGNATURES(4), STRUCTURAL_OUTLINE(6), FULL_SOURCE(9)

`uko-doc:` (Documents)

Classes: Document, Section, Paragraph, Citation, Figure, CodeBlock
Properties: cites, references, illustrates
DetailLevelMap: TITLE_ONLY(0), HEADINGS(2), FULL_TOC(3), SECTION_SUMMARIES(4), FULL_TEXT(9)

`uko-data:` (Data Schemas)

Classes: Schema, Table, Column, Constraint, Index, View, StoredProcedure
Properties: foreignKeyTo, partOf, constrainedBy
DetailLevelMap: TABLE_LISTING(0), TYPED_COLUMNS(3), WITH_CONSTRAINTS(5), FULL_DDL(9)

`uko-infra:` (Infrastructure)

Classes: Service, Endpoint, ConfigBlock, ConfigKey, Volume, Network
Properties: connectsTo, exposesEndpoint, configuredBy
DetailLevelMap: SERVICE_LISTING(0), ENDPOINTS(3), FULL_CONFIG(9)

Each domain must:

Define OWL/Turtle files with proper rdfs:subClassOf from Layer 0 classes
Register a DetailLevelMap that maps named levels to integer depths
Be loadable by the graph backend for SPARQL queries
Support the Universal View Guarantee (any Layer 0 query works across all domains)

Acceptance Criteria

Layer 0 (uko:) base ontology defined in OWL/Turtle with: InformationUnit, Container, Atom, Boundary, Relationship, dependsOn, contains, sourceResource, sourcePath, sourceRange, validFrom, validUntil, isCurrent, isRevisionOf, detailDepth
uko-code: ontology file with all classes, properties, and DetailLevelMap
uko-doc: ontology file with all classes, properties, and DetailLevelMap
uko-data: ontology file with all classes, properties, and DetailLevelMap
uko-infra: ontology file with all classes, properties, and DetailLevelMap
Python DetailLevelMap model with inheritance chain resolution (Layer 3 → 2 → 1 → 0)
All ontologies validate with an OWL reasoner or at minimum pass Turtle syntax validation
Unit tests verifying DetailLevelMap resolution across layers
Integration test loading all ontologies into the graph backend and running a Layer 0 universal query

Parent epic: #367 (Multi-Agent RDF Knowledge Graph)
Blocked by: #396 (ACMS Context Pipeline) for integration
Prerequisite for: UKO Layer 2 (uko-oo, uko-func, uko-proc), UKO Layer 3 (uko-py, uko-ts, uko-rs, uko-java)

Suggested Milestone

v3.5.0

Priority

Medium

Suggested Assignee

@hamza.khyari — RDF/UKO/ACMS pipeline specialist

Subtasks

Code: Define Layer 0 (uko:) base ontology in OWL/Turtle with all universal classes and properties
Code: Implement uko-code:, uko-doc:, uko-data:, uko-infra: ontology files with classes, properties, and DetailLevelMaps
Code: Implement Python DetailLevelMap model with inheritance chain resolution (Layer 3 → 2 → 1 → 0)
Code: Integrate ontology loading into the graph backend for SPARQL queries; ensure Universal View Guarantee
Docs: Document the UKO Layer 0 + Layer 1 ontology hierarchy and DetailLevelMap system
Behave tests: Add BDD feature file features/acms/uko_layer1_domain_ontologies.feature covering ontology loading and detail level resolution
Robot tests: Add Robot Framework integration test loading all ontologies into graph backend and running Layer 0 universal query
ASV benchmarks: Add ASV benchmark for ontology loading and SPARQL query performance (benchmarks/bench_uko_ontology.py)
Quality: coverage ≥97%: Verify via nox -s coverage_report
Quality: nox full suite: Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata | Field | Value | |-------|-------| | **Commit Message** | `feat(acms): implement UKO Layer 1 Domain Ontologies (uko-code, uko-doc, uko-data, uko-infra)` | | **Branch** | `feature/m6-uko-layer1-domain-ontologies` | ## Summary Implement the four Layer 1 domain-specific OWL/Turtle ontology vocabularies that specialize the Layer 0 universal concepts for specific knowledge domains: general software (`uko-code:`), documents (`uko-doc:`), data schemas (`uko-data:`), and infrastructure (`uko-infra:`). ## Spec Reference **Section**: Architecture > ACMS > Universal Knowledge Ontology (UKO) > Ontology Hierarchy > Layer 1 **Lines**: ~41830-42332 ## Current State - **Layer 0** (`uko:`) base classes exist conceptually (referenced in the spec as `uko:InformationUnit`, `uko:Container`, `uko:Atom`, `uko:Boundary`, `uko:Relationship`, `uko:dependsOn`, `uko:contains`, etc.) but no OWL/Turtle files exist in the codebase. - No Layer 1 vocabulary files exist anywhere in the project. - The `domain/models/acms/` directory has Python stubs for BAL backends (`TextBackend`, `VectorBackend`, `GraphBackend`), `ScopedBackendView`, CRP, and tiers — but no UKO vocabulary definitions. ## Description The specification defines four Layer 1 domains, each with its own namespace prefix, class hierarchy, and `DetailLevelMap`: ### `uko-code:` (General Software) - **Classes**: `Module`, `Callable`, `TypeDefinition`, `Import`, `Variable` - **Properties**: `calls`, `imports`, `defines`, `exportsSymbol` - **DetailLevelMap**: MODULE_LISTING(0), MEMBER_LISTING(2), SIGNATURES(4), STRUCTURAL_OUTLINE(6), FULL_SOURCE(9) ### `uko-doc:` (Documents) - **Classes**: `Document`, `Section`, `Paragraph`, `Citation`, `Figure`, `CodeBlock` - **Properties**: `cites`, `references`, `illustrates` - **DetailLevelMap**: TITLE_ONLY(0), HEADINGS(2), FULL_TOC(3), SECTION_SUMMARIES(4), FULL_TEXT(9) ### `uko-data:` (Data Schemas) - **Classes**: `Schema`, `Table`, `Column`, `Constraint`, `Index`, `View`, `StoredProcedure` - **Properties**: `foreignKeyTo`, `partOf`, `constrainedBy` - **DetailLevelMap**: TABLE_LISTING(0), TYPED_COLUMNS(3), WITH_CONSTRAINTS(5), FULL_DDL(9) ### `uko-infra:` (Infrastructure) - **Classes**: `Service`, `Endpoint`, `ConfigBlock`, `ConfigKey`, `Volume`, `Network` - **Properties**: `connectsTo`, `exposesEndpoint`, `configuredBy` - **DetailLevelMap**: SERVICE_LISTING(0), ENDPOINTS(3), FULL_CONFIG(9) Each domain must: 1. Define OWL/Turtle files with proper `rdfs:subClassOf` from Layer 0 classes 2. Register a `DetailLevelMap` that maps named levels to integer depths 3. Be loadable by the graph backend for SPARQL queries 4. Support the Universal View Guarantee (any Layer 0 query works across all domains) ## Acceptance Criteria - [ ] Layer 0 (`uko:`) base ontology defined in OWL/Turtle with: `InformationUnit`, `Container`, `Atom`, `Boundary`, `Relationship`, `dependsOn`, `contains`, `sourceResource`, `sourcePath`, `sourceRange`, `validFrom`, `validUntil`, `isCurrent`, `isRevisionOf`, `detailDepth` - [ ] `uko-code:` ontology file with all classes, properties, and DetailLevelMap - [ ] `uko-doc:` ontology file with all classes, properties, and DetailLevelMap - [ ] `uko-data:` ontology file with all classes, properties, and DetailLevelMap - [ ] `uko-infra:` ontology file with all classes, properties, and DetailLevelMap - [ ] Python `DetailLevelMap` model with inheritance chain resolution (Layer 3 → 2 → 1 → 0) - [ ] All ontologies validate with an OWL reasoner or at minimum pass Turtle syntax validation - [ ] Unit tests verifying DetailLevelMap resolution across layers - [ ] Integration test loading all ontologies into the graph backend and running a Layer 0 universal query ## Related Issues - Parent epic: #367 (Multi-Agent RDF Knowledge Graph) - Blocked by: #396 (ACMS Context Pipeline) for integration - Prerequisite for: UKO Layer 2 (uko-oo, uko-func, uko-proc), UKO Layer 3 (uko-py, uko-ts, uko-rs, uko-java) ## Suggested Milestone v3.5.0 ## Priority Medium ## Suggested Assignee @hamza.khyari — RDF/UKO/ACMS pipeline specialist ## Subtasks - [ ] **Code**: Define Layer 0 (`uko:`) base ontology in OWL/Turtle with all universal classes and properties - [ ] **Code**: Implement `uko-code:`, `uko-doc:`, `uko-data:`, `uko-infra:` ontology files with classes, properties, and DetailLevelMaps - [ ] **Code**: Implement Python `DetailLevelMap` model with inheritance chain resolution (Layer 3 → 2 → 1 → 0) - [ ] **Code**: Integrate ontology loading into the graph backend for SPARQL queries; ensure Universal View Guarantee - [ ] **Docs**: Document the UKO Layer 0 + Layer 1 ontology hierarchy and DetailLevelMap system - [ ] **Behave tests**: Add BDD feature file `features/acms/uko_layer1_domain_ontologies.feature` covering ontology loading and detail level resolution - [ ] **Robot tests**: Add Robot Framework integration test loading all ontologies into graph backend and running Layer 0 universal query - [ ] **ASV benchmarks**: Add ASV benchmark for ontology loading and SPARQL query performance (`benchmarks/bench_uko_ontology.py`) - [ ] **Quality: coverage ≥97%**: Verify via `nox -s coverage_report` - [ ] **Quality: nox full suite**: Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.