feat(acms): implement Temporal Data Model (Revision-Aware RDF) with 3 storage tiers #577

New issue

Closed

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

freemo commented

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

Owner

Metadata

Field	Value
Commit Message	`feat(acms): implement Temporal Data Model (Revision-Aware RDF) with 3 storage tiers`
Branch	`feature/m6-temporal-data-model-revision-aware-rdf`

Summary

Implement the temporal data model for UKO nodes where code changes produce revision chains (validFrom/validUntil/isRevisionOf) rather than deleting and recreating nodes. Also implement the three storage tiers (Hot/Warm/Cold) with temporal alignment for context assembly.

Spec Reference

Section: Architecture > ACMS > Temporal Data Model and Storage Tiers
Lines: ~42468-42500

Current State

The spec defines temporal properties on UKO nodes (validFrom, validUntil, isCurrent, isRevisionOf) but no temporal metadata model exists in the codebase.
context_tiers.py exists with basic tier configuration (hot/warm/cold retention settings), but no temporal alignment logic — it does not filter by isCurrent or manage temporal chains.
No revision chain tracking exists anywhere in the codebase.

Description

Revision-Aware RDF

When code changes, existing UKO nodes are NOT deleted. Instead:

The existing node's validUntil is set to the change timestamp
Its isCurrent is set to false
A new node is created with isRevisionOf pointing to the predecessor
The new node gets isCurrent: true and validFrom set to the change timestamp

This temporal chain enables the temporal-archaeology strategy to find patterns like "this class was refactored 3 times in the last month" or "this function's signature changed after we updated the auth library."

Three Storage Tiers with Temporal Alignment

Tier	Content	Retention	Temporal Filter
Hot	Current UKO graph + recent embeddings + active text index	Until resource removed	`isCurrent = true` only
Warm	Recent decision contexts, plan context snapshots	configurable (default: 24h)	Current + recently-expired nodes
Cold	Archived decision contexts, historical UKO snapshots	configurable (default: 90d)	All temporal versions

Acceptance Criteria

Temporal metadata fields on UKO nodes: validFrom (datetime), validUntil (datetime, nullable), isCurrent (bool), isRevisionOf (node reference, nullable)
Revision chain creation: when a resource changes, old nodes are marked historical and new revision nodes are created with back-links
Hot tier queries automatically filter to isCurrent = true
Warm tier queries include current + recently-expired nodes (within retention window)
Cold tier queries include all temporal versions
Tier retention configuration respected: context.tiers.warm.retention-hours and context.tiers.cold.retention-days
SPARQL query helpers for temporal filtering (e.g., "show me all revisions of this class")
Revision chain traversal: given a current node, find its full history
Unit tests for revision chain creation and temporal filtering
Integration test: modify a resource, verify old node is marked historical, new node is current, revision chain is intact

Depends on: UKO Layer 1 Domain Ontologies (nodes must exist to have temporal metadata)
Parent epic: #367 (Multi-Agent RDF Knowledge Graph)
Used by: temporal-archaeology strategy, Real-time Index Sync/UKOIndexer

Suggested Milestone

v3.5.0

Priority

Medium

Suggested Assignee

@hamza.khyari

Subtasks

