trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/history/apps.py

@@ -0,0 +1,12 @@
+"""App config for history."""
+
+from django.apps import AppConfig
+
+
+class HistoryConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "trueppm_api.apps.history"
+
+    def ready(self) -> None:
+        # Register the post_save receiver that fires history_record_created.
+        import trueppm_api.apps.history.signals  # noqa: F401

trueppm_api/apps/history/changelog.py

@@ -0,0 +1,359 @@
+"""Unified project changelog aggregator (ADR-0201, #371).
+
+A read-only aggregator that merges the project-scoped ``django-simple-history``
+tables into one newest-first "what changed" stream. No new model, no data
+migration — every event already has a durable home in a ``Historical*`` table.
+
+Why a Python k-way merge and not a SQL ``UNION``
+------------------------------------------------
+The nine source tables have heterogeneous columns, so a single ``UNION`` would
+force a lowest-common-denominator projection and is brittle against schema
+drift. Instead each source is fetched ``ORDER BY history_date DESC, history_id
+DESC`` with ``LIMIT page_size + 1`` (a bounded scan — never a query per row),
+and the bounded lists are merge-sorted in Python on the global total-order key.
+
+Why a ``(history_date, table_rank, history_id)`` keyset and not ``until``
+------------------------------------------------------------------------
+``history_date`` is a timestamp and can collide **across** tables; ``history_id``
+is only unique **within** a table. A timestamp-only cursor (the ``until`` cursor
+of the per-object history and board feeds) is therefore lossy across a cross-table
+tie. The strict total order is the triple ``(history_date DESC, table_rank ASC,
+history_id DESC)``: ``table_rank`` (a fixed integer per source) disambiguates two
+rows in *different* tables sharing an exact ``history_date``, and ``history_id``
+disambiguates two rows in the *same* table. This partitions the global stream
+into pages with no gap and no duplicate — the same guarantee
+``sync/pagination.py`` documents for ``(server_version, id)``.
+
+Permission model (ADR-0201): every source's live GET is ``IsProjectMember``
+(Viewer+), so membership is a sufficient row-inclusion gate — there is no
+per-user sub-project ACL on any source (TimeEntry and the Retrospective models
+carry per-user / team_visibility gates but have **no** ``HistoricalRecords``, so
+they cannot appear here). Field redaction is the shared ``history.diff_policy``
+(one vocabulary for every diff surface, #3435 — it drops ``blocked_reason`` per
+ADR-0124 and the CPM outputs at compute time); ``history_user`` is gated to
+Owner/Admin via the view's ``hide_user`` context, and the ``user=`` filter is
+honored only for those callers.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from django.db.models import Q
+from rest_framework.exceptions import ValidationError
+
+if TYPE_CHECKING:
+    from django.db.models import QuerySet
+
+# django-simple-history ``history_type`` → the changelog's change-type vocabulary.
+_HISTORY_TYPE_TO_CHANGE: dict[str, str] = {"+": "created", "~": "updated", "-": "deleted"}
+_CHANGE_TO_HISTORY_TYPE: dict[str, str] = {v: k for k, v in _HISTORY_TYPE_TO_CHANGE.items()}
+
+CHANGE_TYPES: frozenset[str] = frozenset(_CHANGE_TO_HISTORY_TYPE)
+
+DEFAULT_PAGE_SIZE = 50
+MAX_PAGE_SIZE = 100
+
+
+@dataclass(frozen=True)
+class ChangelogSource:
+    """One historical table wired into the unified changelog.
+
+    ``rank`` is the source's fixed position in the total order — it is encoded in
+    the cursor and MUST stay stable (reordering the source list would invalidate
+    in-flight opaque cursors, which is acceptable for a short-lived pagination
+    token but must be a deliberate change).
+    """
+
+    rank: int
+    object_type: str
+    label_field: str | None  # attribute on the historical row to use as the display label
+    label_fallback: str  # used when label_field is None or the value is empty
+    project_filter: str  # ORM lookup that scopes the historical rows to a project
+
+
+def _sources() -> list[ChangelogSource]:
+    """The ordered project-scoped historical sources (ADR-0201).
+
+    Program and CeremonyTemplate are deliberately excluded (program-scoped, not
+    project-scoped); Workspace is a singleton. TimeEntry and the Retrospective
+    models are excluded because they have no ``HistoricalRecords`` table at all.
+    """
+    return [
+        ChangelogSource(0, "task", "name", "Task", "project_id"),
+        ChangelogSource(1, "sprint", "name", "Sprint", "project_id"),
+        ChangelogSource(2, "risk", "title", "Risk", "project_id"),
+        ChangelogSource(3, "dependency", None, "Dependency", "predecessor__project_id"),
+        # HistoricalProject's ``pk`` is ``history_id``; the original project's PK
+        # lives in the ``id`` column, so the project's own history is scoped by id.
+        ChangelogSource(4, "project", "name", "Project", "id"),
+        ChangelogSource(5, "task_recurrence", None, "Recurrence rule", "task__project_id"),
+        ChangelogSource(6, "guardrail_policy", None, "Guardrail policy", "project_id"),
+        ChangelogSource(7, "signal_privacy_policy", None, "Signal privacy policy", "project_id"),
+        ChangelogSource(8, "decisions_policy", None, "Decisions policy", "project_id"),
+    ]
+
+
+def object_type_choices() -> list[str]:
+    return [s.object_type for s in _sources()]
+
+
+def _historical_model(object_type: str) -> Any:
+    """Return the ``Historical*`` model class for a source's live model."""
+    from trueppm_api.apps.projects.models import (
+        Dependency,
+        Project,
+        ProjectDecisionsPolicy,
+        ProjectGuardrailPolicy,
+        ProjectSignalPrivacyPolicy,
+        Risk,
+        Sprint,
+        Task,
+        TaskRecurrenceRule,
+    )
+
+    live = {
+        "task": Task,
+        "sprint": Sprint,
+        "risk": Risk,
+        "dependency": Dependency,
+        "project": Project,
+        "task_recurrence": TaskRecurrenceRule,
+        "guardrail_policy": ProjectGuardrailPolicy,
+        "signal_privacy_policy": ProjectSignalPrivacyPolicy,
+        "decisions_policy": ProjectDecisionsPolicy,
+    }[object_type]
+    # ``history`` is the django-simple-history manager, added dynamically to the
+    # model class — not visible to the type checker on the VersionedModel base.
+    return live.history.model  # type: ignore[attr-defined]
+
+
+@dataclass(frozen=True)
+class ChangelogCursor:
+    """Position in the ``(history_date, table_rank, history_id)`` total order.
+
+    Encoded as an opaque, URL-safe base64 JSON token, mirroring
+    :class:`~trueppm_api.apps.sync.pagination.SyncCursor`. The token is
+    client-controlled, so every field is validated on decode — a tampered or
+    truncated token yields a 400 rather than an unhandled 500.
+    """
+
+    history_date: datetime
+    rank: int
+    history_id: int
+
+    def encode(self) -> str:
+        raw = json.dumps(
+            {"d": self.history_date.isoformat(), "r": self.rank, "id": self.history_id},
+            separators=(",", ":"),
+        )
+        return base64.urlsafe_b64encode(raw.encode()).decode()
+
+    @classmethod
+    def decode(cls, token: str) -> ChangelogCursor:
+        from django.utils.dateparse import parse_datetime
+
+        try:
+            raw = base64.urlsafe_b64decode(token.encode())
+            data = json.loads(raw)
+            parsed = parse_datetime(str(data["d"]))
+            if parsed is None:
+                raise ValueError("bad date")
+            rank = int(data["r"])
+            history_id = int(data["id"])
+        except (binascii.Error, ValueError, KeyError, TypeError, UnicodeDecodeError) as err:
+            raise ValidationError({"cursor": "Malformed pagination cursor."}) from err
+        if rank < 0:
+            raise ValidationError({"cursor": "Malformed pagination cursor."})
+        return cls(history_date=parsed, rank=rank, history_id=history_id)
+
+
+def _cursor_filter(source: ChangelogSource, cursor: ChangelogCursor) -> Q:
+    """The keyset predicate that resumes strictly *after* ``cursor`` for one source.
+
+    "After" = older in the newest-first total order. With the source's fixed
+    ``rank`` known as a constant, the cross-table tie-break collapses to a simple
+    per-source predicate (see the module docstring for the derivation):
+
+    * rank > cursor.rank  → every same-``history_date`` row is older  → ``<= cd``
+    * rank == cursor.rank → tie-break within the table on ``history_id``
+    * rank < cursor.rank  → same-``history_date`` rows here are newer  → already sent
+    """
+    cd = cursor.history_date
+    if source.rank > cursor.rank:
+        return Q(history_date__lte=cd)
+    if source.rank == cursor.rank:
+        return Q(history_date__lt=cd) | Q(history_date=cd, history_id__lt=cursor.history_id)
+    return Q(history_date__lt=cd)
+
+
+def _label_for(source: ChangelogSource, row: Any) -> str:
+    if source.label_field is not None:
+        value = getattr(row, source.label_field, None)
+        if value:
+            return str(value)
+    return source.label_fallback
+
+
+def _object_id_for(source: ChangelogSource, row: Any) -> str:
+    """The id used for click-through. Policies point at their project (settings);
+    every other source points at the object's own row."""
+    if source.object_type in {"guardrail_policy", "signal_privacy_policy", "decisions_policy"}:
+        return str(row.project_id)
+    return str(row.id)
+
+
+def _fetch_source_rows(
+    source: ChangelogSource,
+    project: Any,
+    *,
+    since: datetime | None,
+    history_types: set[str] | None,
+    user_id: Any,
+    cursor: ChangelogCursor | None,
+    page_size: int,
+) -> list[Any]:
+    """Fetch one source's bounded, newest-first row window (``LIMIT page_size + 1``).
+
+    Each of the ``since`` / ``history_types`` / ``user_id`` / ``cursor`` filters is
+    applied only when set, so an unconstrained call scans just the project-scoped
+    rows. ``select_related("history_user")`` keeps the per-row ``history_user``
+    render from fanning out into a query per row.
+    """
+    model = _historical_model(source.object_type)
+    qs: QuerySet[Any] = model.objects.filter(**{source.project_filter: project.pk})
+    if since is not None:
+        qs = qs.filter(history_date__gte=since)
+    if history_types is not None:
+        qs = qs.filter(history_type__in=history_types)
+    if user_id is not None:
+        qs = qs.filter(history_user_id=user_id)
+    if cursor is not None:
+        qs = qs.filter(_cursor_filter(source, cursor))
+    return list(
+        qs.select_related("history_user").order_by("-history_date", "-history_id")[: page_size + 1]
+    )
+
+
+def _source_entries(
+    source: ChangelogSource,
+    rows: list[Any],
+    diff_fn: Any,
+) -> list[tuple[tuple[datetime, int, int], dict[str, Any]]]:
+    """Pair one source's rows with their diffs and key each surviving entry.
+
+    Diffs are computed within this source's batch (same model), so the
+    ``history_id``-keyed dict never collides across tables. Rows whose entire diff
+    is redacted (:func:`_row_to_entry` returns ``None``) are dropped.
+    """
+    diffs = diff_fn(rows, all_records=rows)
+    collected: list[tuple[tuple[datetime, int, int], dict[str, Any]]] = []
+    for row in rows:
+        entry = _row_to_entry(source, row, diffs)
+        if entry is not None:
+            collected.append(((row.history_date, source.rank, row.history_id), entry))
+    return collected
+
+
+def build_project_changelog(
+    project: Any,
+    *,
+    diff_fn: Any,
+    cursor: ChangelogCursor | None = None,
+    since: datetime | None = None,
+    object_types: set[str] | None = None,
+    change_types: set[str] | None = None,
+    user_id: Any = None,
+    page_size: int = DEFAULT_PAGE_SIZE,
+) -> tuple[list[dict[str, Any]], ChangelogCursor | None]:
+    """Build one newest-first page of the unified changelog (ADR-0201).
+
+    Args:
+        project: the project whose history is aggregated.
+        diff_fn: ``history.views._compute_diffs`` bound with ``object_scoped=False``
+            — injected to avoid an import cycle. It applies the shared
+            ``history.diff_policy`` (CPM outputs, sync internals, and
+            ``blocked_reason`` per ADR-0124 are never compared; noise is hidden
+            unless it is a record's only change) and keys rows by field name.
+        cursor: keyset position; ``None`` starts at the newest row.
+        since: inclusive lower bound on ``history_date``.
+        object_types: restrict to these source ``object_type`` keys (default all).
+        change_types: restrict to these change types (``created``/``updated``/``deleted``).
+        user_id: restrict to a single ``history_user`` (honored by the caller only
+            for Owner/Admin — see the view).
+        page_size: rows per page (clamped to ``[1, MAX_PAGE_SIZE]``).
+
+    Returns:
+        ``(entries, next_cursor)``. ``next_cursor`` is ``None`` when the stream is
+        exhausted. Each entry is a plain dict — see :func:`_row_to_entry`.
+    """
+    page_size = max(1, min(int(page_size), MAX_PAGE_SIZE))
+    wanted_types = {s.strip() for s in object_types} if object_types else None
+    history_types: set[str] | None = (
+        {_CHANGE_TO_HISTORY_TYPE[c] for c in change_types} if change_types else None
+    )
+
+    entries: list[tuple[tuple[datetime, int, int], dict[str, Any]]] = []
+    for source in _sources():
+        if wanted_types is not None and source.object_type not in wanted_types:
+            continue
+        rows = _fetch_source_rows(
+            source,
+            project,
+            since=since,
+            history_types=history_types,
+            user_id=user_id,
+            cursor=cursor,
+            page_size=page_size,
+        )
+        if rows:
+            entries.extend(_source_entries(source, rows, diff_fn))
+
+    # Newest-first total order: history_date DESC, rank ASC, history_id DESC.
+    entries.sort(key=lambda item: (item[0][0], -item[0][1], item[0][2]), reverse=True)
+
+    has_more = len(entries) > page_size
+    page = entries[:page_size]
+    next_cursor: ChangelogCursor | None = None
+    if has_more and page:
+        key = page[-1][0]
+        next_cursor = ChangelogCursor(history_date=key[0], rank=key[1], history_id=key[2])
+
+    return [entry for _, entry in page], next_cursor
+
+
+def _row_to_entry(
+    source: ChangelogSource,
+    row: Any,
+    diffs: dict[int, list[dict[str, Any]]],
+) -> dict[str, Any] | None:
+    """Turn one historical row into a changelog entry, or ``None`` to drop it.
+
+    An ``updated`` row whose entire diff is excluded fields (a pure CPM/sync bump)
+    carries no team-readable signal and is dropped — matching the per-object
+    history views. ``created`` / ``deleted`` rows are always kept (the change type
+    is itself the signal) and carry an empty ``changes`` list to keep the feed
+    scannable.
+    """
+    change_type = _HISTORY_TYPE_TO_CHANGE.get(row.history_type, "updated")
+    changes: list[dict[str, Any]] = []
+    if change_type == "updated":
+        changes = diffs.get(row.history_id, [])
+        if not changes:
+            return None
+
+    return {
+        "id": f"{source.object_type}:{row.history_id}",
+        "object_type": source.object_type,
+        "object_id": _object_id_for(source, row),
+        "object_label": _label_for(source, row),
+        "change_type": change_type,
+        "history_date": row.history_date,
+        "history_user": row.history_user,
+        "changes": changes,
+    }

