ouroboros-ai 0.31.2.dev17__tar.gz → 0.31.2.dev18__tar.gz

{ouroboros_ai-0.31.2.dev17 → ouroboros_ai-0.31.2.dev18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.31.2.dev17
+Version: 0.31.2.dev18
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.31.2.dev17 → ouroboros_ai-0.31.2.dev18}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.31.2.dev17'
-__version_tuple__ = version_tuple = (0, 31, 2, 'dev17')
+__version__ = version = '0.31.2.dev18'
+__version_tuple__ = version_tuple = (0, 31, 2, 'dev18')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.31.2.dev17 → ouroboros_ai-0.31.2.dev18}/src/ouroboros/core/lineage.py

@@ -369,6 +369,24 @@ class RewindRecord(BaseModel, frozen=True):
     discarded_generations: tuple[GenerationRecord, ...] = ()
 
 
+class ControlDirectiveEmission(BaseModel, frozen=True):
+    """One ``control.directive.emitted`` event folded onto a lineage.
+
+    Captures the audit-level "who/what/why/when" of a control-plane
+    decision so it appears in the lineage timeline alongside state events
+    (per RFC #476 M2 / sub-RFC #511). The full event row remains in the
+    EventStore; this is the projected view used by callers.
+    """
+
+    directive: str
+    reason: str
+    emitted_by: str
+    timestamp: datetime
+    generation_number: int | None = None
+    phase: str | None = None
+    is_terminal: bool = False
+
+
 class OntologyLineage(BaseModel, frozen=True):
     """Tracks O₁ → O₂ → O₃ evolution across generations.
 
@@ -382,6 +400,7 @@ class OntologyLineage(BaseModel, frozen=True):
     goal: str
     generations: tuple[GenerationRecord, ...] = Field(default_factory=tuple)
     rewind_history: tuple[RewindRecord, ...] = Field(default_factory=tuple)
+    directive_emissions: tuple[ControlDirectiveEmission, ...] = Field(default_factory=tuple)
     status: LineageStatus = LineageStatus.ACTIVE
     created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
 
@@ -410,6 +429,18 @@ class OntologyLineage(BaseModel, frozen=True):
         """Return new lineage with updated status."""
         return self.model_copy(update={"status": status})
 
+    def with_directive_emission(self, emission: ControlDirectiveEmission) -> OntologyLineage:
+        """Return new lineage with the directive emission appended.
+
+        Folds one ``control.directive.emitted`` event into the lineage's
+        timeline view. Existing emissions are preserved; ordering is
+        whatever the projector replayed (timestamp order from the
+        EventStore).
+        """
+        return self.model_copy(
+            update={"directive_emissions": self.directive_emissions + (emission,)}
+        )
+
     def rewind_to(self, generation_number: int) -> OntologyLineage:
         """Return lineage truncated to the given generation.
 

{ouroboros_ai-0.31.2.dev17 → ouroboros_ai-0.31.2.dev18}/src/ouroboros/evolution/projector.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import logging
 
 from ouroboros.core.lineage import (
+    ControlDirectiveEmission,
     EvaluationSummary,
     GenerationPhase,
     GenerationRecord,
@@ -51,6 +52,7 @@ class LineageProjector:
         lineage: OntologyLineage | None = None
         generations: dict[int, GenerationRecord] = {}
         rewind_history: list[RewindRecord] = []
+        directive_emissions: list[ControlDirectiveEmission] = []
 
         for event in events:
             if event.type == "lineage.created":
@@ -191,20 +193,59 @@ class LineageProjector:
                         discarded_generations=discarded,
                     )
                 )
-                # Remove generations after the rewind point
+                # Remove active generations after the rewind point. Directive
+                # emissions remain in the projected audit timeline so reports
+                # can still explain discarded branches preserved in
+                # rewind_history.
                 generations = {k: v for k, v in generations.items() if k <= to_gen}
                 if lineage is not None:
                     lineage = lineage.with_status(LineageStatus.ACTIVE)
 
+            elif event.type == "control.directive.emitted":
+                # Fold control-plane directives onto the lineage timeline
+                # alongside state events, per RFC #476 M2 / sub-RFC #511.
+                # The full event row remains in the EventStore; we project
+                # the audit-level summary so callers (TUI, reports) can
+                # render decisions without a second query.
+                data = event.data
+                directive_value = data.get("directive")
+                if not isinstance(directive_value, str) or not directive_value:
+                    # Silently skip malformed directive events rather than
+                    # corrupt the projection; the raw row is still queryable
+                    # via event_store directly for postmortem.
+                    continue
+                generation_number = data.get("generation_number")
+                if generation_number is not None and not isinstance(generation_number, int):
+                    continue
+                phase = data.get("phase")
+                if phase is not None and not isinstance(phase, str):
+                    continue
+                is_terminal = data.get("is_terminal", False)
+                if not isinstance(is_terminal, bool):
+                    continue
+                directive_emissions.append(
+                    ControlDirectiveEmission(
+                        directive=directive_value,
+                        reason=str(data.get("reason", "")),
+                        emitted_by=str(data.get("emitted_by", "")),
+                        timestamp=event.timestamp,
+                        generation_number=generation_number,
+                        phase=phase,
+                        is_terminal=is_terminal,
+                    )
+                )
+
         if lineage is None:
             return None
 
