cleveragents/cleveragents-core

Fork 3

feat(acms): operationalize UKO runtime with provenance and temporal versioning #1312

Merged

freemo merged 1 commit from feature/m6-uko-runtime into master

2026-04-02 17:09:15 +00:00

freemo commented

2026-04-02 11:29:06 +00:00

Owner

Summary

Operationalizes the Universal Knowledge Ontology (UKO) runtime per issue #891, implementing provenance tracking, temporal versioning, ACMS context strategy integration, four-layer ontology population, implicit relationship inference, and graph persistence.

Changes

New Services

uko_query_interface.py: UKOQueryInterface — typed interface for ACMS context strategies to query UKO classification data (layer, type, implicit relations)
uko_inference.py: UKOInferenceEngine — semantic analysis producing uko:implicitSiblingOf, uko:implicitContains, and uko:implicitDependsOn triples with confidence 0.7
uko_persistence.py: UKOGraphPersistence — serialises/restores UKO graph state via JSONFilePersistenceBackend or InMemoryPersistenceBackend

Modified Services

uko_indexer_internals.py: index_graph() now runs inference and populates uko:layer triples for all four ontology layers (0=universal, 1=domain, 2=paradigm, 3=technology)

Tests

features/uko_runtime.feature: 47 new BDD scenarios covering all acceptance criteria
features/steps/uko_runtime_steps.py: Step definitions for the new feature

Acceptance Criteria Status

✅ UKO indexer produces typed triples with provenance metadata (sourceResource, validFrom, isCurrent)
✅ Temporal versioning tracks ontology state across indexing runs (revision chain)
✅ ACMS context strategies can query UKO for resource classification via UKOQueryInterface
✅ Four ontology layers populated during resource indexing via uko:layer triples
✅ Implicit relationship inference runs during indexing
✅ UKO data persists across application restarts via UKOGraphPersistence
✅ 47 BDD scenarios: typed triples, temporal query, provenance
✅ nox -s lint typecheck passes (0 errors)
✅ All existing UKO tests continue to pass (312 scenarios)

Closes #891

## Summary Operationalizes the Universal Knowledge Ontology (UKO) runtime per issue #891, implementing provenance tracking, temporal versioning, ACMS context strategy integration, four-layer ontology population, implicit relationship inference, and graph persistence. ## Changes ### New Services - **`uko_query_interface.py`**: `UKOQueryInterface` — typed interface for ACMS context strategies to query UKO classification data (layer, type, implicit relations) - **`uko_inference.py`**: `UKOInferenceEngine` — semantic analysis producing `uko:implicitSiblingOf`, `uko:implicitContains`, and `uko:implicitDependsOn` triples with confidence 0.7 - **`uko_persistence.py`**: `UKOGraphPersistence` — serialises/restores UKO graph state via `JSONFilePersistenceBackend` or `InMemoryPersistenceBackend` ### Modified Services - **`uko_indexer_internals.py`**: `index_graph()` now runs inference and populates `uko:layer` triples for all four ontology layers (0=universal, 1=domain, 2=paradigm, 3=technology) ### Tests - **`features/uko_runtime.feature`**: 47 new BDD scenarios covering all acceptance criteria - **`features/steps/uko_runtime_steps.py`**: Step definitions for the new feature ## Acceptance Criteria Status - ✅ UKO indexer produces typed triples with provenance metadata (sourceResource, validFrom, isCurrent) - ✅ Temporal versioning tracks ontology state across indexing runs (revision chain) - ✅ ACMS context strategies can query UKO for resource classification via `UKOQueryInterface` - ✅ Four ontology layers populated during resource indexing via `uko:layer` triples - ✅ Implicit relationship inference runs during indexing - ✅ UKO data persists across application restarts via `UKOGraphPersistence` - ✅ 47 BDD scenarios: typed triples, temporal query, provenance - ✅ `nox -s lint typecheck` passes (0 errors) - ✅ All existing UKO tests continue to pass (312 scenarios) Closes #891

freemo added 1 commit

2026-04-02 11:29:06 +00:00

feat(acms): operationalize UKO runtime with provenance and temporal versioning

CI / build (pull_request) Successful in 16s

Details

CI / helm (pull_request) Successful in 20s

Details

CI / lint (pull_request) Successful in 3m19s

Details

CI / quality (pull_request) Successful in 3m44s

Details

CI / typecheck (pull_request) Successful in 4m0s

Details

CI / security (pull_request) Successful in 4m6s

