UAT: UKO Layer 1 domain vocabularies (uko-doc:, uko-data:, uko-infra:) absent from acms/uko module public API #2945

Open
opened 2026-04-05 02:54:17 +00:00 by freemo · 1 comment
Owner

Metadata

  • Branch: feat/acms-uko-layer1-domain-vocabularies
  • Commit Message: feat(acms): add Layer 1 domain vocabularies (uko-doc, uko-data, uko-infra) to acms/uko module
  • Milestone: v3.4.0
  • Parent Epic: #933

Background and context

The src/cleveragents/acms/uko/ module is the authoritative domain model layer for the Universal Knowledge Ontology (UKO). Per docs/specification.md (line 43971), Layer 1 specialises for domain-specific concepts across four domains: general software (uko-code:), documents (uko-doc:), data schemas (uko-data:), and infrastructure (uko-infra:). Each domain must register a DetailLevelMap that assigns named labels to specific integer depths.

Currently only uko-code: (Layer 1) is present in the module. The three remaining Layer 1 domain vocabularies — uko-doc:, uko-data:, and uko-infra: — are entirely absent from the acms/uko public API. Their DetailLevelMap definitions have leaked into application-layer services (depth_breadth_projection.py, acms_skeleton_compressor.py), creating an architectural inconsistency where domain model types are defined outside the domain model layer.

Current behavior (for bugs)

  • src/cleveragents/acms/uko/__init__.py exports only Layer 2 (uko-oo:, uko-func:, uko-proc:) and Layer 3 (language-specific) vocabulary types, plus the single Layer 1 uko-code: map.
  • src/cleveragents/acms/uko/detail_level_maps.py defines CODE_DETAIL_LEVEL_MAP but not DOC_DETAIL_LEVEL_MAP, DATA_DETAIL_LEVEL_MAP, or INFRA_DETAIL_LEVEL_MAP.
  • src/cleveragents/acms/uko/vocabularies.py contains only Layer 2 paradigm vocabulary types.
  • src/cleveragents/acms/uko/vocabulary_registry.py only handles ParadigmVocabulary (Layer 2).
  • The uko-doc:, uko-data:, and uko-infra: DetailLevelMap definitions exist only inside src/cleveragents/application/services/depth_breadth_projection.py and src/cleveragents/application/services/acms_skeleton_compressor.py.

Expected behavior

src/cleveragents/acms/uko/ exports complete Layer 1 domain vocabulary types for all four domains (uko-code:, uko-doc:, uko-data:, uko-infra:), including:

  • Dedicated module files (layer1_doc.py, layer1_data.py, layer1_infra.py) containing OWL class/property definitions per the spec (lines 44091–44400+).
  • DOC_DETAIL_LEVEL_MAP, DATA_DETAIL_LEVEL_MAP, and INFRA_DETAIL_LEVEL_MAP defined in detail_level_maps.py and exported from __init__.py.
  • The vocabulary_registry.py updated to handle Layer 1 domain vocabularies alongside Layer 2 paradigm vocabularies.
  • Application-layer services refactored to import these maps from acms/uko rather than defining them locally.

Spec-defined ontologies that must be implemented (lines 44091–44400+):

Namespace Classes
uko-doc: Document, Part, Chapter, Section, Subsection, Paragraph, CodeBlock, Figure, Table, BlockQuote, ListBlock, Footnote, Citation, Comment, TableOfContents, Index, Glossary
uko-data: Database, Schema, Table, View, Column, StoredProcedure, Trigger, Migration, Constraint, Index, ForeignKey
uko-infra: Service, Endpoint, Config, Port, EnvironmentVariable, DeploymentUnit

Acceptance criteria

  • src/cleveragents/acms/uko/layer1_doc.py exists and defines all uko-doc: OWL classes and properties per the spec.
  • src/cleveragents/acms/uko/layer1_data.py exists and defines all uko-data: OWL classes and properties per the spec.
  • src/cleveragents/acms/uko/layer1_infra.py exists and defines all uko-infra: OWL classes and properties per the spec.
  • DOC_DETAIL_LEVEL_MAP, DATA_DETAIL_LEVEL_MAP, INFRA_DETAIL_LEVEL_MAP are defined in detail_level_maps.py and exported from acms/uko/__init__.py.
  • vocabulary_registry.py registers all four Layer 1 domain vocabularies.
  • Application services (depth_breadth_projection.py, acms_skeleton_compressor.py) import Layer 1 maps from acms/uko instead of defining them locally.
  • All new types are statically typed and pass nox -e typecheck.
  • All nox stages pass.
  • Coverage ≥ 97%.

Supporting information

Steps to reproduce:

  1. Read src/cleveragents/acms/uko/__init__.py — note only Layer 2/3 types are exported.
  2. Read src/cleveragents/acms/uko/detail_level_maps.py — only uko-code:, uko-oo:, uko-func:, uko-proc: maps present.
  3. Check spec at docs/specification.md lines 44135–44400 for the complete uko-doc:, uko-data:, uko-infra: ontology definitions.
  4. Note that uko-doc:, uko-data:, uko-infra: DetailLevelMaps are only accessible via src/cleveragents/application/services/depth_breadth_projection.py.