Code: Implement temporal metadata fields on UKO nodes (validFrom, validUntil, isCurrent, isRevisionOf) and revision chain creation logic
Code: Implement Hot/Warm/Cold tier temporal filtering: Hot filters to isCurrent=true, Warm includes recently-expired, Cold includes all temporal versions
Code: Implement SPARQL query helpers for temporal filtering and revision chain traversal
Code: Wire tier retention configuration (context.tiers.warm.retention-hours, context.tiers.cold.retention-days)
Docs: Document the temporal data model, revision chain semantics, and storage tier temporal alignment
Behave tests: Add BDD feature file features/acms/temporal_data_model.feature covering revision chain creation and tier-based temporal filtering
Robot tests: Add Robot Framework integration test: modify a resource, verify old node is marked historical, new node is current, revision chain is intact
ASV benchmarks: Add ASV benchmark for revision chain traversal and temporal query performance (benchmarks/bench_temporal_model.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 below 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 Temporal Data Model (Revision-Aware RDF) with 3 storage tiers` | | **Branch** | `feature/m6-temporal-data-model-revision-aware-rdf` | ## Summary Implement the temporal data model for UKO nodes where code changes produce revision chains (`validFrom`/`validUntil`/`isRevisionOf`) rather than deleting and recreating nodes. Also implement the three storage tiers (Hot/Warm/Cold) with temporal alignment for context assembly. ## Spec Reference **Section**: Architecture > ACMS > Temporal Data Model and Storage Tiers **Lines**: ~42468-42500 ## Current State - The spec defines temporal properties on UKO nodes (`validFrom`, `validUntil`, `isCurrent`, `isRevisionOf`) but no temporal metadata model exists in the codebase. - `context_tiers.py` exists with basic tier configuration (hot/warm/cold retention settings), but no temporal alignment logic — it does not filter by `isCurrent` or manage temporal chains. - No revision chain tracking exists anywhere in the codebase. ## Description ### Revision-Aware RDF When code changes, existing UKO nodes are NOT deleted. Instead: 1. The existing node's `validUntil` is set to the change timestamp 2. Its `isCurrent` is set to `false` 3. A new node is created with `isRevisionOf` pointing to the predecessor 4. The new node gets `isCurrent: true` and `validFrom` set to the change timestamp This temporal chain enables the `temporal-archaeology` strategy to find patterns like "this class was refactored 3 times in the last month" or "this function's signature changed after we updated the auth library." ### Three Storage Tiers with Temporal Alignment | Tier | Content | Retention | Temporal Filter | |------|---------|-----------|----------------| | **Hot** | Current UKO graph + recent embeddings + active text index | Until resource removed | `isCurrent = true` only | | **Warm** | Recent decision contexts, plan context snapshots | configurable (default: 24h) | Current + recently-expired nodes | | **Cold** | Archived decision contexts, historical UKO snapshots | configurable (default: 90d) | All temporal versions | ## Acceptance Criteria - [ ] Temporal metadata fields on UKO nodes: `validFrom` (datetime), `validUntil` (datetime, nullable), `isCurrent` (bool), `isRevisionOf` (node reference, nullable) - [ ] Revision chain creation: when a resource changes, old nodes are marked historical and new revision nodes are created with back-links - [ ] Hot tier queries automatically filter to `isCurrent = true` - [ ] Warm tier queries include current + recently-expired nodes (within retention window) - [ ] Cold tier queries include all temporal versions - [ ] Tier retention configuration respected: `context.tiers.warm.retention-hours` and `context.tiers.cold.retention-days` - [ ] SPARQL query helpers for temporal filtering (e.g., "show me all revisions of this class") - [ ] Revision chain traversal: given a current node, find its full history - [ ] Unit tests for revision chain creation and temporal filtering - [ ] Integration test: modify a resource, verify old node is marked historical, new node is current, revision chain is intact ## Related Issues - Depends on: UKO Layer 1 Domain Ontologies (nodes must exist to have temporal metadata) - Parent epic: #367 (Multi-Agent RDF Knowledge Graph) - Used by: `temporal-archaeology` strategy, Real-time Index Sync/UKOIndexer ## Suggested Milestone v3.5.0 ## Priority Medium ## Suggested Assignee @hamza.khyari ## Subtasks - [ ] **Code**: Implement temporal metadata fields on UKO nodes (`validFrom`, `validUntil`, `isCurrent`, `isRevisionOf`) and revision chain creation logic - [ ] **Code**: Implement Hot/Warm/Cold tier temporal filtering: Hot filters to `isCurrent=true`, Warm includes recently-expired, Cold includes all temporal versions - [ ] **Code**: Implement SPARQL query helpers for temporal filtering and revision chain traversal - [ ] **Code**: Wire tier retention configuration (`context.tiers.warm.retention-hours`, `context.tiers.cold.retention-days`) - [ ] **Docs**: Document the temporal data model, revision chain semantics, and storage tier temporal alignment - [ ] **Behave tests**: Add BDD feature file `features/acms/temporal_data_model.feature` covering revision chain creation and tier-based temporal filtering - [ ] **Robot tests**: Add Robot Framework integration test: modify a resource, verify old node is marked historical, new node is current, revision chain is intact - [ ] **ASV benchmarks**: Add ASV benchmark for revision chain traversal and temporal query performance (`benchmarks/bench_temporal_model.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 below 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