Details

CI / unit_tests (pull_request) Successful in 9m12s

Details

CI / docker (pull_request) Successful in 1m35s

Details

CI / coverage (pull_request) Successful in 12m20s

Details

CI / e2e_tests (pull_request) Successful in 19m58s

Details

CI / integration_tests (pull_request) Successful in 24m40s

Details

CI / status-check (pull_request) Successful in 1s

Details

CI / benchmark-publish (pull_request) Has been skipped

Details

CI / benchmark-regression (pull_request) Successful in 55m41s

Details

a349e7b9fe

Implements the UKO runtime operationalization per issue #891:

- UKO indexer now produces typed triples with provenance metadata
  (sourceResource, validFrom, isCurrent, sourcePath, sourceRange)
- Temporal versioning (revision chain) already existed; wired into
  new BDD tests covering store_initial_node, create_revision,
  get_revision_chain, get_history, get_current, mark_historical
- UKO query interface (UKOQueryInterface) wires UKO classification
  data into ACMS context strategies via classify_resource(),
  get_resources_by_layer(), and get_implicit_relations()
- Four ontology layers (0=universal, 1=domain, 2=paradigm,
  3=technology) are now populated during resource indexing via
  uko:layer triples on the resource URI
- Implicit relationship inference (UKOInferenceEngine) runs during
  indexing to produce uko:implicitSiblingOf, uko:implicitContains,
  and uko:implicitDependsOn triples with confidence 0.7
- UKO graph persistence (UKOGraphPersistence) serialises graph state
  to JSON (JSONFilePersistenceBackend) or in-memory store
  (InMemoryPersistenceBackend) for cross-restart persistence
- 47 new BDD scenarios in features/uko_runtime.feature covering all
  acceptance criteria; all existing UKO tests continue to pass

ISSUES CLOSED: #891

freemo referenced this pull request

2026-04-02 16:53:56 +00:00

feat(acms): operationalize UKO runtime with provenance tracking and temporal versioning #891

freemo commented

2026-04-02 17:03:44 +00:00

Author

Owner

Review claimed by reviewer pool instance reviewer-pool-1. Dispatching independent code review.

freemo reviewed

2026-04-02 17:09:05 +00:00

freemo left a comment

Code Review — APPROVED ✅ (self-review, posted as comment)

Summary

This PR operationalizes the UKO runtime per issue #891, implementing provenance tracking, temporal versioning, ACMS context strategy integration, four-layer ontology population, implicit relationship inference, and graph persistence. The implementation is clean, well-tested, and aligns with the specification.

Files Reviewed (6 files, +1908/-3 lines)

File	Status	Notes
`uko_inference.py` (new, 174 lines)	✅	Clean inference engine with 3 strategies (sibling, containment, dependency). Smart O(n²) avoidance.
`uko_persistence.py` (new, 323 lines)	✅	Protocol-based design with JSON file and in-memory backends. Proper validation.
`uko_query_interface.py` (new, 343 lines)	✅	Well-structured query interface with ClassificationResult dataclass. Comprehensive layer inference.
`uko_indexer_internals.py` (+87/-3)	✅	Clean integration of inference and layer triples into `index_graph()`. Doesn't mutate inputs.
`uko_runtime.feature` (new, 266 lines)	✅	47 BDD scenarios covering all acceptance criteria.
`uko_runtime_steps.py` (new, 718 lines)	✅	Well-structured step definitions with proper prefixing to avoid collisions.

Specification Alignment ✅

Four ontology layers (universal=0, domain=1, paradigm=2, technology=3) per spec §185 ✅
Provenance metadata (sourceResource, validFrom, isCurrent) ✅
Temporal versioning via revision chains ✅
Implicit relationship inference (uko:implicitSiblingOf, uko:implicitContains, uko:implicitDependsOn) ✅
ACMS context strategy integration via UKOQueryInterface ✅
Graph persistence across restarts via UKOGraphPersistence ✅

Test Quality ✅

47 BDD scenarios covering:

Happy paths for all new services
Error paths (empty inputs, invalid types, invalid layers)
Edge cases (unknown URIs, empty graphs, unknown projects)
Round-trip persistence (save → restore)
Temporal versioning chain (store → revise → query chain)
All four ontology layers
All three inference types
ClassificationResult validation

Minor Observations (non-blocking)

