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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.31.2.dev16
+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.dev18/docs/rfc/disposable-memory.md

@@ -0,0 +1,188 @@
+# RFC — Disposable Memory process model and `artifact_ref`
+
+> Status: **Accepted** (Phase 2 of #476 Agent OS roadmap).
+> Closes [#512](https://github.com/Q00/ouroboros/issues/512).
+> Related: [#476](https://github.com/Q00/ouroboros/issues/476) M3 (I/O Journal payload policy), [#492](https://github.com/Q00/ouroboros/pull/492) (`agent_process` target_type forward declaration), [#511](https://github.com/Q00/ouroboros/issues/511), [#518](https://github.com/Q00/ouroboros/issues/518) (M6 AgentProcess lifecycle).
+
+## Summary
+
+This RFC specifies how *disposable working memory* is bounded for sub-agent invocations: where their outputs live, how they are referenced from the ledger without leaking back into main session context, when they are reclaimed, and how replay treats them.
+
+The RFC narrows itself deliberately. *Lifecycle verbs* (spawn / pause / resume / cancel / replay) belong to [#518](https://github.com/Q00/ouroboros/issues/518). *Wire and failure semantics* belong to [#511](https://github.com/Q00/ouroboros/issues/511). *Persistent cross-session memory* (Hermes Super Memory and the hippocampus / brain-plasticity research track) is **out of scope** — it is a parallel research stream not part of the 1.0 acceptance surface.
+
+Disposable Memory is, in one sentence, the discipline that makes the slide promise *"main ledger holds only `contract_id + artifact_ref`"* survive in code.
+
+## Scope
+
+This document **does** decide:
+- The execution model for sub-agent invocations.
+- The `artifact_ref` backend (storage layout and addressing).
+- The garbage-collection policy.
+- The mechanism that prevents sub-agent transcripts from leaking into main context.
+- The default replay behavior with respect to artifact reuse vs re-execution.
+
+This document **does not** decide:
+- AgentProcess lifecycle verbs (deferred to [#518](https://github.com/Q00/ouroboros/issues/518)).
+- Mesh transport, envelope, or failure → Directive mapping (deferred to [#511](https://github.com/Q00/ouroboros/issues/511)).
+- Contract Ledger schema (deferred to [#513](https://github.com/Q00/ouroboros/issues/513)).
+- Hermes Super Memory or any persistent cross-session memory layer — explicitly **out of scope**.
+
+## Inherited from earlier RFCs
+
+| Decision | Source | What it means here |
+|---|---|---|
+| IPC channel | [#511](https://github.com/Q00/ouroboros/issues/511) D1 — streamable-http + stdio multiplex | Sub-agents do not need a separate channel; the Mesh transport is the IPC. |
+| Resource limits | [#511](https://github.com/Q00/ouroboros/issues/511) D7 — `deadline_ms` + `retry_budget` only | CPU/mem caps are RFC #476 Tier-3 C3, gated by usage evidence. |
+| Crash → Directive | [#511](https://github.com/Q00/ouroboros/issues/511) D7 — runtime crash → `CANCEL`; schema fail → `CANCEL` | Disposable failures inherit this mapping unchanged. |
+| `contract_id = ULID` | [#511](https://github.com/Q00/ouroboros/issues/511) D2 | Sub-agent invocations are addressed by the same id space. |
+
+## Decisions
+
+### C1 — Execution model: harness invocation, no new Python process layer
+
+**Decision.** A sub-agent spawn is a **bounded harness invocation** on top of the existing provider/runtime pattern in `providers/{codex,opencode,gemini}_cli_adapter.py` and `orchestrator/hermes_runtime.py`. The disposable boundary is the harness child process; the spawn passes a constrained context, the harness produces a result envelope, and the child exits when the contract completes.
+
+This RFC does **not** add a Python `multiprocessing` or `os.fork` layer.
+
+**Rationale.** The slide framing of *"each sub-agent forks like an independent process and dies"* is *already true* in the codebase: every harness adapter spawns the harness as a child process. Inventing a Python-level multiprocessing layer on top of that would duplicate the existing isolation, fail on Windows (`os.fork` is POSIX-only, `multiprocessing.spawn` has pickling problems with stateful objects), and add no isolation we do not already have.
+
+**Important framing.** Isolation here is in the **cooperative-trust sense** (#476), not the security sense. A misbehaving sub-agent can still emit forged directives in cooperation; the same trust model the rest of the system uses. This RFC does not pretend otherwise.
+
+**Risks.**
+- "Isolation" misread as security isolation. Mitigation: this RFC and the implementation explicitly state cooperative-trust framing.
+- Future demand for true sandboxing. Mitigation: the harness pattern allows a sandboxed harness implementation later without changing the disposable contract.
+
+### C2 — Backend: content-addressed filesystem
+
+**Layout.**
+
+```
+.ouroboros/artifacts/
+  ab/                          # 2-level prefix avoids huge directories
+    abc123<sha256>.json        # content-addressed result envelope body
+  contracts/
+    01HXAB.../
+      events.json              # optional per-contract event dump/manifest
+```
+
+`artifact_ref = "sha256:abc123..."` (matches the result envelope shape in [#511](https://github.com/Q00/ouroboros/issues/511) D2). Event dumps are keyed by `contract_id`, not by body hash, so content dedup never overwrites per-contract history.
+
+**Why content-addressed FS.**
+- **Auto-dedup.** Identical sub-agent results across contracts collapse to one file.
+- **Single-DB pressure relieved.** The EventStore stays focused on events; bodies do not bloat its WAL.
+- **OS tools work.** `du`, `find`, `rsync`, `ls` operate on the artifact tree directly — important for local-first introspection.
+- **Single hashing story.** SHA-256 is also used for `prompt_hash` in [#517](https://github.com/Q00/ouroboros/issues/517) M3 I/O Journal; using the same family keeps the operator mental model small.
+
+**Why not external KV (S3 etc.).** RFC #476 Tier-4 Won't (no SaaS).
+
+**Why not SQLite blob.** The EventStore's WAL behavior is not designed for large binary payloads; storing artifacts inline degrades append latency for the rest of the journal.
+
+### C3 — GC: reachability-first + TTL fallback + explicit CLI
+
+```bash
+ouroboros artifacts prune              # dry-run; prints what would be deleted
+ouroboros artifacts prune --apply      # actually delete
+ouroboros artifacts prune --ttl 30d    # override default TTL of 90 days
+```
+
+**Algorithm.**
+
+1. Walk the EventStore once and build a reverse index: `artifact_ref -> set(contract_id)` plus each contract's retention state.
+2. Protect every artifact referenced by an active contract or by a contract still inside the replay-retention window. These are *active reachable* and are never removed by normal prune.
+3. Mark a file under `.ouroboros/artifacts/` for deletion only when its `mtime` exceeds the TTL **and** every referencing contract is outside the artifact-body retention window, or the operator explicitly opts into tombstoning replay bodies with `--allow-replay-tombstone`.
+4. Before deleting a content-addressed blob, write a contract-scoped `artifact.tombstoned` event (or durable per-contract tombstone manifest entry) for **each** referencing contract. This fan-out is required because a single deduplicated hash may be shared by many contracts.
+5. Delete the blob only after those tombstones are durable. Future replay surfaces *"this artifact was pruned; use `--force-rerun` to recompute"* from the contract's own event stream/manifest rather than a silent missing-file error.
+6. Tombstones for still-referenced contracts are retained as part of the replay contract. Tombstones for artifacts whose referencing contracts are also out of retention may be compacted by an explicit ledger-compaction workflow, not by the normal artifact prune path.
+
+**Why local-first / opt-in.** Local-first means GC is never on the hot path; users opt in by running the command. Default policy is conservative (data preservation > disk reclaim). `ouroboros artifacts prune` without `--apply` is a dry-run that prints the candidate list — this is the operator's safety net before destructive action.
+
+**Risks.**
+- Disk growth before the operator notices. Mitigation: TTL fallback default (90 days) + dry-run-by-default CLI semantics.
+- Tombstone accumulation. Mitigation: only an explicit ledger-compaction workflow may drop tombstones after their referencing contracts are also out of retention; deterministic replay wins over routine GC.
+- Hash collision in the SHA-256 namespace. Mitigation: practically zero. Policy is "never silently overwrite" — if a write attempt observes a different existing payload at the same hash, it raises.
+
+### C4 — Context bloat guard: three-layer enforcement
+
+This is the slide promise *"main ledger holds only `contract_id + artifact_ref`"* turned into something that **survives regressions**. Three independent layers because any single layer rots over time.
+
+**Layer 1 — Envelope types.** The Result envelope from [#511](https://github.com/Q00/ouroboros/issues/511) D2 only exposes `contract_id`, `artifact_ref`, `result.status`, `runtime_id`, `duration_ms`, `events_emitted_count`. Sub-agent transcripts are *not a field*. The orchestrator's caller-facing API returns this typed envelope and nothing else; deeper bodies are reachable only via explicit query. The type system itself blocks accidental leakage at compile time.
+
+**Layer 2 — Regression fixture (CI gate).** A test where a sub-agent emits a 1 MB artifact. Assertion: the parent's in-memory context after the call is bounded (e.g., < 4 KB delta, asserted against a high-water-mark probe). This test is wired into CI so that any future PR that quietly enlarges the result envelope fails.
+
+**Layer 3 — Explicit-fetch-only API.** Reading a sub-agent's body is a deliberate call:
+
+```python
+events = event_store.get_events_by_contract(contract_id)
+artifact = artifact_store.read(artifact_ref)
+```
+
+There is *no* implicit accessor that returns a sub-agent's transcript "for free." A grep-able invariant: *no orchestrator code path calls `artifact_store.read` between `spawn` and the next persisted event.* This invariant is testable post-merge by a static check or a runtime assertion in development mode.
+
+**Why three layers.** If any single layer is dropped, the slide promise erodes within a few releases. All three are cheap individually; the discipline is treating them as a set. The common alternative — "developers will remember to keep envelopes small" — is exactly the failure mode this RFC is designed to prevent.
+
+### C5 — Replay default: read artifact + `--force-rerun` opt-in
+
+**Default `replay()` behavior.** Reads from `.ouroboros/artifacts/`. Deterministic, fast, no token spend.
+
+**`--force-rerun`.** Allocates a **new `contract_id`** and runs the work again. This is exactly the rule from [#511](https://github.com/Q00/ouroboros/issues/511) D6: intentional re-execution is a new contract, accidental re-execution via retry is the same contract. Replay inherits that rule rather than inventing a third one.
+
+**Tombstoned artifact path.** If the artifact has been pruned (C3), the default replay first checks the contract-scoped tombstone event/manifest and surfaces that tombstone before asking the user to opt into rerun. **No silent fallback to rerun** — this would corrupt the *replay* verb's promise of determinism.
+
+## Out of scope (explicit)
+
+- **Hermes Super Memory** and any persistent cross-session memory layer. The maintainer's parallel research project on hippocampus modeling and brain-plasticity-inspired forgetting is its own track. Disposable Memory is *the opposite of* Super Memory: disposable is "throw away cleanly," Super Memory is "preserve and forget intelligently." Conflating the two would corrupt both abstractions.
+- **CPU/mem resource limits.** RFC #476 Tier-3 C3, gated by usage evidence.
+- **Forking and branching of sub-agent state.** RFC #476 Tier-3 C1, gated by usage evidence.
+
+## Sequence diagram — one sub-agent invocation
+
+```mermaid
+sequenceDiagram
+    participant O as Orchestrator (main session)
+    participant H as Harness child (sub-agent)
+    participant E as EventStore
+    participant A as Artifact store (.ouroboros/artifacts)
+
+    O->>H: spawn(directive, bounded context, contract_id)
+    H->>E: append tool.call.* / llm.call.* / control.directive.* (target=agent_process/<contract_id>)
+    H->>A: write sha256(<body>).json
+    H-->>O: result envelope { contract_id, artifact_ref, runtime_id, events_emitted_count, ... }
+    H-->>H: process exit (disposable boundary)
+    O->>O: caller sees only the result envelope (Layer 1 type guard)
+    Note over O,A: replay(contract_id) reads E + A, never re-executes
+```
+
+## Cross-RFC consistency
+
+| Subject | Source | This RFC's behaviour |
+|---|---|---|
+| IPC channel | [#511](https://github.com/Q00/ouroboros/issues/511) D1 | Inherited; no separate Disposable IPC. |
+| Resource limits | [#511](https://github.com/Q00/ouroboros/issues/511) D7 | Inherited; `deadline_ms` and `retry_budget` only. |
+| Crash → Directive | [#511](https://github.com/Q00/ouroboros/issues/511) D7 | Inherited; sub-agent crash → `CANCEL`. |
+| `artifact_ref` URI scheme | this RFC, C2 | Used in [#511](https://github.com/Q00/ouroboros/issues/511) D2 result envelope. |
+| Replay determinism | this RFC, C5 + [#511](https://github.com/Q00/ouroboros/issues/511) D6 | `replay()` reads artifacts; new run = new `contract_id`. |
+| Bloat guard | this RFC, C4 | Enforced at envelope, fixture, and API layers. |
+
+## Pre-merge checklist
+
+- [ ] All 5 fresh decisions present (C1–C5), each with option, rationale, risks
+- [ ] Inherited-from list explicitly cites [#511](https://github.com/Q00/ouroboros/issues/511) D1 / D7
+- [ ] Out-of-scope statement names Hermes Super Memory and persistent cross-session memory
+- [ ] Mermaid diagram renders and shows the spawn-to-cleanup loop end to end
+- [ ] Cross-references resolve to existing issues / files
+- [ ] At least two maintainer approvals
+- [ ] C4 three-layer enforcement listed with concrete acceptance examples
+- [ ] `artifact_ref = "sha256:..."` linkage matches what [#513](https://github.com/Q00/ouroboros/issues/513) inherits
+- [ ] "Replay default = read artifact" matches [#511](https://github.com/Q00/ouroboros/issues/511) D6 + [#518](https://github.com/Q00/ouroboros/issues/518) M6
+- [ ] No accidental re-decision of items already settled in [#511](https://github.com/Q00/ouroboros/issues/511)
+
+## Post-merge checklist
+
+- [ ] `docs/rfc/disposable-memory.md` reachable from the docs site (or the README index when it lands)
+- [ ] Issue [#512](https://github.com/Q00/ouroboros/issues/512) closed with a back-link to this PR
+- [ ] At least one Phase E implementation issue opened referencing this RFC (sub-agent migration to disposable model — `qa-judge` is the candidate first migration)
+- [ ] `.ouroboros/artifacts/<prefix>/<sha256>` path layout reflected in `core/project_paths.py` or equivalent
+
+## Rollback
+
+Docs PR with no runtime impact. Rollback = revert the docs PR. The proposal comment in [#512](https://github.com/Q00/ouroboros/issues/512) remains as the working draft.

{ouroboros_ai-0.31.2.dev16 → 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.dev16'
-__version_tuple__ = version_tuple = (0, 31, 2, 'dev16')
+__version__ = version = '0.31.2.dev18'
+__version_tuple__ = version_tuple = (0, 31, 2, 'dev18')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.31.2.dev16 → 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.dev16 → 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"]