# UKO Layer 3 Technology Vocabularies

## Overview

Layer 3 of the Unified Knowledge Ontology (UKO) extends Layer 2 paradigm
vocabularies (or Layer 1 directly) with technology-specific semantic
refinements for four programming languages:

- **Python** (`uko-py:`) -- decorators, `.pyi` type stubs, test associations
- **TypeScript** (`uko-ts:`) -- export markers, ambient types, generics, mapped/conditional types
- **Rust** (`uko-rs:`) -- visibility, lifetimes, trait bounds, derive macros, unsafe markers
- **Java** (`uko-java:`) -- package visibility, modifiers, annotations, checked exceptions

Each vocabulary defines OWL classes, properties, Layer 2 dependencies, and
optional DetailLevelMap insertions per `docs/specification.md` ~lines 44405-44420.

## Namespace Prefixes

| Prefix | IRI | Layer |
|--------|-----|-------|
| `uko-py:` | `https://cleveragents.ai/ontology/uko/py#` | 3 |
| `uko-ts:` | `https://cleveragents.ai/ontology/uko/ts#` | 3 |
| `uko-rs:` | `https://cleveragents.ai/ontology/uko/rs#` | 3 |
| `uko-java:` | `https://cleveragents.ai/ontology/uko/java#` | 3 |

## Python Vocabulary (`uko-py:`)

### Classes

| Class | Superclass | Description |
|-------|-----------|-------------|
| `uko-py:PythonModule` | `uko-code:Module` | A Python module (`.py` file). |
| `uko-py:PythonClass` | `uko-oo:Class` | A Python class definition. |
| `uko-py:PythonFunction` | `uko-oo:Method` | A Python function or method. |
| `uko-py:PythonDecorator` | `uko-code:TypeDefinition` | A decorator chain entry. |
| `uko-py:PythonTypeStub` | `uko-code:TypeDefinition` | `.pyi` stub type annotation. |

### Properties

| Property | Domain | Range | Type |
|----------|--------|-------|------|
| `uko-py:hasDecorator` | PythonFunction, PythonClass | PythonDecorator | ObjectProperty |
| `uko-py:hasTypeStub` | PythonModule, PythonClass, PythonFunction | PythonTypeStub | ObjectProperty |
| `uko-py:hasTest` | PythonFunction, PythonClass | PythonFunction | ObjectProperty |
| `uko-py:decoratorName` | PythonDecorator | `xsd:string` | DatatypeProperty |
| `uko-py:stubAnnotation` | PythonTypeStub | `xsd:string` | DatatypeProperty |

### DetailLevelMap Insertions

Python inserts 3 levels into the OO parent map, producing a 15-level effective map:

| Depth | Name | Description |
|-------|------|-------------|
| 7 | `DECORATED_SIGNATURES` | Decorator chains (`@property`, `@staticmethod`, custom). |
| 11 | `TYPE_STUBS` | Type annotations from `.pyi` stub files. |
| 14 | `WITH_TESTS` | Full source + associated test cases. |

## TypeScript Vocabulary (`uko-ts:`)

### Classes

| Class | Superclass | Description |
|-------|-----------|-------------|
| `uko-ts:TypeScriptModule` | `uko-code:Module` | A TypeScript module (`.ts`/`.tsx`). |
| `uko-ts:TypeScriptClass` | `uko-oo:Class` | A TypeScript class. |
| `uko-ts:TypeScriptInterface` | `uko-oo:Interface` | A TypeScript interface (generics, mapped/conditional). |
| `uko-ts:TypeScriptFunction` | `uko-oo:Method` | A TypeScript function or method. |

### Properties

| Property | Domain | Range | Type |
|----------|--------|-------|------|
| `uko-ts:exportKind` | TypeScriptClass, TypeScriptInterface, TypeScriptFunction, TypeScriptModule | `xsd:string` | DatatypeProperty |
| `uko-ts:isAmbient` | TypeScriptClass, TypeScriptInterface, TypeScriptFunction | `xsd:boolean` | DatatypeProperty |
| `uko-ts:genericParameters` | TypeScriptClass, TypeScriptInterface, TypeScriptFunction | `xsd:string` | DatatypeProperty |
| `uko-ts:isMappedType` | TypeScriptInterface | `xsd:boolean` | DatatypeProperty |
| `uko-ts:isConditionalType` | TypeScriptInterface | `xsd:boolean` | DatatypeProperty |
| `uko-ts:implementsInterface` | TypeScriptClass | TypeScriptInterface | ObjectProperty |

### DetailLevelMap Insertions

TypeScript extends at the SIGNATURES level with no new depth insertions (12-level identity map).

## Rust Vocabulary (`uko-rs:`)

### Classes

| Class | Superclass | Description |
|-------|-----------|-------------|
| `uko-rs:RustStruct` | `uko-oo:Class` | A Rust struct definition. |
| `uko-rs:RustTrait` | `uko-oo:Interface` | A Rust trait definition. |
| `uko-rs:RustImpl` | `uko-code:TypeDefinition` | A Rust impl block. |
| `uko-rs:RustFunction` | `uko-oo:Method` | A Rust function or method. |
| `uko-rs:RustDeriveAttribute` | `uko-code:TypeDefinition` | A `#[derive(...)]` macro attribute. |