_infer_layer_from_uri naming: This function is prefixed with _ (private) but is imported by uko_indexer_internals.py. Consider making it public if it's part of the package API.
# type: ignore[import-untyped] on behave import: Ubiquitous pattern across all step definition files (behave doesn't ship type stubs). Consistent with existing codebase.
# type: ignore[arg-type] in test assertions: Used intentionally to test TypeError handling by passing wrong types. Acceptable in test code.
PR metadata: Missing Type/Feature label and v3.6.0 milestone assignment.

Correctness ✅

No logic errors detected
Proper boundary condition handling
No resource leaks
Input validation present on all public methods
Error handling follows fail-fast principles

Security ✅

No secrets or credentials in code
Input validation present
No injection vulnerabilities

Decision: APPROVE and MERGE — Code is well-implemented, well-tested, and spec-aligned. Proceeding with squash merge.

## Code Review — APPROVED ✅ (self-review, posted as comment) ### Summary This PR operationalizes the UKO runtime per issue #891, implementing provenance tracking, temporal versioning, ACMS context strategy integration, four-layer ontology population, implicit relationship inference, and graph persistence. The implementation is clean, well-tested, and aligns with the specification. ### Files Reviewed (6 files, +1908/-3 lines) | File | Status | Notes | |------|--------|-------| | `uko_inference.py` (new, 174 lines) | ✅ | Clean inference engine with 3 strategies (sibling, containment, dependency). Smart O(n²) avoidance. | | `uko_persistence.py` (new, 323 lines) | ✅ | Protocol-based design with JSON file and in-memory backends. Proper validation. | | `uko_query_interface.py` (new, 343 lines) | ✅ | Well-structured query interface with ClassificationResult dataclass. Comprehensive layer inference. | | `uko_indexer_internals.py` (+87/-3) | ✅ | Clean integration of inference and layer triples into `index_graph()`. Doesn't mutate inputs. | | `uko_runtime.feature` (new, 266 lines) | ✅ | 47 BDD scenarios covering all acceptance criteria. | | `uko_runtime_steps.py` (new, 718 lines) | ✅ | Well-structured step definitions with proper prefixing to avoid collisions. | ### Specification Alignment ✅ - Four ontology layers (universal=0, domain=1, paradigm=2, technology=3) per spec §185 ✅ - Provenance metadata (sourceResource, validFrom, isCurrent) ✅ - Temporal versioning via revision chains ✅ - Implicit relationship inference (uko:implicitSiblingOf, uko:implicitContains, uko:implicitDependsOn) ✅ - ACMS context strategy integration via `UKOQueryInterface` ✅ - Graph persistence across restarts via `UKOGraphPersistence` ✅ ### Test Quality ✅ 47 BDD scenarios covering: - Happy paths for all new services - Error paths (empty inputs, invalid types, invalid layers) - Edge cases (unknown URIs, empty graphs, unknown projects) - Round-trip persistence (save → restore) - Temporal versioning chain (store → revise → query chain) - All four ontology layers - All three inference types - ClassificationResult validation ### Minor Observations (non-blocking) 1. **`_infer_layer_from_uri` naming**: This function is prefixed with `_` (private) but is imported by `uko_indexer_internals.py`. Consider making it public if it's part of the package API. 2. **`# type: ignore[import-untyped]`** on behave import: Ubiquitous pattern across all step definition files (behave doesn't ship type stubs). Consistent with existing codebase. 3. **`# type: ignore[arg-type]`** in test assertions: Used intentionally to test TypeError handling by passing wrong types. Acceptable in test code. 4. **PR metadata**: Missing `Type/Feature` label and `v3.6.0` milestone assignment. ### Correctness ✅ - No logic errors detected - Proper boundary condition handling - No resource leaks - Input validation present on all public methods - Error handling follows fail-fast principles ### Security ✅ - No secrets or credentials in code - Input validation present - No injection vulnerabilities **Decision: APPROVE and MERGE** — Code is well-implemented, well-tested, and spec-aligned. Proceeding with squash merge.

freemo merged commit 0787f42e2f into master

2026-04-02 17:09:15 +00:00

freemo deleted branch feature/m6-uko-runtime

2026-04-02 17:09:17 +00:00

freemo referenced this pull request

2026-04-02 17:09:23 +00:00

feat(acms): operationalize UKO runtime with provenance tracking and temporal versioning #891

freemo referenced this pull request

2026-04-02 17:11:30 +00:00

[Automated] Product Build Session State #1314

freemo referenced this pull request from a commit

2026-04-02 17:19:37 +00:00