-        # Build final lineage with sorted generations and rewind history
+        # Build final lineage with sorted generations, rewind history, and
+        # any control-plane directive emissions that were folded in.
         sorted_records = tuple(generations[k] for k in sorted(generations.keys()))
         return lineage.model_copy(
             update={
                 "generations": sorted_records,
                 "rewind_history": tuple(rewind_history),
+                "directive_emissions": tuple(directive_emissions),
             }
         )
 

ouroboros_ai-0.31.2.dev18/tests/unit/test_lineage.py

@@ -0,0 +1,39 @@
+def test_rewind_to_retains_directives_for_discarded_generation_audit() -> None:
+    from datetime import UTC, datetime
+
+    from ouroboros.core.lineage import ControlDirectiveEmission, GenerationRecord, OntologyLineage
+    from ouroboros.core.seed import OntologyField, OntologySchema
+
+    ontology = OntologySchema(
+        name="Test",
+        description="test",
+        fields=(OntologyField(name="x", field_type="string", description="x"),),
+    )
+    lineage = OntologyLineage(
+        lineage_id="lin_rewind_directives",
+        goal="test",
+        generations=(
+            GenerationRecord(generation_number=1, seed_id="s1", ontology_snapshot=ontology),
+            GenerationRecord(generation_number=2, seed_id="s2", ontology_snapshot=ontology),
+        ),
+        directive_emissions=(
+            ControlDirectiveEmission(
+                directive="evolve",
+                reason="gen1",
+                emitted_by="test",
+                timestamp=datetime.now(UTC),
+                generation_number=1,
+            ),
+            ControlDirectiveEmission(
+                directive="retry",
+                reason="gen2",
+                emitted_by="test",
+                timestamp=datetime.now(UTC),
+                generation_number=2,
+            ),
+        ),
+    )
+
+    rewound = lineage.rewind_to(1)
+
+    assert [e.directive for e in rewound.directive_emissions] == ["evolve", "retry"]

ouroboros_ai-0.31.2.dev18/tests/unit/test_projector_directives.py