Spec reference: docs/specification.md line 43971:

Layer 1 specializes for domain-specific concepts: general software (uko-code: — modules, callables, types), documents (uko-doc: — sections, paragraphs, citations), data schemas (uko-data: — tables, columns, constraints), and infrastructure (uko-infra: — services, endpoints, config). Each domain registers a DetailLevelMap that assigns named labels to specific integer depths.

Related: Parent Epic #933 (A2A Protocol Compliance / ACMS v1).

Subtasks

  • Implement src/cleveragents/acms/uko/layer1_doc.pyuko-doc: OWL vocabulary (all classes/properties per spec lines 44091–44200)
  • Implement src/cleveragents/acms/uko/layer1_data.pyuko-data: OWL vocabulary (all classes/properties per spec lines 44201–44300)
  • Implement src/cleveragents/acms/uko/layer1_infra.pyuko-infra: OWL vocabulary (all classes/properties per spec lines 44301–44400)
  • Add DOC_DETAIL_LEVEL_MAP, DATA_DETAIL_LEVEL_MAP, INFRA_DETAIL_LEVEL_MAP to detail_level_maps.py
  • Update vocabulary_registry.py to register all four Layer 1 domain vocabularies
  • Update acms/uko/__init__.py to export all new Layer 1 types and maps
  • Refactor depth_breadth_projection.py to import Layer 1 maps from acms/uko
  • Refactor acms_skeleton_compressor.py to import Layer 1 maps from acms/uko
  • Tests (Behave): Add scenarios for all three new Layer 1 vocabulary modules
  • Tests (Behave): Add scenarios for updated vocabulary_registry.py Layer 1 registration
  • Tests (Robot): Add integration test for Layer 1 domain vocabulary round-trip via ACMS
  • Verify coverage ≥ 97% via nox -s coverage_report
  • 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.
  • All nox stages pass.
  • Coverage ≥ 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `feat/acms-uko-layer1-domain-vocabularies` - **Commit Message**: `feat(acms): add Layer 1 domain vocabularies (uko-doc, uko-data, uko-infra) to acms/uko module` - **Milestone**: v3.4.0 - **Parent Epic**: #933 ## Background and context The `src/cleveragents/acms/uko/` module is the authoritative domain model layer for the Universal Knowledge Ontology (UKO). Per `docs/specification.md` (line 43971), Layer 1 specialises for domain-specific concepts across four domains: general software (`uko-code:`), documents (`uko-doc:`), data schemas (`uko-data:`), and infrastructure (`uko-infra:`). Each domain must register a `DetailLevelMap` that assigns named labels to specific integer depths. Currently only `uko-code:` (Layer 1) is present in the module. The three remaining Layer 1 domain vocabularies — `uko-doc:`, `uko-data:`, and `uko-infra:` — are entirely absent from the `acms/uko` public API. Their `DetailLevelMap` definitions have leaked into application-layer services (`depth_breadth_projection.py`, `acms_skeleton_compressor.py`), creating an architectural inconsistency where domain model types are defined outside the domain model layer. ## Current behavior (for bugs) - `src/cleveragents/acms/uko/__init__.py` exports only Layer 2 (`uko-oo:`, `uko-func:`, `uko-proc:`) and Layer 3 (language-specific) vocabulary types, plus the single Layer 1 `uko-code:` map. - `src/cleveragents/acms/uko/detail_level_maps.py` defines `CODE_DETAIL_LEVEL_MAP` but **not** `DOC_DETAIL_LEVEL_MAP`, `DATA_DETAIL_LEVEL_MAP`, or `INFRA_DETAIL_LEVEL_MAP`. - `src/cleveragents/acms/uko/vocabularies.py` contains only Layer 2 paradigm vocabulary types. - `src/cleveragents/acms/uko/vocabulary_registry.py` only handles `ParadigmVocabulary` (Layer 2). - The `uko-doc:`, `uko-data:`, and `uko-infra:` `DetailLevelMap` definitions exist only inside `src/cleveragents/application/services/depth_breadth_projection.py` and `src/cleveragents/application/services/acms_skeleton_compressor.py`. ## Expected behavior `src/cleveragents/acms/uko/` exports complete Layer 1 domain vocabulary types for **all four** domains (`uko-code:`, `uko-doc:`, `uko-data:`, `uko-infra:`), including: - Dedicated module files (`layer1_doc.py`, `layer1_data.py`, `layer1_infra.py`) containing OWL class/property definitions per the spec (lines 44091–44400+). - `DOC_DETAIL_LEVEL_MAP`, `DATA_DETAIL_LEVEL_MAP`, and `INFRA_DETAIL_LEVEL_MAP` defined in `detail_level_maps.py` and exported from `__init__.py`. - The `vocabulary_registry.py` updated to handle Layer 1 domain vocabularies alongside Layer 2 paradigm vocabularies. - Application-layer services refactored to import these maps from `acms/uko` rather than defining them locally. **Spec-defined ontologies that must be implemented** (lines 44091–44400+): | Namespace | Classes | |-----------|---------| | `uko-doc:` | Document, Part, Chapter, Section, Subsection, Paragraph, CodeBlock, Figure, Table, BlockQuote, ListBlock, Footnote, Citation, Comment, TableOfContents, Index, Glossary | | `uko-data:` | Database, Schema, Table, View, Column, StoredProcedure, Trigger, Migration, Constraint, Index, ForeignKey | | `uko-infra:` | Service, Endpoint, Config, Port, EnvironmentVariable, DeploymentUnit | ## Acceptance criteria - [ ] `src/cleveragents/acms/uko/layer1_doc.py` exists and defines all `uko-doc:` OWL classes and properties per the spec. - [ ] `src/cleveragents/acms/uko/layer1_data.py` exists and defines all `uko-data:` OWL classes and properties per the spec. - [ ] `src/cleveragents/acms/uko/layer1_infra.py` exists and defines all `uko-infra:` OWL classes and properties per the spec. - [ ] `DOC_DETAIL_LEVEL_MAP`, `DATA_DETAIL_LEVEL_MAP`, `INFRA_DETAIL_LEVEL_MAP` are defined in `detail_level_maps.py` and exported from `acms/uko/__init__.py`. - [ ] `vocabulary_registry.py` registers all four Layer 1 domain vocabularies. - [ ] Application services (`depth_breadth_projection.py`, `acms_skeleton_compressor.py`) import Layer 1 maps from `acms/uko` instead of defining them locally. - [ ] All new types are statically typed and pass `nox -e typecheck`. - [ ] All nox stages pass. - [ ] Coverage ≥ 97%. ## Supporting information **Steps to reproduce:** 1. Read `src/cleveragents/acms/uko/__init__.py` — note only Layer 2/3 types are exported. 2. Read `src/cleveragents/acms/uko/detail_level_maps.py` — only `uko-code:`, `uko-oo:`, `uko-func:`, `uko-proc:` maps present. 3. Check spec at `docs/specification.md` lines 44135–44400 for the complete `uko-doc:`, `uko-data:`, `uko-infra:` ontology definitions. 4. Note that `uko-doc:`, `uko-data:`, `uko-infra:` `DetailLevelMap`s are only accessible via `src/cleveragents/application/services/depth_breadth_projection.py`. **Spec reference:** `docs/specification.md` line 43971: > Layer 1 specializes for domain-specific concepts: general software (`uko-code:` — modules, callables, types), **documents (`uko-doc:` — sections, paragraphs, citations), data schemas (`uko-data:` — tables, columns, constraints), and infrastructure (`uko-infra:` — services, endpoints, config)**. Each domain registers a DetailLevelMap that assigns named labels to specific integer depths. Related: Parent Epic #933 (A2A Protocol Compliance / ACMS v1). ## Subtasks - [ ] Implement `src/cleveragents/acms/uko/layer1_doc.py` — `uko-doc:` OWL vocabulary (all classes/properties per spec lines 44091–44200) - [ ] Implement `src/cleveragents/acms/uko/layer1_data.py` — `uko-data:` OWL vocabulary (all classes/properties per spec lines 44201–44300) - [ ] Implement `src/cleveragents/acms/uko/layer1_infra.py` — `uko-infra:` OWL vocabulary (all classes/properties per spec lines 44301–44400) - [ ] Add `DOC_DETAIL_LEVEL_MAP`, `DATA_DETAIL_LEVEL_MAP`, `INFRA_DETAIL_LEVEL_MAP` to `detail_level_maps.py` - [ ] Update `vocabulary_registry.py` to register all four Layer 1 domain vocabularies - [ ] Update `acms/uko/__init__.py` to export all new Layer 1 types and maps - [ ] Refactor `depth_breadth_projection.py` to import Layer 1 maps from `acms/uko` - [ ] Refactor `acms_skeleton_compressor.py` to import Layer 1 maps from `acms/uko` - [ ] Tests (Behave): Add scenarios for all three new Layer 1 vocabulary modules - [ ] Tests (Behave): Add scenarios for updated `vocabulary_registry.py` Layer 1 registration - [ ] Tests (Robot): Add integration test for Layer 1 domain vocabulary round-trip via ACMS - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] 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. - All nox stages pass. - Coverage ≥ 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester
freemo added this to the v3.4.0 milestone 2026-04-05 02:54:22 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Confirmed
  • MoSCoW: Should Have

Valid finding verified during batch triage.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
freemo removed this from the v3.4.0 milestone 2026-04-06 21:01:55 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#2945
No description provided.