feat(acms): implement UKO Layer 3 Technology Vocabularies (uko-py, uko-ts, uko-rs, uko-java) #576

New issue

Closed

opened 2026-03-04 23:43:10 +00:00 by freemo · 0 comments

freemo commented

2026-03-04 23:43:10 +00:00

Owner

Metadata

Field	Value
Commit Message	`feat(acms): implement UKO Layer 3 Technology Vocabularies (uko-py, uko-ts, uko-rs, uko-java)`
Branch	`feature/m6-uko-layer3-technology-vocabularies`

Summary

Implement Layer 3 technology-specific UKO vocabulary extensions for Python (uko-py:), TypeScript (uko-ts:), Rust (uko-rs:), and Java (uko-java:). These extend Layer 2 paradigm vocabularies (or Layer 1 directly) with language-specific semantic refinements and DetailLevelMap insertions.

Spec Reference

Section: Architecture > ACMS > UKO > Ontology Hierarchy > Layer 3: Technology-Specific Specializations
Lines: ~42423-42438

Current State

No Layer 3 vocabulary files exist. Layers 1 and 2 are also not yet implemented (prerequisites).

Description

Each language extension may insert additional named levels into its parent paradigm's map:

Language	Inserted Levels	Additional Content
Python (`uko-py:`)	`DECORATED_SIGNATURES` (between SIGNATURES_WITH_DOCS and STRUCTURAL_OUTLINE), `TYPE_STUBS` (between KEY_LOGIC and NEAR_COMPLETE), `WITH_TESTS` (beyond FULL_SOURCE)	Decorator chains (`@property`, `@staticmethod`, custom), `.pyi` stub type annotations, associated test cases
TypeScript (`uko-ts:`)	Extends at SIGNATURES level	`export`/`default export` markers, `declare` ambient types, generic type parameters, mapped/conditional types
Rust (`uko-rs:`)	Extends at SIGNATURES level	Visibility modifiers (`pub`, `pub(crate)`), lifetime parameters, trait bounds, `unsafe` markers, `#[derive]` macros, `#[must_use]` annotations
Java (`uko-java:`)	Extends at SIGNATURES level	Package visibility, `final`/`abstract`/`sealed` modifiers, annotation lists, checked exceptions

Key design note: Not every language requires a Layer 3 extension. If a language's semantics are fully captured by Layers 1+2, no Layer 3 extension is needed. The system falls back to the nearest parent layer's DetailLevelMap.

Acceptance Criteria

uko-py: OWL/Turtle file with Python-specific classes and properties (decorators, type stubs, test associations)
uko-ts: OWL/Turtle file with TypeScript-specific extensions (export markers, ambient types, generics)
uko-rs: OWL/Turtle file with Rust-specific extensions (visibility, lifetimes, trait bounds, derive macros)
uko-java: OWL/Turtle file with Java-specific extensions (package visibility, modifiers, annotations, checked exceptions)
DetailLevelMap insertions correctly shift subsequent integer assignments
Full inheritance chain resolution: Layer 3 → Layer 2 → Layer 1 → Layer 0 (e.g., uko-py: → uko-oo: → uko-code: → uko:)
Provenance contract: Every Layer 3 node carries uko:sourceResource, uko:sourcePath, uko:sourceRange, uko:validFrom, uko:isCurrent
Unit tests for the full 4-layer DetailLevelMap resolution chain

Depends on: UKO Layer 1 Domain Ontologies, UKO Layer 2 Paradigm Vocabularies
Parent epic: #367 (Multi-Agent RDF Knowledge Graph)
Used by: ACMS Domain-Specific Analyzers (PythonAnalyzer, TypeScriptAnalyzer, etc.)

Suggested Milestone

v3.5.0

Priority

Low

Suggested Assignee

@hamza.khyari

Subtasks