@@ -0,0 +1,278 @@
+"""Unit tests for LineageProjector folding control.directive.emitted events.
+
+Covers (issue #514, closes #473):
+- A `control.directive.emitted` event with `aggregate_type="lineage"` is
+  folded onto the projected `OntologyLineage.directive_emissions` view.
+- Multiple directives appear in event-order on the projection.
+- Optional correlation fields (generation_number, phase, is_terminal) are
+  preserved when present and tolerate absence.
+- Malformed directive events (missing/empty `directive` payload) are
+  skipped silently rather than corrupting the projection.
+- Existing lineage state (generations, status) projects unchanged when
+  directive events are interleaved.
+"""
+
+from datetime import UTC, datetime
+
+from ouroboros.core.lineage import LineageStatus
+from ouroboros.events.base import BaseEvent
+from ouroboros.evolution.projector import LineageProjector
+
+LINEAGE_ID = "lin_directive_projector_test"
+
+
+def _event(
+    event_type: str,
+    data: dict | None = None,
+    *,
+    timestamp: datetime | None = None,
+) -> BaseEvent:
+    """Build a `BaseEvent` aggregated by the lineage under test."""
+    payload: dict = data or {}
+    return BaseEvent(
+        type=event_type,
+        aggregate_type="lineage",
+        aggregate_id=LINEAGE_ID,
+        data=payload,
+        timestamp=timestamp or datetime.now(UTC),
+    )
+
+
+class TestDirectiveProjection:
+    def test_directive_appears_on_projected_lineage(self) -> None:
+        """A control.directive.emitted event is folded onto directive_emissions."""
+        projector = LineageProjector()
+        events = [
+            _event("lineage.created", {"goal": "intent under test"}),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "evolve",
+                    "reason": "Advance generation.",
+                    "emitted_by": "evolver",
+                    "lineage_id": LINEAGE_ID,
+                    "generation_number": 1,
+                    "phase": "reflecting",
+                    "is_terminal": False,
+                },
+            ),
+        ]
+
+        lineage = projector.project(events)
+
+        assert lineage is not None
+        assert len(lineage.directive_emissions) == 1
+        emission = lineage.directive_emissions[0]
+        assert emission.directive == "evolve"
+        assert emission.reason == "Advance generation."
+        assert emission.emitted_by == "evolver"
+        assert emission.generation_number == 1
+        assert emission.phase == "reflecting"
+        assert emission.is_terminal is False
+
+    def test_directives_preserve_event_order(self) -> None:
+        """Multiple directives arrive on the projection in event-replay order."""
+        projector = LineageProjector()
+        events = [
+            _event("lineage.created", {"goal": "ordered emissions"}),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "evolve",
+                    "reason": "First emission.",
+                    "emitted_by": "evolver",
+                },
+            ),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "retry",
+                    "reason": "Second emission.",
+                    "emitted_by": "evolver",
+                    "is_terminal": False,
+                },
+            ),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "converge",
+                    "reason": "Third emission.",
+                    "emitted_by": "evolver",
+                    "is_terminal": True,
+                },
+            ),
+        ]
+
+        lineage = projector.project(events)
+
+        assert lineage is not None
+        emitted = [e.directive for e in lineage.directive_emissions]
+        assert emitted == ["evolve", "retry", "converge"]
+        assert lineage.directive_emissions[-1].is_terminal is True
+
+    def test_optional_correlation_fields_default_to_none(self) -> None:
+        """generation_number and phase are None when absent from the payload."""
+        projector = LineageProjector()
+        events = [
+            _event("lineage.created", {"goal": "no correlations"}),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "wait",
+                    "reason": "External input pending.",
+                    "emitted_by": "orchestrator",
+                },
+            ),
+        ]
+
+        lineage = projector.project(events)
+
+        assert lineage is not None
+        emission = lineage.directive_emissions[0]
+        assert emission.generation_number is None
+        assert emission.phase is None
+
+    def test_malformed_directive_event_is_skipped(self) -> None:
+        """A directive event without a usable directive payload is silently skipped."""
+        projector = LineageProjector()
+        events = [
+            _event("lineage.created", {"goal": "malformed input"}),
+            _event(
+                "control.directive.emitted",
+                {
+                    # 'directive' missing on purpose
+                    "reason": "Bad event row.",
+                    "emitted_by": "evolver",
+                },
+            ),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "",  # empty string also rejected
+                    "reason": "Empty directive value.",
+                    "emitted_by": "evolver",
+                },
+            ),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "continue",
+                    "reason": "Healthy event row.",
+                    "emitted_by": "evolver",
+                },
+            ),
+        ]
+
+        lineage = projector.project(events)
+
+        assert lineage is not None
+        # Only the healthy row survives; malformed rows are absorbed silently.
+        assert [e.directive for e in lineage.directive_emissions] == ["continue"]
+
+    def test_directives_do_not_corrupt_existing_lineage_state(self) -> None:
+        """Lineage state events project unchanged when interleaved with directives."""
+        projector = LineageProjector()
+        events = [
+            _event("lineage.created", {"goal": "interleaved replay"}),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "evolve",
+                    "reason": "Pre-converge directive.",
+                    "emitted_by": "evolver",
+                },
+            ),
+            _event(
+                "lineage.converged",
+                {
+                    "generation_number": 1,
+                    "reason": "All ACs passed.",
+                    "ontology_similarity": 1.0,
+                },
+            ),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "converge",
+                    "reason": "Post-converge directive.",
+                    "emitted_by": "evolver",
+                    "is_terminal": True,
+                },
+            ),
+        ]
+
+        lineage = projector.project(events)
+
+        assert lineage is not None
+        assert lineage.status == LineageStatus.CONVERGED
+        assert len(lineage.directive_emissions) == 2
+        assert lineage.directive_emissions[-1].directive == "converge"
+
+    def test_rewind_retains_directives_for_discarded_generation_audit(self) -> None:
+        """Directive audit timeline still explains discarded rewind branches."""
+        projector = LineageProjector()
+        events = [
+            _event("lineage.created", {"goal": "rewind directive pruning"}),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "evolve",
+                    "reason": "Gen 1 decision.",
+                    "emitted_by": "evolver",
+                    "generation_number": 1,
+                },
+            ),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "retry",
+                    "reason": "Discarded Gen 2 decision.",
+                    "emitted_by": "evolver",
+                    "generation_number": 2,
+                },
+            ),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "wait",
+                    "reason": "Unscoped audit note.",
+                    "emitted_by": "orchestrator",
+                },
+            ),
+            _event("lineage.rewound", {"from_generation": 2, "to_generation": 1}),
+        ]
+
+        lineage = projector.project(events)
+
+        assert lineage is not None
+        assert [e.directive for e in lineage.directive_emissions] == ["evolve", "retry", "wait"]
+
+    def test_invalid_directive_correlation_shape_is_skipped(self) -> None:
+        """Malformed optional fields should not abort lineage projection."""
+        projector = LineageProjector()
+        events = [
+            _event("lineage.created", {"goal": "invalid directive shape"}),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "retry",
+                    "reason": "Bad generation number.",
+                    "emitted_by": "evolver",
+                    "generation_number": "two",
+                },
+            ),
+            _event(
+                "control.directive.emitted",
+                {
+                    "directive": "continue",
+                    "reason": "Healthy row.",
+                    "emitted_by": "evolver",
+                    "generation_number": 1,
+                },
+            ),
+        ]
+
+        lineage = projector.project(events)
+
+        assert lineage is not None
+        assert [e.directive for e in lineage.directive_emissions] == ["continue"]