### Properties

| Property | Domain | Range | Type |
|----------|--------|-------|------|
| `uko-rs:visibility` | RustStruct, RustTrait, RustFunction | `xsd:string` | DatatypeProperty |
| `uko-rs:lifetimeParameters` | RustStruct, RustImpl, RustFunction, RustTrait | `xsd:string` | DatatypeProperty |
| `uko-rs:traitBounds` | RustStruct, RustFunction, RustImpl | `xsd:string` | DatatypeProperty |
| `uko-rs:isUnsafe` | RustFunction, RustImpl, RustTrait | `xsd:boolean` | DatatypeProperty |
| `uko-rs:deriveTraits` | RustDeriveAttribute | `xsd:string` | DatatypeProperty |
| `uko-rs:mustUse` | RustStruct, RustFunction | `xsd:boolean` | DatatypeProperty |
| `uko-rs:hasDerive` | RustStruct | RustDeriveAttribute | ObjectProperty |
| `uko-rs:implementsTrait` | RustImpl | RustTrait | ObjectProperty |

### DetailLevelMap Insertions

Rust extends at the SIGNATURES level with no new depth insertions (12-level identity map).

## Java Vocabulary (`uko-java:`)

### Classes

| Class | Superclass | Description |
|-------|-----------|-------------|
| `uko-java:JavaClass` | `uko-oo:Class` | A Java class definition. |
| `uko-java:JavaInterface` | `uko-oo:Interface` | A Java interface. |
| `uko-java:JavaMethod` | `uko-oo:Method` | A Java method. |
| `uko-java:JavaAnnotation` | `uko-code:TypeDefinition` | A Java annotation entry. |
| `uko-java:JavaCheckedException` | `uko-code:TypeDefinition` | A checked exception declaration. |

### Properties

| Property | Domain | Range | Type |
|----------|--------|-------|------|
| `uko-java:packageVisibility` | JavaClass, JavaInterface, JavaMethod | `xsd:string` | DatatypeProperty |
| `uko-java:isFinal` | JavaClass, JavaMethod | `xsd:boolean` | DatatypeProperty |
| `uko-java:isAbstract` | JavaClass, JavaMethod | `xsd:boolean` | DatatypeProperty |
| `uko-java:isSealed` | JavaClass, JavaInterface | `xsd:boolean` | DatatypeProperty |
| `uko-java:hasAnnotation` | JavaClass, JavaInterface, JavaMethod | JavaAnnotation | ObjectProperty |
| `uko-java:annotationName` | JavaAnnotation | `xsd:string` | DatatypeProperty |
| `uko-java:throwsException` | JavaMethod | JavaCheckedException | ObjectProperty |
| `uko-java:exceptionClass` | JavaCheckedException | `xsd:string` | DatatypeProperty |

### DetailLevelMap Insertions

Java extends at the SIGNATURES level with no new depth insertions (12-level identity map).

## Shared Base Types

All Layer 3 vocabularies use shared types from `vocabulary.py`:

| Type | Description |
|------|-------------|
| `ProvenanceInfo` | Frozen Pydantic model with 2 required fields (`source_resource`, `source_path`) and 3 defaulted fields (`source_range`, `valid_from`, `is_current`). |
| `UKOClass` | Frozen OWL class definition (`uri`, `label`, `comment`, `subclass_of`, `provenance`). |
| `UKOProperty` | Frozen OWL property definition (`uri`, `label`, `comment`, `domain`, `range_uri`, `is_object_property`, `provenance`). |
| `Layer2Dependency` | Declared dependency on a Layer 1/2 URI (`uri`, `layer`, `prefix`, `description`). |
| `UKOVocabulary` | Container aggregating classes, properties, deps, inserted levels, and optional `provenance`. |

## Utility Functions

| Function | Description |
|----------|-------------|
| `build_detail_level_map(parent_levels, insertions)` | Merge parent + child insertions with consecutive integer re-numbering. |
| `resolve_detail_level(name, levels, parent_levels=None)` | Look up a named level in `levels`, falling back to `parent_levels`. |

## Source Files

| File | Description |
|------|-------------|
| `src/cleveragents/acms/uko/vocabulary.py` | Shared base types and utility functions. |
| `src/cleveragents/acms/uko/layer3_py.py` | Python vocabulary definitions. |
| `src/cleveragents/acms/uko/layer3_ts.py` | TypeScript vocabulary definitions. |
| `src/cleveragents/acms/uko/layer3_rs.py` | Rust vocabulary definitions. |
| `src/cleveragents/acms/uko/layer3_java.py` | Java vocabulary definitions. |
| `docs/ontology/uko-py.ttl` | Python OWL/Turtle ontology. |
| `docs/ontology/uko-ts.ttl` | TypeScript OWL/Turtle ontology. |
| `docs/ontology/uko-rs.ttl` | Rust OWL/Turtle ontology. |
| `docs/ontology/uko-java.ttl` | Java OWL/Turtle ontology. |