Code: Implement uko-py: OWL/Turtle ontology with Python-specific classes (decorators, type stubs, test associations) and DetailLevelMap insertions
Code: Implement uko-ts: OWL/Turtle ontology with TypeScript-specific extensions (export markers, ambient types, generics)
Code: Implement uko-rs: OWL/Turtle ontology with Rust-specific extensions (visibility, lifetimes, trait bounds, derive macros)
Code: Implement uko-java: OWL/Turtle ontology with Java-specific extensions (package visibility, modifiers, annotations)
Code: Implement full 4-layer DetailLevelMap inheritance chain resolution with provenance contract enforcement
Docs: Document Layer 3 technology vocabulary hierarchy and language-specific extensions
Behave tests: Add BDD feature file features/acms/uko_layer3_technology_vocabularies.feature covering all 4 language vocabularies and inheritance chain
Robot tests: Add Robot Framework integration test for full 4-layer resolution chain and provenance contract verification
ASV benchmarks: Add ASV benchmark for 4-layer DetailLevelMap resolution performance (benchmarks/bench_uko_layer3.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 3 Technology Vocabularies (uko-py, uko-ts, uko-rs, uko-java)` | | **Branch** | `feature/m6-uko-layer3-technology-vocabularies` | ## Summary Implement Layer 3 technology-specific UKO vocabulary extensions for Python (`uko-py:`), TypeScript (`uko-ts:`), Rust (`uko-rs:`), and Java (`uko-java:`). These extend Layer 2 paradigm vocabularies (or Layer 1 directly) with language-specific semantic refinements and DetailLevelMap insertions. ## Spec Reference **Section**: Architecture > ACMS > UKO > Ontology Hierarchy > Layer 3: Technology-Specific Specializations **Lines**: ~42423-42438 ## Current State No Layer 3 vocabulary files exist. Layers 1 and 2 are also not yet implemented (prerequisites). ## Description Each language extension may insert additional named levels into its parent paradigm's map: | Language | Inserted Levels | Additional Content | |----------|----------------|-------------------| | **Python** (`uko-py:`) | `DECORATED_SIGNATURES` (between SIGNATURES_WITH_DOCS and STRUCTURAL_OUTLINE), `TYPE_STUBS` (between KEY_LOGIC and NEAR_COMPLETE), `WITH_TESTS` (beyond FULL_SOURCE) | Decorator chains (`@property`, `@staticmethod`, custom), `.pyi` stub type annotations, associated test cases | | **TypeScript** (`uko-ts:`) | Extends at SIGNATURES level | `export`/`default export` markers, `declare` ambient types, generic type parameters, mapped/conditional types | | **Rust** (`uko-rs:`) | Extends at SIGNATURES level | Visibility modifiers (`pub`, `pub(crate)`), lifetime parameters, trait bounds, `unsafe` markers, `#[derive]` macros, `#[must_use]` annotations | | **Java** (`uko-java:`) | Extends at SIGNATURES level | Package visibility, `final`/`abstract`/`sealed` modifiers, annotation lists, checked exceptions | **Key design note**: Not every language requires a Layer 3 extension. If a language's semantics are fully captured by Layers 1+2, no Layer 3 extension is needed. The system falls back to the nearest parent layer's DetailLevelMap. ## Acceptance Criteria - [ ] `uko-py:` OWL/Turtle file with Python-specific classes and properties (decorators, type stubs, test associations) - [ ] `uko-ts:` OWL/Turtle file with TypeScript-specific extensions (export markers, ambient types, generics) - [ ] `uko-rs:` OWL/Turtle file with Rust-specific extensions (visibility, lifetimes, trait bounds, derive macros) - [ ] `uko-java:` OWL/Turtle file with Java-specific extensions (package visibility, modifiers, annotations, checked exceptions) - [ ] DetailLevelMap insertions correctly shift subsequent integer assignments - [ ] Full inheritance chain resolution: Layer 3 → Layer 2 → Layer 1 → Layer 0 (e.g., `uko-py:` → `uko-oo:` → `uko-code:` → `uko:`) - [ ] Provenance contract: Every Layer 3 node carries `uko:sourceResource`, `uko:sourcePath`, `uko:sourceRange`, `uko:validFrom`, `uko:isCurrent` - [ ] Unit tests for the full 4-layer DetailLevelMap resolution chain ## Related Issues - Depends on: UKO Layer 1 Domain Ontologies, UKO Layer 2 Paradigm Vocabularies - Parent epic: #367 (Multi-Agent RDF Knowledge Graph) - Used by: ACMS Domain-Specific Analyzers (PythonAnalyzer, TypeScriptAnalyzer, etc.) ## Suggested Milestone v3.5.0 ## Priority Low ## Suggested Assignee @hamza.khyari ## Subtasks - [ ] **Code**: Implement `uko-py:` OWL/Turtle ontology with Python-specific classes (decorators, type stubs, test associations) and DetailLevelMap insertions - [ ] **Code**: Implement `uko-ts:` OWL/Turtle ontology with TypeScript-specific extensions (export markers, ambient types, generics) - [ ] **Code**: Implement `uko-rs:` OWL/Turtle ontology with Rust-specific extensions (visibility, lifetimes, trait bounds, derive macros) - [ ] **Code**: Implement `uko-java:` OWL/Turtle ontology with Java-specific extensions (package visibility, modifiers, annotations) - [ ] **Code**: Implement full 4-layer DetailLevelMap inheritance chain resolution with provenance contract enforcement - [ ] **Docs**: Document Layer 3 technology vocabulary hierarchy and language-specific extensions - [ ] **Behave tests**: Add BDD feature file `features/acms/uko_layer3_technology_vocabularies.feature` covering all 4 language vocabularies and inheritance chain - [ ] **Robot tests**: Add Robot Framework integration test for full 4-layer resolution chain and provenance contract verification - [ ] **ASV benchmarks**: Add ASV benchmark for 4-layer DetailLevelMap resolution performance (`benchmarks/bench_uko_layer3.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.

Rows
Columns