claude-smart 0.2.44 → 0.2.46

package/plugin/vendor/reflexio/reflexio/lib/_profiles.py

@@ -1,14 +1,21 @@
 import logging
+from collections import defaultdict
 
 logger = logging.getLogger(__name__)
 
 from datetime import UTC, datetime
+from typing import Protocol
 
 from reflexio.lib._base import (
     STORAGE_NOT_CONFIGURED_MSG,
     ReflexioBase,
     _require_storage,
 )
+from reflexio.models.api_schema.domain.entities import (
+    LineageEvent,
+    ProfileChangeLog,
+    UserProfile,
+)
 from reflexio.models.api_schema.retriever_schema import (
     GetProfileStatisticsResponse,
     GetUserProfilesRequest,
@@ -36,7 +43,7 @@ from reflexio.models.api_schema.service_schemas import (
     UpgradeProfilesRequest,
     UpgradeProfilesResponse,
 )
-from reflexio.server.services.profile.profile_generation_service import (
+from reflexio.server.services.profile.service import (
     ProfileGenerationService,
 )
 from reflexio.server.tracing import profile_step
@@ -199,15 +206,21 @@ class ProfilesMixin(ReflexioBase):
         )
 
     def get_profile_change_logs(self) -> ProfileChangeLogResponse:
-        """Get profile change logs.
+        """Get profile change logs, served from the lineage reconstruction.
+
+        The change-log view is rebuilt on demand from ``lineage_event`` linkage
+        joined to survivor/tombstone content via
+        :func:`reconstruct_profile_change_log`. The legacy ``profile_change_logs``
+        table is no longer written (B3 Task 6) or read (B3 Task 7); it is retained
+        frozen until its removal in Task 8.
 
         Returns:
-            ProfileChangeLogResponse: Response containing profile change logs
+            ProfileChangeLogResponse: Response containing the reconstructed
+                profile change logs.
         """
         if not self._is_storage_configured():
             return ProfileChangeLogResponse(success=True, profile_change_logs=[])
-        changelogs = self._get_storage().get_profile_change_logs()
-        return ProfileChangeLogResponse(success=True, profile_change_logs=changelogs)
+        return reconstruct_profile_change_log(self._get_storage())
 
     @_require_storage(DeleteUserProfileResponse)
     def delete_profile(
@@ -401,7 +414,7 @@ class ProfilesMixin(ReflexioBase):
                 status_filter = [None]  # Default to current profiles
 
         profiles = self._get_storage().get_user_profile(
-            request.user_id, status_filter=status_filter
+            request.user_id, status_filter=status_filter, tags=request.tags
         )
         profiles = sorted(
             profiles, key=lambda x: x.last_modified_timestamp, reverse=True
@@ -543,3 +556,182 @@ class ProfilesMixin(ReflexioBase):
             return GetProfileStatisticsResponse(
                 success=False, msg=f"Failed to get profile statistics: {str(e)}"
             )
+
+
+# ---------------------------------------------------------------------------
+# Standalone read-side reconstruction (Phase B3 Task 2)
+# ---------------------------------------------------------------------------
+
+
+class ChangeLogReadStorage(Protocol):
+    """The storage read surface ``reconstruct_profile_change_log`` requires.
+
+    Both the real ``BaseStorage`` backends and the read-only
+    ``RestStorageReader`` satisfy this structurally — no inheritance required —
+    so reconstruction can run against either without an unsound ``cast`` to
+    ``BaseStorage``.
+    """
+
+    org_id: str
+
+    def get_lineage_events(
+        self,
+        *,
+        entity_type: str | None = ...,
+        entity_id: str | None = ...,
+        org_id: str | None = ...,
+        request_id: str | None = ...,
+    ) -> list[LineageEvent]: ...
+
+    def get_distinct_generated_from_request_ids(self) -> list[str]: ...
+
+    def get_profiles_by_generated_from_request_id(
+        self, request_id: str
+    ) -> list[UserProfile]: ...
+
+    def get_all_generated_profiles(self) -> list[UserProfile]: ...
+
+    def get_profile_by_id(
+        self, profile_id: str, *, include_tombstones: bool = ...
+    ) -> UserProfile | None: ...
+
+
+def reconstruct_profile_change_log(
+    storage: ChangeLogReadStorage,
+    *,
+    limit: int = 100,
+) -> ProfileChangeLogResponse:
+    """Rebuild the ProfileChangeLog view using time-travel-stable signals.
+
+    Uses two immutable / stable signals to classify every dedup run:
+
+    * **added(R)** — profiles whose ``generated_from_request_id == R``.  This
+      column is set at creation and never changes, so it correctly classifies
+      a profile as "added in run R" even if it is later tombstoned in run R2.
+      Tombstones are included so the content is available.
+
+    * **removed(R)** — entity_ids of ``status_change`` lineage events with
+      ``to_status == "superseded"`` and ``request_id == R``.  This is the
+      exact signature emitted by ``supersede_profiles_by_ids`` (the dedup
+      soft-delete path).  It is distinct from reflection which emits
+      ``op="revise"``, so reflection events are never mis-counted as removals.
+
+    Groups are formed over the union of request_ids from both signals.
+    Request_id ``""`` is skipped — it would merge unrelated runs.
+    A row is emitted only when ``added or removed`` is non-empty (matching
+    legacy semantics: the legacy table was written only when
+    ``all_new_profiles or superseded_profiles``).
+
+    When a removed profile's tombstone has been physically purged (GDPR GC),
+    it is silently omitted from ``removed_profiles`` rather than crashing.
+
+    Args:
+        storage (ChangeLogReadStorage): Storage read surface to query (any
+            BaseStorage backend or the read-only ``RestStorageReader``).
+        limit (int): Maximum number of reconstructed entries to return.
+            Defaults to 100.
+
+    Returns:
+        ProfileChangeLogResponse: ``success=True`` with reconstructed rows
+            ordered most-recent first (by max event ``created_at`` in each
+            request_id group), capped at ``limit``.
+    """
+    if limit <= 0:
+        return ProfileChangeLogResponse(success=True, profile_change_logs=[])
+
+    all_events = storage.get_lineage_events(
+        entity_type="profile", org_id=storage.org_id
+    )
+
+    # Dedup soft-delete signature: status_change to_status=="superseded".
+    # Each such event records one profile removed in the dedup run ``request_id``.
+    # Distinct from reflection which emits op="revise" — so revise events are
+    # never counted as removals here.
+    removal_by_req: dict[str, list[str]] = defaultdict(list)
+    sort_key: dict[str, tuple[int, int]] = {}  # request_id -> (created_at, event_id)
+    for evt in all_events:
+        key = evt.request_id
+        if not key:
+            continue  # skip empty-string request_ids — never merge unrelated runs
+        cur = sort_key.get(key, (0, 0))
+        if (evt.created_at, evt.event_id) > cur:
+            sort_key[key] = (evt.created_at, evt.event_id)
+        if evt.op == "status_change" and evt.to_status == "superseded":
+            removal_by_req[key].append(evt.entity_id)
+
+    # Resolve the "added" side for every run in ONE bulk read, grouped by each
+    # profile's immutable generated_from_request_id. This replaces a read per
+    # candidate request_id, which fanned out over the org's whole dedup history
+    # before the limit slice below — a hot-path N+1 on network-backed storage now
+    # that the live endpoint serves this reconstruction.
+    added_by_req: dict[str, list] = defaultdict(list)
+    for profile in storage.get_all_generated_profiles():
+        added_by_req[profile.generated_from_request_id].append(profile)
+
+    # Candidate request_ids are the UNION of:
+    #   (a) lineage EVENT request_ids — runs that produced a dedup removal
+    #       (status_change/superseded event); and
+    #   (b) request_ids stamped on profile rows (the keys of added_by_req) —
+    #       discovers ADD-ONLY dedup runs (new profiles, nothing superseded) that
+    #       emit no lineage event. ``get_all_generated_profiles`` already excludes
+    #       the empty-string sentinel, so unrelated runs are never merged.
+    #
+    # This closes the reconstruction-completeness gap for add-only runs: the
+    # legacy `add_profile_change_log` fired whenever `all_new_profiles or
+    # superseded_profiles` was non-empty, so a run with only adds was still
+    # recorded. The (b) path mirrors that.
+    #
+    # For add-only runs (in set (b) but not (a)), no event timestamp exists.
+    # We derive their sort key from the max `last_modified_timestamp` of the
+    # profiles in that group — set at creation, giving a sensible most-recent-first
+    # ordering relative to event-timestamped runs. The secondary key is 0.
+    candidate_req_ids: set[str] = set(sort_key.keys()) | set(added_by_req.keys())
+
+    def _effective_sort_key(req_id: str) -> tuple[int, int]:
+        """Return (timestamp, event_id) for sorting; for add-only runs fall back to
+        the max last_modified_timestamp of the profiles in that group."""
+        if req_id in sort_key:
+            return sort_key[req_id]
+        profiles = added_by_req.get(req_id, [])
+        max_ts = max((p.last_modified_timestamp for p in profiles), default=0)
+        return (max_ts, 0)
+
+    sorted_keys = sorted(
+        candidate_req_ids,
+        key=_effective_sort_key,
+        reverse=True,
+    )[:limit]
+
+    logs: list[ProfileChangeLog] = []
+    for req_id in sorted_keys:
+        # added: profiles whose generated_from_request_id == req_id (any status,
+        # include tombstones — a profile added in R1 and tombstoned in R2 is still
+        # "added in R1").
+        added = added_by_req[req_id]
+
+        # removed: dedup-superseded profiles from this run's lineage events.
+        removed: list = []
+        for entity_id in removal_by_req.get(req_id, []):
+            profile = storage.get_profile_by_id(entity_id, include_tombstones=True)
+            if profile is not None:
+                removed.append(profile)
+            # Tombstone physically purged (GDPR GC) → silently omit; no crash.
+
+        if not added and not removed:
+            # No dedup activity for this request_id — skip to match legacy semantics.
+            continue
+
+        ts, _ = _effective_sort_key(req_id)
+        user_id = added[0].user_id if added else removed[0].user_id
+        logs.append(
+            ProfileChangeLog(
+                id=0,
+                user_id=user_id,
+                request_id=req_id,
+                created_at=ts,
+                added_profiles=added,
+                removed_profiles=removed,
+            )
+        )
+
+    return ProfileChangeLogResponse(success=True, profile_change_logs=logs)

package/plugin/vendor/reflexio/reflexio/lib/_reflection.py

@@ -41,7 +41,7 @@ class ReflectionMixin(ReflexioBase):
 
         # Local import keeps the heavy service module out of facade
         # cold-start when reflection is disabled.
-        from reflexio.server.services.reflection.reflection_service import (
+        from reflexio.server.services.reflection.service import (
             ReflectionService,
         )
 

package/plugin/vendor/reflexio/reflexio/lib/_search.py

@@ -13,6 +13,7 @@ from reflexio.models.api_schema.retriever_schema import (
 )
 from reflexio.server.llm.model_defaults import ModelRole, resolve_model_name
 from reflexio.server.site_var.site_var_manager import SiteVarManager
+from reflexio.server.tracing import profile_step
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -136,32 +137,40 @@ class SearchMixin(ReflexioBase):
         if isinstance(request, dict):
             request = UnifiedSearchRequest(**request)
 
-        config = self.request_context.configurator.get_config()
+        with profile_step(
+            "search.prepare",
+            enabled=bool(request.enable_reformulation),
+            has_conversation_history=bool(request.conversation_history),
+            search_mode=request.search_mode,
+        ):
+            config = self.request_context.configurator.get_config()
+            config_llm_config = config.llm_config if config else None
+
+            # Resolve pre_retrieval_model_name: config override -> site var -> auto-detect.
+            model_setting = SiteVarManager().get_site_var("llm_model_setting")
+            site_var = model_setting if isinstance(model_setting, dict) else {}
+            api_key_config = config.api_key_config if config else None
+
+            pre_retrieval_model_name = resolve_model_name(
+                ModelRole.PRE_RETRIEVAL,
+                site_var_value=site_var.get("pre_retrieval_model_name"),
+                config_override=config_llm_config.pre_retrieval_model_name
+                if config_llm_config
+                else None,
+                api_key_config=api_key_config,
+            )
+            storage = self._get_storage()
+            prompt_manager = self.request_context.prompt_manager
+            retrieval_floor = config.retrieval_floor if config else None
 
         from reflexio.server.services.unified_search_service import run_unified_search
 
-        config_llm_config = config.llm_config if config else None
-
-        # Resolve pre_retrieval_model_name: config override → site var → auto-detect
-        model_setting = SiteVarManager().get_site_var("llm_model_setting")
-        site_var = model_setting if isinstance(model_setting, dict) else {}
-        api_key_config = config.api_key_config if config else None
-
-        pre_retrieval_model_name = resolve_model_name(
-            ModelRole.PRE_RETRIEVAL,
-            site_var_value=site_var.get("pre_retrieval_model_name"),
-            config_override=config_llm_config.pre_retrieval_model_name
-            if config_llm_config
-            else None,
-            api_key_config=api_key_config,
-        )
-
         return run_unified_search(
             request=request,
             org_id=org_id,
-            storage=self._get_storage(),
+            storage=storage,
             llm_client=self.llm_client,
-            prompt_manager=self.request_context.prompt_manager,
+            prompt_manager=prompt_manager,
             pre_retrieval_model_name=pre_retrieval_model_name,
-            retrieval_floor=config.retrieval_floor if config else None,
+            retrieval_floor=retrieval_floor,
         )

package/plugin/vendor/reflexio/reflexio/lib/_user_playbook.py

@@ -24,7 +24,7 @@ from reflexio.models.api_schema.service_schemas import (
     UpgradeUserPlaybooksResponse,
 )
 from reflexio.models.config_schema import SearchOptions
-from reflexio.server.services.playbook.playbook_generation_service import (
+from reflexio.server.services.playbook.service import (
     PlaybookGenerationService,
 )
 from reflexio.server.tracing import profile_step
@@ -57,6 +57,7 @@ class UserPlaybookMixin(ReflexioBase):
                 playbook_name=request.playbook_name,
                 agent_version=request.agent_version,
                 status_filter=request.status_filter,
+                tags=request.tags,
             )
             return GetUserPlaybooksResponse(
                 success=True,

package/plugin/vendor/reflexio/reflexio/models/api_schema/domain/entities.py

@@ -118,6 +118,11 @@ __all__ = [
     "ShareLink",
     "AdminInvalidateCacheRequest",
     "AdminInvalidateCacheResponse",
+    "PlaybookRetrievalLogItem",
+    "PlaybookRetrievalLog",
+    "LineageEvent",
+    "LineageContext",
+    "RecordRef",
 ]
 
 # ===============================
@@ -179,11 +184,7 @@ class Request(BaseModel):
     """A user-issued request that begins or continues a session.
 
     A Request is the unit of work the agent reacts to. Multiple Requests
-    share a ``session_id`` to form a multi-turn session. The optional
-    ``metadata`` dict carries per-request key/value annotations stamped by
-    customer integration code — distinct from ``playbook_metadata`` (a
-    JSON-encoded string) used by ``Playbook``-family entities elsewhere in
-    this module.
+    share a ``session_id`` to form a multi-turn session.
 
     Attributes:
         request_id (str): Unique identifier for this request.
@@ -192,22 +193,10 @@ class Request(BaseModel):
             to the current UTC time.
         source (str): Free-form origin tag (integration name, etc.).
         agent_version (str): The agent version that handled this request.
-        session_id (str | None): Session this request belongs to, or None
-            if the request is not part of a multi-turn session.
-        metadata (dict[str, Any]): Free-form per-request annotations.
-            Always a dict — never None. Conventional keys:
-
-            - ``reflexio_retrieval_enabled`` (bool): F2 group-by signal;
-              customer integration code stamps this to indicate whether
-              Reflexio retrieval was active for the session. Read by the
-              ``/api/get_evaluation_overview`` aggregator from the FIRST
-              request of each session for sticky group assignment.
-
-            Distinct from ``playbook_metadata`` on ``Playbook``-family
-            entities (which is a JSON-encoded string, not a dict).
-            On-the-wire serialization assumes JSON-encodable values;
-            non-JSON values like ``datetime`` or ``set`` will fail at
-            the storage / API boundary.
+        session_id (str): Non-empty session this request belongs to.
+        evaluation_only (bool): Whether this request is stored for
+            session-level evaluation only and must be excluded from
+            profile/playbook learning windows.
     """
 
     request_id: str
@@ -215,8 +204,8 @@ class Request(BaseModel):
     created_at: int = Field(default_factory=lambda: int(datetime.now(UTC).timestamp()))
     source: str = ""
     agent_version: str = ""
-    session_id: str | None = None
-    metadata: dict[str, Any] = Field(default_factory=dict)
+    session_id: NonEmptyStr
+    evaluation_only: bool = False
 
 
 # information about the user profile generated from the user interaction
@@ -237,10 +226,14 @@ class UserProfile(BaseModel):
         None  # Retained provenance data column (merged on dedup); new profiles write None.
     )
     expanded_terms: str | None = None
+    tags: list[str] | None = None  # None = not yet tagged; [] = tagged, no match
+    source_interaction_ids: list[int] = Field(default_factory=list)
     embedding: EmbeddingVector = []
     source_span: str | None = None
     notes: str | None = None
     reader_angle: str | None = None
+    merged_into: str | None = None
+    superseded_by: str | None = None
 
 
 # user playbook for agents
@@ -261,10 +254,13 @@ class UserPlaybook(BaseModel):
     source: str | None = None  # source of the interaction that generated this playbook
     source_interaction_ids: list[int] = Field(default_factory=list)
     expanded_terms: str | None = None
+    tags: list[str] | None = None  # None = not yet tagged; [] = tagged, no match
     embedding: EmbeddingVector = []
     source_span: str | None = None
     notes: str | None = None
     reader_angle: str | None = None
+    merged_into: int | None = None
+    superseded_by: int | None = None
 
 
 class ProfileChangeLog(BaseModel):
@@ -274,7 +270,6 @@ class ProfileChangeLog(BaseModel):
     created_at: int = Field(default_factory=lambda: int(datetime.now(UTC).timestamp()))
     added_profiles: list[UserProfile]
     removed_profiles: list[UserProfile]
-    mentioned_profiles: list[UserProfile]
 
 
 class AgentPlaybook(BaseModel):
@@ -289,10 +284,13 @@ class AgentPlaybook(BaseModel):
     playbook_status: PlaybookStatus = PlaybookStatus.PENDING
     playbook_metadata: str = ""
     expanded_terms: str | None = None
+    tags: list[str] | None = None  # None = not yet tagged; [] = tagged, no match
     embedding: EmbeddingVector = []
     status: Status | None = (
         None  # used for tracking intermediate states during playbook aggregation. Status.ARCHIVED for playbooks during aggregation process, None for current playbooks
     )
+    merged_into: int | None = None
+    superseded_by: int | None = None
 
 
 class PlaybookOptimizationJob(BaseModel):
@@ -330,6 +328,7 @@ class PlaybookOptimizationCandidate(BaseModel):
     parent_candidate_ids: list[int] = Field(default_factory=list)
     aggregate_score: float | None = None
     is_winner: bool = False
+    metadata_json: str = "{}"
     created_at: int = Field(default_factory=lambda: int(datetime.now(UTC).timestamp()))
 
 
@@ -384,6 +383,7 @@ class AgentPlaybookSourceWindow(BaseModel):
 
 class AgentSuccessEvaluationResult(BaseModel):
     result_id: int = 0
+    user_id: str = ""
     agent_version: str
     session_id: str
     is_success: bool
@@ -398,6 +398,100 @@ class AgentSuccessEvaluationResult(BaseModel):
     embedding: EmbeddingVector = []
 
 
+class PlaybookRetrievalLogItem(BaseModel):
+    """One retrieved agent playbook plus the serve-time attribution snapshot."""
+
+    retrieval_log_item_id: int = 0
+    retrieval_log_id: int = 0
+    ordinal: int
+    agent_playbook_id: int
+    source_user_playbook_ids: list[int] = Field(default_factory=list)
+    source_interaction_ids_by_user_playbook_id: dict[str, list[int]] = Field(
+        default_factory=dict
+    )
+
+
+class PlaybookRetrievalLog(BaseModel):
+    """A retrieval-log header with ordered item rows.
+
+    Used by retrieval-capture consumers to correlate retrieval decisions with
+    downstream outcomes. ``retrieval_log_id`` is assigned by the storage layer;
+    ``shown_items`` stores ids and serve-time attribution snapshots only.
+    """
+
+    retrieval_log_id: int = 0
+    request_id: str
+    session_id: str
+    interaction_id: int | None = None
+    user_id: str
+    query: str | None = None
+    agent_version: str | None = None
+    shown_items: list[PlaybookRetrievalLogItem] = Field(default_factory=list)
+    created_at: int = 0
+
+
+class LineageEvent(BaseModel):
+    """Append-only, content-free provenance record. NEVER carries content/PII.
+
+    Attributes:
+        event_id (int): PK assigned by storage (0 = not yet persisted).
+        org_id (str): Owning org (tenant) — required for RLS / isolation.
+        entity_type (str): One of "profile" | "user_playbook" | "agent_playbook".
+        entity_id (str): The affected record's id, stringified (profile_id is str).
+        op (str): create|revise|merge|aggregate|archive|soft_delete|hard_delete|purge|status_change.
+        prov_relation (str): W3C PROV relation (see spec §14).
+        source_ids (list[str]): Records merged/superseded into entity_id.
+        actor (str): Who/what triggered it (consolidator|reflection|offline_optimizer|...).
+        request_id (str): Triggering request — part of the idempotency key.
+        reason (str): Free-text rationale (no PII).
+        created_at (int): Unix epoch seconds (0 = unset; storage stamps it).
+    """
+
+    event_id: int = 0
+    org_id: str
+    entity_type: str
+    entity_id: str
+    op: str
+    prov_relation: str = ""
+    source_ids: list[str] = []
+    actor: str = ""
+    request_id: str = ""
+    reason: str = ""
+    created_at: int = 0
+    from_status: str | None = None
+    to_status: str | None = None
+    status_namespace: str | None = None
+
+
+class LineageContext(BaseModel):
+    """Caller-supplied intent the storage layer can't infer.
+
+    Required for merge/supersede/aggregate; optional for create/revise/archive.
+    """
+
+    op_kind: str
+    actor: str = ""
+    source_ids: list[str] = []
+    reason: str = ""
+    request_id: str | None = None
+
+
+class RecordRef(BaseModel):
+    """Result of resolve_current — the live survivor's id and whether its body was purged.
+
+    Attributes:
+        id: Primary key of the live survivor record.
+        is_purged: True when the survivor's content body has been blanked by
+            ``purge_content`` (GDPR/erasure).  Any consumer that dereferences the
+            resolved record's content MUST treat ``is_purged=True`` as "erased —
+            skip or treat as absent."  Reading blank content as if it were valid
+            is a silent data-quality bug.
+    """
+
+    id: str
+    is_purged: bool = False
+
+
 class ShareLink(BaseModel):
     """A shareable public link that maps a token to a resource within an org.
 
@@ -563,26 +657,21 @@ class PublishUserInteractionRequest(BaseModel):
     agent_version: str = (
         ""  # this is used for aggregating interactions for generating agent playbooks
     )
-    session_id: str | None = None  # used for grouping requests together
+    session_id: NonEmptyStr  # used for grouping requests together
     skip_aggregation: bool = (
         False  # when True, extract profiles/playbooks but skip aggregation
     )
     force_extraction: bool = False  # when True, bypass all extraction gates (stride_size, cheap pre-filter, LLM should_run) and always run extractors
+    evaluation_only: bool = False  # when True, store for evaluation and permanently exclude from profile/playbook extraction
     override_learning_stall: bool = False  # when True, run extraction even if a provider auth/billing stall is recorded
-    metadata: dict[str, Any] = Field(default_factory=dict)
-    """Per-request annotations stamped by customer integration code.
-
-    Mirrors ``Request.metadata`` — the publish path copies this dict
-    onto the ``Request`` row it creates so the eval pipeline (and the
-    F2 sticky-group aggregator in particular) can read it back from
-    the first request of each session.
 
-    Conventional keys:
-        - ``reflexio_retrieval_enabled`` (bool): F2 group assignment signal.
-
-    Defaults to ``{}`` (never None) for backward compatibility — existing
-    callers that don't pass ``metadata`` keep working unchanged.
-    """
+    @model_validator(mode="after")
+    def validate_evaluation_only(self) -> Self:
+        if self.evaluation_only and self.force_extraction:
+            raise ValueError("evaluation_only cannot be combined with force_extraction")
+        if self.evaluation_only and not self.session_id:
+            raise ValueError("evaluation_only publishes require session_id")
+        return self
 
 
 # publish user interaction response

package/plugin/vendor/reflexio/reflexio/models/api_schema/domain/enums.py

@@ -42,6 +42,10 @@ class Status(str, Enum):  # noqa: UP042 - CURRENT=None is not compatible with St
     ARCHIVE_IN_PROGRESS = (
         "archive_in_progress"  # temporary status during downgrade operation
     )
+    MERGED = "merged"  # tombstone: consolidated into a survivor (merged_into set)
+    SUPERSEDED = (
+        "superseded"  # tombstone: replaced by a new version (superseded_by set)
+    )
 
 
 class OperationStatus(StrEnum):