promoted_item.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/registry/source/promoted_item.py
 
# OCT-LINT: disable=tests_exist reason="Covered by oc_chat/tests/registry/source/test_canonical.py"
"""
The promoted-item (``phases/<code>/<sub_id>.md``) source model (Plan 142 P1.4).
 
Purpose
-------
Close the P1.1 model gap (umbrella §12.1): a promoted sub-item is an ``m_phase``
item, but ``RoadmapItem.track_kind`` excludes ``m_phase`` (§3.3), so P1.3's
loader cannot model it. ``PromotedItem`` reuses the P1.1 strict types + base so a
promoted record parses, validates, canonicalises, hashes, and builds into one
``roadmap_items_v3`` row with NO ``roadmap_phases`` row (AC §8.39). ``track_kind``
is implied ``m_phase`` by the path and is set by the builder, not authored.
 
Home & layering (Plan 142i [OP-5])
----------------------------------
The model lives under ``source/`` (not ``regenerate/``) so the ``source`` layer
(``canonical``/``hashing``) can resolve it for full three-projection parity
WITHOUT importing ``regenerate`` (``source`` must not depend on ``regenerate``).
``regenerate/promoted.py`` is retained as a re-export shim for the pre-existing
importers outside this plan's file scope (``tools/seed_142_ingest.py``).
 
Responsibilities
----------------
- Define the promoted-item frontmatter schema (item fields minus ``track_kind``/
  ``era``) with the shared lifecycle cross-field rule.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - model lifecycle
    L3 - field validation
    L4 - lifecycle cross-field checks
 
Contracts
---------
- ``frozen``/``extra=forbid``/``strict`` (inherited from ``SourceRecord``).
- ``track_kind`` is NOT a field — the builder sets it to ``m_phase``.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- option_c_registry_contracts (P1.1 base + strict types + lifecycle helper)
- pydantic (Field and model_validator - list and map defaults and the lifecycle cross-field check)
"""
from __future__ import annotations
 
from typing import Optional
 
from pydantic import Field, model_validator
 
from oc_diagnostics import _dbg
 
from option_c_registry_contracts import (
    DependsOn,
    EntityId,
    ExtensionsMap,
    Line300,
    Priority,
    RequiredLine,
    SourceRecord,
    Status,
    VersionId,
    check_item_lifecycle,
)
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
 
class PromotedItem(SourceRecord):
    """A promoted sub-item authored as ``phases/<phase_code>/<sub_id>.md`` (§5.6).
 
    Field order mirrors ``RoadmapItem`` minus ``track_kind`` (implied ``m_phase``
    from the path) and ``era`` (phases carry the era). The builder sets
    ``track_kind='m_phase'``, ``phase_id`` from the parent ``phases/<code>.md``,
    and ``parent_item_id`` to the parent ``m_phase`` item.
    """
 
    id: EntityId
    title: RequiredLine
    purpose: Line300
    status: Status
    priority: Optional[Priority] = None
    depends_on: DependsOn = Field(default_factory=list)
    track_codes: list[EntityId] = Field(default_factory=list)
    order: int
    target_version: Optional[VersionId] = None
    introduced_in_version: Optional[VersionId] = None
    closed_in_version: Optional[VersionId] = None
    successor: Optional[EntityId] = None
    superseded_by: Optional[EntityId] = None
    extensions: ExtensionsMap = Field(default_factory=dict)
 
    @model_validator(mode="after")
    def _validate_lifecycle(self) -> "PromotedItem":
        return check_item_lifecycle(self)