trueppm_api/apps/history/diff_policy.py

@@ -0,0 +1,177 @@
+"""Which tracked fields a history diff shows, hides, and promotes — decided once.
+
+Task field changes reach users through **three** renderers, and until #3435 each
+carried its own exclusion list:
+
+* the task drawer's Activity tab — ``apps/projects/views.py`` (``TaskHistoryView``),
+  Task-only, FK values resolved to labels;
+* the project **Activity** page and the per-object history routes —
+  ``apps/history/views.py::_compute_diffs``, every project-scoped historical model,
+  raw values;
+* the board activity feed — ``apps/projects/board_activity.py``, a curated
+  **allow-list** (``_BOARD_DIFF_FIELDS``) rather than allow-by-exclusion.
+
+The first two disagreed on what to hide, and only the first had a label map, so the
+project Activity page rendered raw column names for every change the drawer rendered
+as prose. Decision (#3435): the two allow-by-exclusion pipelines **converge** on this
+module. They stay separate functions because they differ in what they *resolve* (the
+drawer batch-resolves FK ids to names; the generic pipeline carries the ids), but
+*which* fields are compared, hidden, and promoted is decided here, and both emit the
+model **field name** (``assignee``), never the column (``assignee_id``), so one client
+label map (``activityFormat.ts::fieldLabel``) serves every surface. The board feed
+keeps its allow-list — a board reader wants six fields, not "everything but the
+noise" — and is pinned against the privacy set by test rather than by sharing code.
+
+The sets are grouped by the *reason* a field is hidden, because the reasons carry
+different obligations. A noise exclusion may be promoted back when it is a record's
+only change (#3306); an access-control exclusion never may, and conflating the two
+turns a labelling cleanup into a disclosure bug.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import TypeVar
+
+T = TypeVar("T")
+
+# django-simple-history's own columns. Present on every ``Historical*`` row and never
+# a user change; the drawer never sees them because it iterates the live model's
+# fields, but the generic pipeline iterates the historical model's and must drop them.
+HISTORY_DIFF_META_COLUMNS: frozenset[str] = frozenset(
+    {"history_id", "history_date", "history_change_reason", "history_user", "history_type"}
+)
+
+# Engine outputs and sync counters. ``HistoricalTask`` no longer carries any of these
+# (``_HISTORY_EXCLUDED_TASK`` strips them at tracking time), but the generic pipeline
+# diffs eight other models whose tracking lists differ, so they are named here as well:
+# a model that does track them must still never show a recalculation as an edit.
+HISTORY_DIFF_ENGINE_AND_SYNC: frozenset[str] = frozenset(
+    {
+        "early_start",
+        "early_finish",
+        "late_start",
+        "late_finish",
+        "total_float",
+        "free_float",
+        "is_critical",
+        "scheduled_start",
+        "server_version",
+        "sync_seq",
+        "deleted_version",
+        "deleted_at",
+    }
+)
+
+# Low-signal bookkeeping hidden from every diff surface (ADR-0096 Part 1, #874). These
+# are *display* decisions: the historical model tracks the column, a reader simply
+# gains nothing from a row about it. Members of this set — and only this set — are
+# eligible for promotion when they are a record's only change.
+HISTORY_DIFF_NOISE: frozenset[str] = frozenset(
+    {
+        "short_id",  # immutable, system-assigned identifier
+        "status_changed_at",  # derived bookkeeping timestamp
+        "blocked_since",  # derived bookkeeping timestamp
+        "sprint_pending",  # transient ADR-0102 scope-injection flag
+        # sprint-backlog reorder bookkeeping: drag-reorder rewrites the team's
+        # within-sprint sequence on every affected sibling, so surfacing it would
+        # flood the timeline with integer noise — mirrors the other rank/bookkeeping
+        # exclusions (#1885). Deliberate ordering signals (priority_rank) stay visible.
+        "sprint_rank",
+        # Promoted back into the diff when it is a record's ONLY change — see
+        # ``HISTORY_DIFF_PROMOTED_WHEN_ALONE`` below.
+        "parent_governance_inherited",  # internal inheritance bookkeeping
+        "recurrence_occurrence_date",  # system-set during recurrence expansion
+        "recurrence_rule",  # FK to the rule object; recurrence shown via is_recurring
+    }
+)
+
+# The one deliberate per-surface difference. A soft delete is a ``~`` row whose only
+# tracked change is ``is_deleted`` (``VersionedModel.soft_delete`` saves the flag; a
+# hard ``-`` row exists only for the purge task). On a surface scoped to ONE object —
+# the task drawer — that flag is not a field change worth a row: a deleted task has no
+# drawer to read it in, and a restore re-opens the same drawer to the same task. On the
+# cross-object project Activity page the same row is the ONLY record that the delete
+# happened at all, so hiding it there would make every soft delete invisible — the
+# #3306 "write with no record" shape, for the most consequential write there is.
+HISTORY_DIFF_OBJECT_SCOPED_EXCLUDED: frozenset[str] = frozenset({"is_deleted"})
+
+# Excluded for an ACCESS-CONTROL reason, not a noise one, and therefore never
+# promotable and never a per-surface judgment call.
+#
+# ``blocked_reason`` is contributor voice (ADR-0124, #1135 — the "Morgan surveillance
+# boundary"): ``TaskSerializer`` read-gates it to the assignee and @-mentioned users
+# via ``can_read_blocker_reason()``, while every history endpoint is Viewer+ for every
+# project member. ``HistoricalTask`` deliberately still tracks it (it is NOT in
+# ``_HISTORY_EXCLUDED_TASK``), so this exclusion is the only thing keeping the reason
+# — and every past reason — off a team-readable feed. The structured blocker signal
+# (``blocker_type`` / ``blocked_since`` / ``blocked_by`` / ``blocking_task``) is
+# team-shareable and stays in the diff.
+HISTORY_DIFF_PRIVACY_GATED: frozenset[str] = frozenset({"blocked_reason"})
+
+# Noise exclusions surfaced anyway when they are the ONLY thing a record changed (#3306).
+#
+# ``parent_governance_inherited`` is genuinely bookkeeping alongside a governance
+# change: every ordinary governance write moves the two together, so surfacing both
+# would double the diff rows on the highest-frequency case and turn the summary verb
+# from "changed governance" into "updated 2 fields". That call stands.
+#
+# But the bit can also move *alone*, and then the exclusion plus the empty-diff drop
+# erase the write entirely. The concrete case is a classification cascade onto a root
+# already at the requested ``governance_class`` with ``parent_governance_inherited=True``:
+# declaring the class on the root sets the bit to False, which writes the row, bumps
+# ``server_version``, records an undo-ledger row and broadcasts ``tasks_bulk_mutated``
+# — and left the task's Activity tab showing nothing at all.
+#
+# Narrowing the drop rule instead (rendering every empty-diff ``~`` record) was
+# rejected: that is the bare "Updated" pill issue 874 removed, and it would resurrect
+# it for every ``sprint_rank`` reorder and every transient ``sprint_pending`` flip.
+# Promotion keeps the exclusion's intent — no noise beside a change the user can
+# already read — while guaranteeing that no write is invisible.
+HISTORY_DIFF_PROMOTED_WHEN_ALONE: frozenset[str] = frozenset({"parent_governance_inherited"})
+
+# Everything a diff never compares, on any surface. Privacy-gated names are excluded
+# here at *compute* time, not at render time, so no pipeline ever holds the value in a
+# structure a later refactor could accidentally serialize.
+HISTORY_DIFF_HARD_EXCLUDED: frozenset[str] = (
+    HISTORY_DIFF_META_COLUMNS | HISTORY_DIFF_ENGINE_AND_SYNC | HISTORY_DIFF_PRIVACY_GATED
+)
+
+# What the drawer's routine tuple excludes — the name the drawer has always used.
+HISTORY_DIFF_DISPLAY_EXCLUDED: frozenset[str] = (
+    HISTORY_DIFF_HARD_EXCLUDED | HISTORY_DIFF_NOISE | HISTORY_DIFF_OBJECT_SCOPED_EXCLUDED
+)
+
+
+def is_compared(name: str, *, object_scoped: bool) -> bool:
+    """Whether a pipeline should diff the field at all.
+
+    Hard exclusions never are. Noise is compared only if it is promotable, so a
+    promoted field can be rendered when it stands alone; the rest of the noise is
+    skipped before comparison rather than filtered afterwards, which is what keeps
+    the drawer's FK-id collection from resolving ids nobody will see.
+    """
+    if name in HISTORY_DIFF_HARD_EXCLUDED:
+        return False
+    if object_scoped and name in HISTORY_DIFF_OBJECT_SCOPED_EXCLUDED:
+        return False
+    if name in HISTORY_DIFF_NOISE:
+        return name in HISTORY_DIFF_PROMOTED_WHEN_ALONE
+    return True
+
+
+def visible_changes(changes: Iterable[T], field_name: Callable[[T], str]) -> list[T]:
+    """Apply the promote-when-alone rule to one record's compared changes.
+
+    Routine changes render as they are. A change in
+    :data:`HISTORY_DIFF_PROMOTED_WHEN_ALONE` renders only when the record has no
+    routine change to show — it rescues an otherwise invisible write without adding
+    a row beside a change the reader can already see. Generic over the change shape
+    so the drawer's ``(field, old, new)`` tuples and the generic pipeline's dicts run
+    the same rule; ``field_name`` extracts the model field name from either.
+    """
+    items = list(changes)
+    routine = [c for c in items if field_name(c) not in HISTORY_DIFF_PROMOTED_WHEN_ALONE]
+    if routine:
+        return routine
+    return [c for c in items if field_name(c) in HISTORY_DIFF_PROMOTED_WHEN_ALONE]

trueppm_api/apps/history/serializers.py

@@ -0,0 +1,104 @@
+"""Serializers for the object change history API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rest_framework import serializers
+
+
+class HistoryUserSerializer(serializers.Serializer[Any]):
+    """Minimal user representation in a history record."""
+
+    id = serializers.UUIDField()
+    display_name = serializers.SerializerMethodField()
+
+    def get_display_name(self, obj: Any) -> str:
+        full = f"{obj.first_name} {obj.last_name}".strip()
+        return full or obj.username
+
+
+class FieldDiffSerializer(serializers.Serializer[Any]):
+    """A single field change within a history record.
+
+    ``field`` is the model **field name** (``assignee``, ``sprint``), never the
+    database column (``assignee_id``) — the same key the per-task history endpoint
+    emits, so one client label map serves every history surface.
+    """
+
+    field = serializers.CharField()
+    old = serializers.JSONField(allow_null=True)
+    new = serializers.JSONField(allow_null=True)
+
+
+class HistoryRecordSerializer(serializers.Serializer[Any]):
+    """One change record: when it happened, what changed, and (for Admins) by whom.
+
+    ``history_user`` is null for callers below Admin, so a client must treat it as
+    optional rather than assume the actor is always present.
+    """
+
+    # This docstring is published as the ``HistoryRecord`` component description in
+    # docs/api/openapi.json, so it is integrator-facing copy — keep it about the
+    # contract, not the mechanism. The mechanism: the view sets ``hide_user=True``
+    # on the serializer context for callers below ``Role.ADMIN`` (redaction, not
+    # omission — the key is always present), and computes ``diff`` via a
+    # ``prev_record`` comparison injected through context so this serializer needs
+    # no ORM access.
+
+    id = serializers.SerializerMethodField()
+    history_date = serializers.DateTimeField()
+    history_type = serializers.CharField()
+    history_change_reason = serializers.CharField(allow_null=True)
+    history_user = serializers.SerializerMethodField()
+    diff = serializers.SerializerMethodField()
+
+    def get_id(self, obj: Any) -> str:
+        return str(obj.history_id)
+
+    def get_history_user(self, obj: Any) -> dict[str, Any] | None:
+        if self.context.get("hide_user"):
+            return None
+        user = obj.history_user
+        if user is None:
+            return None
+        return HistoryUserSerializer(user).data
+
+    def get_diff(self, obj: Any) -> list[dict[str, Any]]:
+        diffs: dict[int, list[dict[str, Any]]] = self.context.get("diffs", {})
+        return diffs.get(obj.history_id, [])
+
+
+class ChangelogEntrySerializer(serializers.Serializer[Any]):
+    """One row in the unified project changelog (ADR-0201).
+
+    The instance is a plain dict from ``changelog.build_project_changelog`` — the
+    aggregator already merged, ordered, and diffed across the historical tables,
+    so the serializer only renders. ``user`` is exposed only to Owner/Admin
+    callers (``hide_user=True`` in context returns null), reusing the same gate as
+    :class:`HistoryRecordSerializer`.
+    """
+
+    id = serializers.CharField()
+    object_type = serializers.CharField()
+    object_id = serializers.CharField()
+    object_label = serializers.CharField()
+    change_type = serializers.ChoiceField(choices=["created", "updated", "deleted"])
+    history_date = serializers.DateTimeField()
+    user = serializers.SerializerMethodField()
+    changes = FieldDiffSerializer(many=True)
+
+    def get_user(self, obj: dict[str, Any]) -> dict[str, Any] | None:
+        if self.context.get("hide_user"):
+            return None
+        user = obj.get("history_user")
+        if user is None:
+            return None
+        return HistoryUserSerializer(user).data
+
+
+class ChangelogResponseSerializer(serializers.Serializer[Any]):
+    """Response envelope for the unified project changelog (ADR-0201)."""
+
+    results = ChangelogEntrySerializer(many=True)
+    next_cursor = serializers.CharField(allow_null=True)