# UKO Layer 2 Paradigm Vocabularies

## Overview

Layer 2 of the Unified Knowledge Ontology (UKO) refines the Layer 1
`uko-code:` domain with paradigm-specific specializations for three
programming paradigms:

- **Object-Oriented** (`uko-oo:`) — classes, interfaces, methods, attributes
- **Functional** (`uko-func:`) — pure functions, type classes, monads
- **Procedural** (`uko-proc:`) — procedural functions, globals, headers, structs, macros

Each paradigm defines OWL classes that subclass Layer 1 or Layer 0 concepts,
and extends the parent `uko-code:` DetailLevelMap with paradigm-specific
named levels.

Based on `docs/specification.md` ~lines 42333-42422, 24923-25027.

## Namespace Prefixes

| Prefix | IRI | Layer |
|--------|-----|-------|
| `uko-oo:` | `https://cleveragents.ai/ontology/uko/oo#` | 2 |
| `uko-func:` | `https://cleveragents.ai/ontology/uko/func#` | 2 |
| `uko-proc:` | `https://cleveragents.ai/ontology/uko/proc#` | 2 |

## Object-Oriented Vocabulary (`uko-oo:`)

### Classes

| Class | Superclasses | Description |
|-------|-------------|-------------|
| `uko-oo:Class` | `uko-code:TypeDefinition`, `uko:Container` | An OO class that contains methods and attributes. |
| `uko-oo:Interface` | `uko-code:TypeDefinition`, `uko:Boundary` | An interface or abstract base class. |
| `uko-oo:Method` | `uko-code:Callable` | A method defined within a class. |
| `uko-oo:Attribute` | `uko:Atom` | A class or instance attribute. |

### Properties

| Property | Domain | Range | subPropertyOf |
|----------|--------|-------|---------------|
| `uko-oo:inheritsFrom` | `uko-oo:Class` | `uko-oo:Class` | `uko:dependsOn` |
| `uko-oo:implements` | `uko-oo:Class` | `uko-oo:Interface` | `uko:dependsOn` |

### DetailLevelMap Insertions

The OO map inserts two levels into the `uko-code:` base map:

| Depth | Name | Origin | Content |
|-------|------|--------|---------|
| 3 | `CLASS_HIERARCHY` | **uko-oo:** | Inheritance chains and interface implementations |
| 7 | `VISIBILITY_ANNOTATED` | **uko-oo:** | Public/protected/private modifiers |

The full effective map with reassigned depths is documented in
`docs/specification.md` ~lines 24991-25004.

## Functional Vocabulary (`uko-func:`)

### Classes

| Class | Superclasses | Description |
|-------|-------------|-------------|
| `uko-func:PureFunction` | `uko-code:Callable` | A pure function with no side effects. |
| `uko-func:TypeClass` | `uko-code:TypeDefinition`, `uko:Boundary` | A type class defining a set of operations for types. |
| `uko-func:Monad` | `uko-code:TypeDefinition` | A monadic type encapsulating computation context. |

### DetailLevelMap

Uses the same named levels as `uko-code:` without insertions.

## Procedural Vocabulary (`uko-proc:`)

### Classes

| Class | Superclasses | Description |
|-------|-------------|-------------|
| `uko-proc:ProceduralFunction` | `uko-code:Callable` | A procedural function declaration. |
| `uko-proc:GlobalVariable` | `uko:Atom` | A global variable declaration. |
| `uko-proc:HeaderFile` | `uko:Container` | A header file defining exported declarations. |
| `uko-proc:StructDefinition` | `uko-code:TypeDefinition` | A C-style struct type definition. |
| `uko-proc:Macro` | `uko:Atom` | A preprocessor macro definition. |

### DetailLevelMap

Uses the same named levels as `uko-code:` without insertions.

## DetailLevelMap Inheritance

The inheritance chain resolves named levels by walking up the map hierarchy:

```
Layer 3 (uko-py:) -> Layer 2 (uko-oo:) -> Layer 1 (uko-code:) -> Layer 0 (uko:)
```

When a named level is requested, the system looks up the name in the most
specific map first, then walks up to parent maps until a match is found.
Integer depths are used directly (clamped to `max_depth`).

### Insertion Mechanics

When a child map inserts a new named level (e.g., `CLASS_HIERARCHY` after
`MEMBER_LISTING`), all subsequent levels shift upward by one to maintain
consecutive integer numbering.

## Python API

### `DetailLevelMapBuilder`

```python
from cleveragents.acms.uko.detail_level_maps import (
    CODE_DETAIL_LEVEL_MAP,
    DetailLevelMapBuilder,
)

builder = DetailLevelMapBuilder(CODE_DETAIL_LEVEL_MAP, "uko-oo:")
builder.insert_after("MEMBER_LISTING", "CLASS_HIERARCHY")
builder.insert_after("SIGNATURES_WITH_DOCS", "VISIBILITY_ANNOTATED")
oo_map = builder.build()

assert oo_map.resolve("CLASS_HIERARCHY") == 3
assert oo_map.resolve("FULL_SOURCE") == 11
```

### `VocabularyRegistry`

```python
from cleveragents.acms.uko.vocabularies import (
    get_oo_vocabulary,
    get_func_vocabulary,
    get_proc_vocabulary,
)
from cleveragents.acms.uko.vocabulary_registry import VocabularyRegistry

registry = VocabularyRegistry(
    vocabularies=(
        get_oo_vocabulary(),
        get_func_vocabulary(),
        get_proc_vocabulary(),
    )
)
oo = registry.get_by_prefix("uko-oo:")
assert oo is not None
assert oo.get_class("Class") is not None
```

## Parent-Layer Dependencies

Layer 2 vocabularies reference these Layer 1 URIs via `rdfs:subClassOf`:

- `https://cleveragents.ai/ontology/uko/code#TypeDefinition`
- `https://cleveragents.ai/ontology/uko/code#Callable`

Layer 2 vocabularies also reference these Layer 0 URIs via
`rdfs:subClassOf` or `rdfs:subPropertyOf`:

- `https://cleveragents.ai/ontology/uko#Container` — superclass of `uko-oo:Class`, `uko-proc:HeaderFile`
- `https://cleveragents.ai/ontology/uko#Atom` — superclass of `uko-oo:Attribute`, `uko-proc:GlobalVariable`, `uko-proc:Macro`
- `https://cleveragents.ai/ontology/uko#Boundary` — superclass of `uko-oo:Interface`, `uko-func:TypeClass`
- `https://cleveragents.ai/ontology/uko#dependsOn` — superproperty of `uko-oo:inheritsFrom`, `uko-oo:implements`

All URIs are defined in `docs/ontology/uko.ttl` and will be fully wired
when the Layer 1 Python module (`uko-code:`) is implemented.

## Limitations

- Layer 1 (`uko-code:`) Python module is not yet implemented; the Python
  code works standalone with the `DetailLevelMap` from `crp.py`.
- Turtle files are validated by the `UKOLoader` but not by a full
  OWL reasoner.
- The procedural vocabulary classes are inferred from the spec's rendering
  tables rather than explicit Turtle definitions.