trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/projects/seed/exporter.py

@@ -0,0 +1,1644 @@
+"""Export a live program to the canonical JSON seed format (ADR-0109, issue #616).
+
+``export_program`` is the inverse of the importer: it walks a program and emits
+a seed document that re-validates and re-imports. The exporter is deterministic
+— arrays are emitted in a stable order and UUIDs are replaced with derived
+slugs — so the round-trip ``export(import(export(p)))`` is identical to
+``export(import(p))`` (the #616 guarantee). It strips every derived field
+(server_version, CPM outputs, short_id) by simply never emitting them.
+
+By default it emits **v1** (``schema_version: "1.0"``, final-state) so the #616
+byte-identical round-trip is preserved unchanged. Passing ``with_events=True``
+emits **v2** (ADR-0114 §7 / #1109): dates are rewritten as ``anchor``-relative
+offsets and an ordered ``events`` timeline is reconstructed from the history
+tables so a shared program re-imports as the *life* it lived, not a snapshot.
+The v2 path is a self-consistent fixpoint — ``export→import→export`` is
+byte-identical — because every reconstructed event replays to a state that
+reconstructs to the same event, and the importer's synthesizer is naturally
+suppressed (every task with history already carries authored status events).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from trueppm_api.apps.access.models import ProgramMembership, ProjectMembership, Role
+from trueppm_api.apps.projects.models import (
+    AcceptanceCriterion,
+    BacklogItem,
+    Baseline,
+    BaselineTask,
+    BoardColumnConfig,
+    CeremonyTemplate,
+    CommentAcknowledgement,
+    CommentReaction,
+    Dependency,
+    Label,
+    Program,
+    Project,
+    RetroActionItem,
+    Risk,
+    RiskComment,
+    ScopeChangeStatus,
+    Sprint,
+    SprintRetro,
+    SprintScopeChange,
+    Task,
+    TaskComment,
+    TaskLabel,
+    TaskNote,
+    TaskRecurrenceRule,
+    TaskRelation,
+)
+from trueppm_api.apps.resources.models import (
+    ProjectResource,
+    Resource,
+    ResourceSkill,
+    TaskResource,
+    TaskSkillRequirement,
+)
+
+_UTC = ZoneInfo("UTC")
+
+# Sentinel distinguishing "no HTTP caller at all" (a management command, run by
+# an operator with direct DB/shell access — already a higher trust tier than any
+# API role) from "an HTTP caller whose user object is falsy" (an async export
+# job's ``requested_by`` can go ``NULL`` via ``on_delete=SET_NULL`` if the
+# requesting account is deleted between enqueue and build). Only the sentinel is
+# treated as trusted; a literal ``None`` from a real request lineage is not
+# (#3627) — see ``_Exporter._resolve_email_visibility``.
+_NO_HTTP_CALLER = object()
+
+
+@dataclass(order=True)
+class _RawEvent:
+    """A reconstructed event before serialization, sortable into replay order.
+
+    Sort key is ``(when, target, action, seq)``: chronological, with a fully
+    deterministic tiebreak so re-export is byte-identical. ``data`` (actor +
+    action-specific keys) is excluded from the ordering.
+    """
+
+    when: datetime
+    target: str
+    action: str
+    seq: int
+    data: dict[str, Any] = field(compare=False, default_factory=dict)
+
+
+# Signature of the ``emit`` callback the reconstruction helpers are handed.
+_Emit = Callable[[datetime, str, str, dict[str, Any]], None]
+
+# seedDate / seedTimestamp cap a relative offset at 4 digits (~27 years); a date
+# further from the anchor than this falls back to an ISO literal (still a valid
+# seedDate/seedTimestamp) so a very long-lived program still exports cleanly.
+_MAX_REL_OFFSET_DAYS = 9999
+
+_ROLE_NAME: dict[int, str] = {
+    Role.VIEWER: "VIEWER",
+    Role.MEMBER: "MEMBER",
+    Role.SCHEDULER: "SCHEDULER",
+    Role.ADMIN: "ADMIN",
+    Role.OWNER: "OWNER",
+}
+
+
+#: Event actions that only exist from schema 2.1 (#3603).
+_V21_EVENT_ACTIONS = frozenset({"task.note", "task.react", "task.ack", "time.log"})
+
+
+#: Weekday names in bitmask order — the authoring shape of a recurrence rule (#3498).
+_WEEKDAY_BITS = (
+    ("mon", 1),
+    ("tue", 2),
+    ("wed", 4),
+    ("thu", 8),
+    ("fri", 16),
+    ("sat", 32),
+    ("sun", 64),
+)
+
+#: ``Proficiency`` integer -> the seed's authoring name (#3498).
+_PROFICIENCY_NAME = {1: "beginner", 2: "intermediate", 3: "expert"}
+
+#: Task keys that only exist from schema 2.1.
+_V21_TASK_KEYS = ("acceptance_criteria", "is_subtask", "recurrence", "skill_requirements")
+
+
+def _uses_v21(doc: dict[str, Any]) -> bool:
+    """Whether an exported document carries any construct introduced in 2.1."""
+    program = doc.get("program", {})
+    if program.get("backlog_items") or program.get("ceremonies"):
+        return True
+    if any(resource.get("skills") for resource in doc.get("resources", [])):
+        return True
+    for project in doc.get("projects", []):
+        if project.get("team"):
+            return True
+        for task in project.get("tasks", []):
+            if task.get("type") == "tech_debt" or any(task.get(k) for k in _V21_TASK_KEYS):
+                return True
+    return any(
+        event.get("action") in _V21_EVENT_ACTIONS or "slug" in event or "reply_to" in event
+        for event in doc.get("events", [])
+    )
+
+
+def dump_seed(payload: dict[str, Any]) -> str:
+    """Canonical serialization: sorted keys, 2-space indent, trailing newline.
+
+    Centralised so the management command, the REST endpoint, and the round-trip
+    test all emit byte-identical output.
+    """
+    return json.dumps(payload, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+
+
+# The seed schema caps every ``slug`` at 40 chars (so a program slug still fits
+# ``Program.code``). Slugs are derived from free-text titles/names, so the
+# exporter must enforce the cap itself — a risk titled longer than ~40 chars
+# would otherwise emit a slug the importer's own schema rejects (#2006).
+_MAX_SLUG_LEN = 40
+
+
+def _slugify(text: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    # Truncate to the schema cap, then re-strip so a cut mid-separator can't
+    # leave a trailing "-" that violates the kebab-case pattern.
+    return slug[:_MAX_SLUG_LEN].strip("-") or "x"
+
+
+class _SlugAllocator:
+    """Assigns unique kebab slugs deterministically (suffix on collision)."""
+
+    def __init__(self) -> None:
+        self._used: set[str] = set()
+
+    def take(self, text: str) -> str:
+        base = _slugify(text)
+        candidate = base
+        i = 2
+        while candidate in self._used:
+            suffix = f"-{i}"
+            # Keep the disambiguated slug within the 40-char cap by trimming the
+            # base to make room for the suffix (and re-stripping any dangling "-").
+            candidate = base[: _MAX_SLUG_LEN - len(suffix)].strip("-") + suffix
+            i += 1
+        self._used.add(candidate)
+        return candidate
+
+
+def _put(target: dict[str, Any], key: str, value: Any) -> None:
+    """Emit a key only when meaningful — skips None and empty strings."""
+    if value is None or value == "":
+        return
+    target[key] = value
+
+
+def export_program(
+    program: Program,
+    *,
+    with_events: bool = False,
+    requesting_user: Any = _NO_HTTP_CALLER,
+) -> dict[str, Any]:
+    """Serialize ``program`` to a canonical seed document (a ``dict``).
+
+    Args:
+        program: the program to export.
+        with_events: when ``False`` (default) emit a v1 final-state document,
+            preserving the #616 byte-identical round-trip. When ``True`` emit a
+            v2 document (ADR-0114 §7 / #1109) with ``anchor``-relative dates and
+            a reconstructed ``events`` timeline, so the export re-imports through
+            the replay engine as the program's dated life rather than a snapshot.
+        requesting_user: the account the export is being produced *for* (#3627).
+            ``Resource.email`` and account ``email`` are withheld unless this
+            user holds workspace Admin+ — see
+            ``_Exporter._resolve_email_visibility``. Omit entirely for a caller
+            with no HTTP request context (e.g. the management command, run by an
+            operator with shell/DB access already); that is treated as trusted
+            and email is included unredacted. A literal ``None`` (an async
+            export job whose ``requested_by`` went ``NULL``) is deliberately
+            *not* trusted and redacts.
+    """
+    projects = list(
+        Project.objects.filter(program=program, is_deleted=False).order_by("code", "name", "pk")
+    )
+    return _Exporter(
+        program=program,
+        projects=projects,
+        with_events=with_events,
+        requesting_user=requesting_user,
+    ).build()
+
+
+def export_project(project: Project, *, requesting_user: Any = _NO_HTTP_CALLER) -> dict[str, Any]:
+    """Serialize a single ``project`` to a canonical seed document (#967).
+
+    The canonical schema requires a top-level ``program`` block (ADR-0109) but
+    ``Project.program`` is nullable (ADR-0070 — standalone projects are
+    first-class), so the project is emitted inside a minimal program *synthesized
+    from the project itself* (slug/name/methodology). This is uniform whether or
+    not the live project belongs to a program, and because the synthesized slug
+    is project-derived rather than the parent program's ``code``, re-importing a
+    project export creates a fresh program instead of clobbering the live parent
+    program's subtree. The #616 round-trip guarantee still holds. See the #967
+    addendum in ADR-0109.
+
+    Args:
+        project: the project to export.
+        requesting_user: see :func:`export_program` — controls whether
+            ``Resource.email`` / account ``email`` are withheld (#3627).
+    """
+    return _Exporter(
+        program=None,
+        projects=[project],
+        synthetic_program=project,
+        requesting_user=requesting_user,
+    ).build()
+
+
+class _Exporter:
+    def __init__(
+        self,
+        *,
+        program: Program | None,
+        projects: list[Project],
+        synthetic_program: Project | None = None,
+        with_events: bool = False,
+        requesting_user: Any = _NO_HTTP_CALLER,
+    ) -> None:
+        # ``program`` is the live parent program for a program export, or None
+        # for a single-project export (#967), in which case ``synthetic_program``
+        # (the project) sources the synthesized program-wrapper block.
+        self.program = program
+        self.synthetic_program = synthetic_program
+        self.projects = projects
+        # #3627: whether this export includes real Resource/account email.
+        # ``_resources_block``/``_account_entry`` never reach ``ResourceSerializer``
+        # (the #891 harvest control), so the exporter enforces the same invariant
+        # itself rather than inheriting a serializer it does not use. The
+        # endpoint-level gate (IsProjectAdmin/IsProgramAdmin) stays project- or
+        # program-scoped and self-grantable by design (creating a project makes
+        # you its Owner) — that is what makes the field a workspace-wide harvest
+        # once any project Admin can pull the whole catalog into an export. So
+        # email is workspace-Admin-only *content*, independent of who can reach
+        # the export action at all. See docs/adr/0034 (#3569 amendment) and #3627.
+        self._email_visible = self._resolve_email_visibility(requesting_user)
+        # v2 event-timeline export (#1109). When on, dates become anchor-relative
+        # and an ``events`` array is reconstructed from the history tables.
+        self.with_events = with_events
+        # The reference date for relative offsets (v2 only). The earliest project
+        # start is a deterministic, always-present choice (projects require a
+        # start_date), and it round-trips: re-import resolves the same absolute
+        # dates, so re-export recomputes the same anchor.
+        self.anchor: date = min(
+            (p.start_date for p in projects if p.start_date is not None), default=date.today()
+        )
+        # Account identity, captured once accounts are built, so an event actor
+        # always resolves to a real account slug (never a dangling ref).
+        self._account_user_pks: set[Any] = set()
+        self._fallback_actor_slug: str = ""
+        self.project_slug = _SlugAllocator()
+        self.account_slug = _SlugAllocator()
+        self.calendar_slug = _SlugAllocator()
+        self.resource_slug = _SlugAllocator()
+        # v2.1 comment slugs (#3493), minted only for a comment something refers to
+        # (a reply, reaction or acknowledgement). Document-wide, so two tasks'
+        # comments can never collide after the 40-char truncation.
+        self.comment_slug = _SlugAllocator()
+
+        # pk -> slug maps, built once so cross-references resolve consistently.
+        self.user_slugs: dict[Any, str] = {}
+        self.calendar_slugs: dict[Any, str] = {}
+        self.resource_slugs: dict[Any, str] = {}
+        self.project_slugs: dict[Any, str] = {}
+        # task pk -> (project_slug, wbs_path) for global task refs.
+        self.task_ref: dict[Any, tuple[str, str]] = {}
+        # sprint pk -> slug, scoped per project.
+        self.sprint_slugs: dict[Any, str] = {}
+        # Risk slugs are allocated per project inside ``_risk_blocks``; recorded
+        # here so ``risk.note`` events can target them. Projects are serialized
+        # before events, so this is populated by the time the timeline is built.
+        self.risk_slugs: dict[Any, str] = {}
+        # task pk -> [label slug, …], populated per project in ``_project_block``
+        # (ADR-0400 labels folded into the seed, #1958). Label slugs are
+        # project-scoped, matching the slug-based (no-UUID) seed contract.
+        self.task_label_slugs: dict[Any, list[str]] = {}
+        # memoized — _all_resources is consulted by three blocks.
+        self._resources_cache: list[Resource] | None = None
+
+    @staticmethod
+    def _resolve_email_visibility(requesting_user: Any) -> bool:
+        """True when ``requesting_user`` may see real ``email`` values (#3627).
+
+        The ``_NO_HTTP_CALLER`` sentinel (the parameter default) means the caller
+        has no HTTP request context at all — the management command, run by an
+        operator with direct DB/shell access, already a higher trust tier than
+        any API role — and is treated as trusted. Every other value, including a
+        literal ``None``, goes through the real check: an HTTP-driven export
+        passes ``request.user`` (always a real, authenticated user), while an
+        async export-job builder passes ``job.requested_by``, which can be
+        ``None`` if the requesting account was deleted between enqueue and
+        build — and a gone account must not fall back to trusted. Email is
+        visible only at workspace Admin+ (``WorkspaceRole.ADMIN``), matching the
+        invariant the #3569 amendment records for the other three email-bearing
+        routes: the endpoint stays reachable at project/program Admin+
+        (self-grantable by creating a project), so the field itself — not the
+        endpoint — has to be the workspace-wide gate.
+        """
+        if requesting_user is _NO_HTTP_CALLER:
+            return True
+        # Imported locally (not at module scope) to match the existing
+        # cross-app-import convention in this package (see attachment_policy.py,
+        # calendar_settings.py, etc.) and avoid a load-order dependency on the
+        # workspace app from the projects app.
+        from trueppm_api.apps.workspace.models import WorkspaceRole
+        from trueppm_api.apps.workspace.permissions import workspace_role_for_user
+
+        role = workspace_role_for_user(requesting_user)
+        return role is not None and role >= WorkspaceRole.ADMIN
+
+    # --- public ------------------------------------------------------------
+
+    def build(self) -> dict[str, Any]:
+        for project in self.projects:
+            self.project_slugs[project.pk] = self.project_slug.take(project.code or project.name)
+
+        # Pre-pass: index every task and sprint across ALL projects before
+        # emitting any block, so cross-project dependency and risk refs resolve
+        # regardless of project ordering.
+        self._project_tasks: dict[Any, list[Task]] = {}
+        self._project_sprints: dict[Any, list[Sprint]] = {}
+        for project in self.projects:
+            self._index_project(project)
+
+        doc: dict[str, Any] = {"schema_version": "2.0" if self.with_events else "1.0"}
+        if self.with_events:
+            # An explicit anchor pins the offsets so re-import resolves the exact
+            # same absolute dates (round-trip determinism), rather than drifting
+            # to the next import day.
+            doc["anchor"] = self.anchor.isoformat()
+        doc["program"] = self._program_block()
+        accounts = self._accounts_block()
+        # Capture account identity before events so an event actor resolves to a
+        # real account slug and the deterministic fallback (OWNER) is known.
+        self._capture_account_identity(accounts)
+        calendars = self._calendars_block()
+        resources = self._resources_block()
+        if accounts:
+            doc["accounts"] = accounts
+        if calendars:
+            doc["calendars"] = calendars
+        if resources:
+            doc["resources"] = resources
+        doc["projects"] = [self._project_block(p) for p in self.projects]
+        if self.with_events:
+            self._put_program_v21(doc["program"])
+            events = self._events_block()
+            if events:
+                doc["events"] = events
+            # Declare 2.1 only when the document uses a 2.1 construct, so a program
+            # with none still exports as 2.0 and stays importable by a 2.0 build.
+            if _uses_v21(doc):
+                doc["schema_version"] = "2.1"
+        return doc
+
+    def _put_program_v21(self, block: dict[str, Any]) -> None:
+        """Program backlog and ceremonies (v2.1, #3491/#3603). v2 export only.
+
+        Built after account identity is captured, so ``pulled_by``/``created_by``
+        can be restricted to users that already hold an account slug. Agent actions
+        and share links are deliberately never exported: one is audit evidence and
+        the other a credential, and every non-sample import rejects both.
+        """
+        if self.program is None:
+            return
+        items = sorted(
+            BacklogItem.objects.filter(program=self.program, is_deleted=False),
+            key=lambda i: (i.priority_rank is None, i.priority_rank or 0, i.created_at, i.title),
+        )
+        allocator = _SlugAllocator()
+        backlog: list[dict[str, Any]] = []
+        for item in items:
+            entry: dict[str, Any] = {"slug": allocator.take(item.title), "title": item.title}
+            _put(entry, "description", item.description)
+            entry["item_type"] = item.item_type
+            entry["status"] = item.status
+            if item.tags:
+                entry["tags"] = list(item.tags)
+            _put(entry, "priority_rank", item.priority_rank)
+            _put(entry, "story_points", item.story_points)
+            ref = self.task_ref.get(item.pulled_task_id) if item.pulled_task_id else None
+            if ref is not None:
+                entry["pulled_to"] = f"{ref[0]}:{ref[1]}"
+                if item.pulled_at is not None:
+                    entry["pulled_at"] = self._rel_ts(item.pulled_at)
+                if item.pulled_by_id in self._account_user_pks:
+                    entry["pulled_by"] = self._user_slug(item.pulled_by)
+            elif item.status == "pulled":
+                # The task it became is gone or unexportable; a "pulled" item that
+                # names no task would fail validation, so it re-imports as archived.
+                entry["status"] = "archived"
+            if item.created_by_id in self._account_user_pks:
+                entry["created_by"] = self._user_slug(item.created_by)
+            entry["created_at"] = self._rel_ts(item.created_at)
+            backlog.append(entry)
+        if backlog:
+            block["backlog_items"] = backlog
+
+        ceremonies: list[dict[str, Any]] = []
+        for ceremony in CeremonyTemplate.objects.filter(
+            program=self.program, is_deleted=False
+        ).order_by("name", "pk"):
+            entry = {"name": ceremony.name, "cadence_type": ceremony.cadence_type}
+            _put(entry, "cadence_day", ceremony.cadence_day)
+            if ceremony.cadence_time is not None:
+                entry["cadence_time"] = ceremony.cadence_time.strftime("%H:%M")
+            entry["duration_minutes"] = ceremony.duration_minutes
+            _put(entry, "owner_role", ceremony.owner_role)
+            if not ceremony.enabled:
+                entry["enabled"] = False
+            ceremonies.append(entry)
+        if ceremonies:
+            block["ceremonies"] = ceremonies
+
+    # --- top-level blocks --------------------------------------------------
+
+    def _program_block(self) -> dict[str, Any]:
+        if self.program is None:
+            # Single-project export (#967): synthesize a minimal program wrapper
+            # from the project so the seed satisfies the schema's required
+            # ``program`` block while staying decoupled from any live parent
+            # program (re-import won't clobber it). The slug is slugified to keep
+            # it schema-valid (kebab-case) since Project.code is free-form.
+            proj = self.synthetic_program
+            assert proj is not None  # always set when self.program is None
+            block: dict[str, Any] = {
+                "slug": _slugify(proj.code or proj.name),
+                "name": proj.name,
+                "methodology": proj.methodology,
+            }
+            _put(block, "description", proj.description)
+            return block
+        block = {
+            "slug": self.program.code or self.project_slug.take(self.program.name),
+            "name": self.program.name,
+            "methodology": self.program.methodology,
+        }
+        _put(block, "description", self.program.description)
+        _put(block, "color", self.program.color)
+        if self.program.lead_id is not None:
+            block["lead"] = self._user_slug(self.program.lead)
+        return block
+
+    def _accounts_block(self) -> list[dict[str, Any]]:
+        # Every user referenced anywhere in the export needs an account so it
+        # re-imports. Membership roles come from ProgramMembership. A single-
+        # project export (#967) has no parent program, so the roster is empty and
+        # no account carries a program-level role — but the project's own live
+        # members are still emitted (#3457), alongside the users it references
+        # through task assignments, resource accounts and risk ownership.
+        roles, users = self._collect_account_users()
+        accounts = [self._account_entry(uid, user, roles) for uid, user in users.items()]
+        return sorted(accounts, key=lambda a: a["slug"])
+
+    def _collect_account_users(self) -> tuple[dict[Any, int], dict[Any, Any]]:
+        """Gather every user referenced by the export, in a stable order.
+
+        Insertion order (program roster, then task assignees, risk owners,
+        resource accounts, then live project members) fixes slug-allocation
+        order, so the roster must be walked in exactly this sequence for the
+        round-trip to stay byte-stable.
+        """
+        users: dict[Any, Any] = {}
+        roles = self._program_roster(users)
+        # Project leads (#3098) come before task assignees so a lead who is
+        # referenced nowhere else still gets an account entry — without one the
+        # exported ``project.lead`` slug would dangle and the document would not
+        # re-import. Inserted here rather than appended because insertion order
+        # fixes slug allocation, and the round-trip is asserted byte-identical.
+        for proj in self.projects:
+            if proj.lead_id is not None:
+                users[proj.lead_id] = proj.lead
+        for task in self._all_tasks():
+            if task.assignee_id is not None:
+                users[task.assignee_id] = task.assignee
+        for risk in Risk.objects.filter(project__in=self.projects).select_related("owner"):
+            if risk.owner_id is not None:
+                users[risk.owner_id] = risk.owner
+        for res in self._all_resources():
+            if res.user_id is not None:
+                users[res.user_id] = res.user
+        self._add_project_member_users(users)
+        return roles, users
+
+    def _add_project_member_users(self, users: dict[Any, Any]) -> None:
+        """Add every live project member not already present, walking the projects in order."""
+        # Live *project* members, last (#3457). Project and program membership are
+        # independent grants (ADR-0070 §RBAC), so a user revoked from the program
+        # can still hold a live ProjectMembership. Now that the roster no longer
+        # carries revoked members, such a user would reach _member_blocks with no
+        # slug and their project grant would be silently dropped from the
+        # document — access lost rather than access leaked, but lost all the same.
+        # Appended after every existing source rather than inserted beside the
+        # roster: this can only add users that would otherwise carry no slug at
+        # all, so no already-allocated slug moves and the byte-stable fixpoint is
+        # untouched. One query, then regrouped and walked in ``self.projects``
+        # order and by username, because insertion order fixes slug allocation
+        # and a database's natural row order does not.
+        #
+        # Ordered by ``user__username`` and NOT by ``user_id``: the slug is
+        # derived from the username and two usernames can slugify to the same
+        # base, in which case ``_SlugAllocator`` suffixes them ``-2``/``-3`` in
+        # *call* order. ``username`` round-trips verbatim through the document;
+        # the user PK does not — a re-import mints new users in ``accounts[]``
+        # order — so ordering on the id would let a colliding pair swap suffixes
+        # on re-export and break the byte-identical fixpoint (#616).
+        members_by_project: dict[Any, list[Any]] = {}
+        for pm in (
+            ProjectMembership.objects.filter(project__in=self.projects, is_deleted=False)
+            .select_related("user")
+            .order_by("user__username")
+        ):
+            members_by_project.setdefault(pm.project_id, []).append(pm)
+        for proj in self.projects:
+            for pm in members_by_project.get(proj.pk, ()):
+                users.setdefault(pm.user_id, pm.user)
+
+    def _program_roster(self, users: dict[Any, Any]) -> dict[Any, int]:
+        """Seed ``users`` with the program lead + members; return their roles.
+
+        A single-project export (#967) has no parent program, so the roster is
+        empty and no program-level roles apply.
+
+        Both ``ProgramMembership`` reads floor on ``is_deleted=False`` (#3457),
+        matching the project-side twin in ``_member_blocks``. A revoked membership
+        is a tombstone that still owns the ``(program, user)`` slot, and the
+        importer's grant deliberately clears that tombstone (``is_deleted: False``)
+        so a seed grant always confers access (#3410) — so any revoked member left
+        in the roster is handed their role back on import. The floor has to be
+        here, on the export side: a revoked member must not be in the document at
+        all.
+
+        The ``lead`` read below is **deliberately not floored**, and must not be
+        "fixed" for symmetry. ``Program.lead`` is a display FK distinct from the
+        OWNER membership, ``_program_block`` emits its slug unconditionally, and
+        ``validate_seed`` requires ``$.program.lead`` to resolve to an
+        ``accounts[]`` entry — so dropping a lead whose *membership* was revoked
+        would emit a document that fails the exporter's own validator. It confers
+        nothing either way: the account is emitted without a ``role`` key, and the
+        importer's grant skips a roleless account.
+        """
+        if self.program is None:
+            return {}
+        roles = {
+            m.user_id: m.role
+            for m in ProgramMembership.objects.filter(program=self.program, is_deleted=False)
+        }
+        if self.program.lead_id is not None:
+            users[self.program.lead_id] = self.program.lead
+        for m in ProgramMembership.objects.filter(
+            program=self.program, is_deleted=False
+        ).select_related("user"):
+            users[m.user_id] = m.user
+        return roles
+
+    def _account_entry(self, uid: Any, user: Any, roles: dict[Any, int]) -> dict[str, Any]:
+        block: dict[str, Any] = {"slug": self._user_slug(user), "username": user.get_username()}
+        # #3627: withheld for a non-workspace-Admin caller. Safe for the
+        # generic re-import path — accounts are matched by ``username``, never
+        # ``email`` (see importer._resolve_accounts) — so dropping the key here
+        # never breaks round-trip. ``_put`` already drops falsy values, so
+        # passing "" simply omits the key, matching the #3599 precedent of
+        # dropping rather than nulling a withheld email.
+        _put(block, "email", getattr(user, "email", "") if self._email_visible else "")
+        display = f"{user.first_name} {user.last_name}".strip()
+        _put(block, "display_name", display)
+        if uid in roles:
+            block["role"] = _ROLE_NAME[roles[uid]]
+        return block
+
+    def _calendars_block(self) -> list[dict[str, Any]]:
+        calendars: dict[Any, Any] = {}
+        for project in self.projects:
+            if project.calendar is not None:
+                calendars[project.calendar.pk] = project.calendar
+        for res in self._all_resources():
+            if res.calendar is not None:
+                calendars[res.calendar.pk] = res.calendar
+        blocks = []
+        for cal in calendars.values():
+            slug = self._calendar_slug(cal)
+            block: dict[str, Any] = {"slug": slug, "name": cal.name}
+            _put(block, "working_days", cal.working_days)
+            _put(block, "hours_per_day", cal.hours_per_day)
+            _put(block, "timezone", cal.timezone)
+            # Non-working ranges (holidays / PTO, #376). Exported as ISO literals so
+            # the export→import→export fixpoint is byte-stable; ordered for
+            # determinism. Forecast-snapshot history is deliberately NOT exported —
+            # like SprintBurnSnapshot it is derived observational history, not
+            # authored structure, so a round-trip drops it (its parameters are not
+            # recoverable from the materialized rows).
+            exceptions = [
+                {
+                    "exc_start": exc.exc_start.isoformat(),
+                    "exc_end": exc.exc_end.isoformat(),
+                    **({"description": exc.description} if exc.description else {}),
+                }
+                for exc in cal.exceptions.all().order_by("exc_start", "exc_end")
+            ]
+            if exceptions:
+                block["exceptions"] = exceptions
+            blocks.append(block)
+        return sorted(blocks, key=lambda c: c["slug"])
+
+    def _resources_block(self) -> list[dict[str, Any]]:
+        blocks = []
+        for res in self._all_resources():
+            slug = self._resource_slug(res)
+            block: dict[str, Any] = {"slug": slug, "name": res.name}
+            # #3627: withheld for a non-workspace-Admin caller. Safe for the
+            # generic re-import path — ``_resolve_resources`` never matches an
+            # existing catalog Resource by email on that path (it always creates
+            # a fresh row, #1004) — only the server-curated sample loader does,
+            # and that path is never fed a redacted export.
+            _put(block, "email", res.email if self._email_visible else "")
+            _put(block, "job_role", res.job_role)
+            _put(block, "max_units", float(res.max_units))
+            if res.calendar_id is not None:
+                block["calendar"] = self._calendar_slug(res.calendar)
+            if res.user_id is not None:
+                block["account"] = self._user_slug(res.user)
+            if self.with_events:
+                # v2.1 (#3498). Ordered on the normalized name so the export is stable.
+                skills = [
+                    {
+                        "name": rs.skill.name,
+                        "proficiency": _PROFICIENCY_NAME[rs.proficiency],
+                        **({"category": rs.skill.category} if rs.skill.category else {}),
+                    }
+                    for rs in ResourceSkill.objects.filter(resource=res, is_deleted=False)
+                    .select_related("skill")
+                    .order_by("skill__normalized_name", "pk")
+                ]
+                if skills:
+                    block["skills"] = skills
+            blocks.append(block)
+        return sorted(blocks, key=lambda r: r["slug"])
+
+    # --- per-project -------------------------------------------------------
+
+    def _index_project(self, project: Project) -> None:
+        """Populate global task/sprint slug maps for one project (pre-pass)."""
+        pslug = self.project_slugs[project.pk]
+        # A task with no wbs_path (e.g. a promoted retro-action backlog item) has
+        # no WBS identity and cannot be represented in a seed — the schema requires
+        # a wbs_path. Exclude it from both tasks[] and the ref map so refs to it are
+        # dropped rather than emitting an invalid "None" path.
+        tasks = list(
+            Task.objects.filter(project=project, is_deleted=False, wbs_path__isnull=False).order_by(
+                "wbs_path", "pk"
+            )
+        )
+        self._project_tasks[project.pk] = tasks
+        for task in tasks:
+            self.task_ref[task.pk] = (pslug, str(task.wbs_path))
+
+        sprints = list(
+            Sprint.objects.filter(project=project, is_deleted=False).order_by("start_date", "pk")
+        )
+        self._project_sprints[project.pk] = sprints
+        sprint_alloc = _SlugAllocator()
+        for sprint in sprints:
+            self.sprint_slugs[sprint.pk] = sprint_alloc.take(sprint.name)
+
+    def _project_block(self, project: Project) -> dict[str, Any]:
+        pslug = self.project_slugs[project.pk]
+        tasks = self._project_tasks[project.pk]
+        sprints = self._project_sprints[project.pk]
+
+        block: dict[str, Any] = {
+            "slug": pslug,
+            "name": project.name,
+            "methodology": project.methodology,
+            "start_date": self._date_str(project.start_date) if project.start_date else None,
+        }
+        self._put_project_scalars(block, project)
+
+        board_columns = self._board_column_blocks(project)
+        member_blocks = self._member_blocks(project)
+
+        # Project-scoped labels (ADR-0400, #1089) folded into the seed (#1958) so a
+        # re-seed round-trips board-card labels. Slugs are allocated per project
+        # (deterministic, kebab-cased) and referenced by ``labels`` on each task
+        # block; label identity in the seed is slug-based (no UUID), matching the
+        # existing seed contract (UUID-preserving round-trip is 0.5, #1959).
+        label_blocks = self._label_blocks(project)
+
+        sprint_blocks = [self._sprint_block(s) for s in sprints]
+        task_blocks = [self._task_block(t) for t in tasks]
+        dep_blocks = self._dependency_blocks(project, pslug)
+        baseline_blocks = self._baseline_blocks(project, pslug)
+        risk_blocks = self._risk_blocks(project, pslug)
+        # Insertion order IS the emitted key order, and the export contract is a
+        # byte-identical export -> import -> export fixpoint (see
+        # ``_member_blocks``), so this sequence is not cosmetic. Note it differs
+        # from the computation order above: the blocks are built sprints-first
+        # because slug allocation is order-sensitive, but emitted tasks-first.
+        for key, value in (
+            ("board_columns", board_columns),
+            ("members", member_blocks),
+            ("labels", label_blocks),
+            ("tasks", task_blocks),
+            ("dependencies", dep_blocks),
+            ("sprints", sprint_blocks),
+            ("baselines", baseline_blocks),
+            ("risks", risk_blocks),
+            ("team", self._team_block(project) if self.with_events else {}),
+        ):
+            if value:
+                block[key] = value
+        return block
+
+    def _team_block(self, project: Project) -> dict[str, Any]:
+        """The default team's name and SM/PO facets (v2.1, #3498). v2 export only.
+
+        Only facet holders are listed: membership itself re-derives from the
+        project's members on import, so listing everyone would restate it. The
+        default name is omitted, so a project nobody configured exports as before.
+        """
+        from trueppm_api.apps.teams.models import Team, TeamMembership
+
+        team = Team.objects.filter(project=project, is_default=True, is_deleted=False).first()
+        if team is None:
+            return {}
+        members: list[dict[str, Any]] = []
+        for membership in (
+            TeamMembership.objects.filter(team=team, is_deleted=False)
+            .exclude(is_scrum_master=False, is_product_owner=False)
+            .select_related("user")
+        ):
+            if membership.user_id not in self._account_user_pks:
+                continue
+            entry: dict[str, Any] = {"account": self._user_slug(membership.user)}
+            if membership.is_scrum_master:
+                entry["scrum_master"] = True
+            if membership.is_product_owner:
+                entry["product_owner"] = True
+            members.append(entry)
+        if not members and team.name == "Default Team":
+            return {}
+        block: dict[str, Any] = {"members": sorted(members, key=lambda e: e["account"])}
+        if team.name != "Default Team":
+            block["name"] = team.name
+        return block
+
+    def _put_project_scalars(self, block: dict[str, Any], project: Project) -> None:
+        """Add the project's optional scalar fields, each omitted at its default.
+
+        A field equal to its default is left out rather than emitted, so a seed
+        stays readable and a later change of default does not silently pin every
+        exported project to the old value.
+        """
+        _put(block, "description", project.description)
+        _put(block, "code", project.code)
+        if project.lead_id is not None:
+            block["lead"] = self._user_slug(project.lead)
+        if project.calendar_id is not None:
+            block["calendar"] = self._calendar_slug(project.calendar)
+        if project.default_view and project.default_view != "SCHEDULE":
+            block["default_view"] = project.default_view
+        if project.estimation_mode and project.estimation_mode != "open":
+            block["estimation_mode"] = project.estimation_mode
+        if project.health and project.health != "AUTO":
+            block["health"] = project.health
+
+    def _member_blocks(self, project: Project) -> list[dict[str, Any]]:
+        """Emit this project's memberships so project-scoped roles round-trip (#3092).
+
+        Emitted unconditionally rather than only when the roles differ from the
+        program roster. A "same as the program" shortcut would make the export
+        lossy the moment a role was later changed to match by coincidence, and the
+        fixpoint (export -> import -> export) is byte-identical either way because
+        a declared ``members`` list re-imports to exactly itself.
+
+        Only users already carrying an account slug are emitted. ``_user_slug``
+        *allocates* on first call, and allocation order is what keeps the export
+        byte-stable (see ``_collect_account_users``), so minting one here would
+        reorder the roster; a member without an account entry could not be
+        re-imported anyway.
+
+        This used to lean on "every project member also holds a
+        ``ProgramMembership``, so is already slugged". That premise is false —
+        the two grants are independent (ADR-0070 §RBAC), and once the roster
+        stopped carrying revoked members (#3457) a program-revoked, still-live
+        project member had no slug and was dropped here in silence. So
+        ``_collect_account_users`` now slugs live project members explicitly, as
+        its last source; do not restore the assumption.
+        """
+        rows = ProjectMembership.objects.filter(project=project, is_deleted=False).select_related(
+            "user"
+        )
+        blocks = [
+            {"account": self.user_slugs[m.user_id], "role": _ROLE_NAME[m.role]}
+            for m in rows
+            if m.user_id in self.user_slugs
+        ]
+        return sorted(blocks, key=lambda b: b["account"])
+
+    def _board_column_blocks(self, project: Project) -> list[dict[str, Any]]:
+        """Emit the project's board configuration, if it has one (#3093).
+
+        Absent when the project never configured a board — the API serves
+        hardcoded defaults in that case, and emitting them would turn "this
+        project uses the defaults" into "this project pinned today's defaults",
+        which is a different and worse claim on re-import.
+
+        Optional per-column metadata is emitted only when set, so a plain
+        rename round-trips as a rename rather than as a config that also pins
+        every null.
+        """
+        config = BoardColumnConfig.objects.filter(project=project).first()
+        if config is None or not config.columns:
+            return []
+        blocks: list[dict[str, Any]] = []
+        for column in config.columns:
+            entry: dict[str, Any] = {
+                "status": column["status"],
+                "label": column.get("label", ""),
+            }
+            if column.get("visible") is not None:
+                entry["visible"] = column["visible"]
+            for key in ("color", "wip_limit", "age_threshold_days"):
+                if column.get(key) is not None:
+                    entry[key] = column[key]
+            lanes = [
+                {
+                    "key": lane["key"],
+                    "label": lane["label"],
+                    **({"wip_limit": lane["wip_limit"]} if lane.get("wip_limit") else {}),
+                }
+                for lane in (column.get("lanes") or [])
+            ]
+            if lanes:
+                entry["lanes"] = lanes
+            blocks.append(entry)
+        return blocks
+
+    def _label_blocks(self, project: Project) -> list[dict[str, Any]]:
+        """Emit the project's labels and index each task's label slugs (#1958).
+
+        Labels are ordered by ``(position, name)`` — their stable display order —
+        so the slug allocation is deterministic and the round-trip is byte-stable.
+        The per-task slug list is stashed in ``self.task_label_slugs`` for
+        ``_task_block`` to read; a label with no attached tasks still round-trips
+        (it is a curated catalog entry, so the block is emitted regardless).
+        """
+        labels = list(Label.objects.filter(project=project).order_by("position", "name", "pk"))
+        if not labels:
+            return []
+        allocator = _SlugAllocator()
+        slug_by_label: dict[Any, str] = {}
+        blocks: list[dict[str, Any]] = []
+        for label in labels:
+            slug = allocator.take(label.name)
+            slug_by_label[label.pk] = slug
+            block: dict[str, Any] = {"slug": slug, "name": label.name, "color": label.color}
+            if label.position:
+                block["position"] = label.position
+            blocks.append(block)
+        # Index each task's labels in (position, name) order — the pill-row order —
+        # so a task's ``labels`` slug list is deterministic too.
+        for tl in (
+            TaskLabel.objects.filter(label__project=project)
+            .select_related("label")
+            .order_by("label__position", "label__name", "label__pk")
+        ):
+            label_slug = slug_by_label.get(tl.label_id)
+            if label_slug is not None:
+                self.task_label_slugs.setdefault(tl.task_id, []).append(label_slug)
+        return blocks
+
+    def _task_block(self, task: Task) -> dict[str, Any]:
+        block: dict[str, Any] = {"wbs_path": str(task.wbs_path), "name": task.name}
+        self._put_task_core(block, task)
+        self._put_task_agile(block, task)
+        self._put_task_blocker(block, task)
+        self._put_task_attachments(block, task)
+        self._put_task_estimate(block, task)
+        self._put_task_assignments(block, task)
+        self._put_task_labels_and_links(block, task)
+        if self.with_events:
+            self._put_task_criteria(block, task)
+            self._put_task_depth(block, task)
+        return block
+
+    def _put_task_depth(self, block: dict[str, Any], task: Task) -> None:
+        """Subtask flag, recurrence rule and skill requirements (v2.1, #3498). v2 only.
+
+        The rule is exported as its authoring shape (weekday names, not the bitmask)
+        and ``end_type`` is implied by which end key is present, so a re-import
+        reconstructs exactly the row it came from.
+        """
+        if task.is_subtask:
+            block["is_subtask"] = True
+        rule = TaskRecurrenceRule.objects.filter(task=task, is_deleted=False).first()
+        if rule is not None:
+            recurrence: dict[str, Any] = {"frequency": rule.frequency}
+            if rule.interval != 1:
+                recurrence["interval"] = rule.interval
+            days = [name for name, bit in _WEEKDAY_BITS if rule.weekdays & bit]
+            if days:
+                recurrence["weekdays"] = days
+            _put(recurrence, "day_of_month", rule.day_of_month)
+            recurrence["time_of_day"] = rule.time_of_day.strftime("%H:%M")
+            if rule.end_date is not None:
+                recurrence["end_date"] = self._date_str(rule.end_date)
+            _put(recurrence, "end_count", rule.end_count)
+            block["recurrence"] = recurrence
+        requirements = [
+            {"skill": req.skill.name, "min_proficiency": _PROFICIENCY_NAME[req.min_proficiency]}
+            for req in TaskSkillRequirement.objects.filter(task=task, is_deleted=False)
+            .select_related("skill")
+            .order_by("skill__normalized_name", "pk")
+        ]
+        if requirements:
+            block["skill_requirements"] = requirements
+
+    def _put_task_criteria(self, block: dict[str, Any], task: Task) -> None:
+        """Acceptance criteria in position order (v2.1, #3492). v2 export only.
+
+        Emitted as final state — ``met`` with its ``met_by``/``met_at`` trail — and
+        never as ``task.ac_met`` beats, the same reason the exporter already skips
+        that action: the end value rides the row, so a beat would apply it twice.
+        ``met_by`` is emitted only for a user who is already an account; minting a
+        slug here would reorder allocation and break the byte-stable round-trip.
+        """
+        rows = AcceptanceCriterion.objects.filter(task=task, is_deleted=False).order_by(
+            "position", "pk"
+        )
+        criteria: list[dict[str, Any]] = []
+        for row in rows:
+            entry: dict[str, Any] = {"text": row.text}
+            for key in ("given", "when", "then"):
+                _put(entry, key, getattr(row, key))
+            if row.met:
+                entry["met"] = True
+                if row.met_by_id is not None and row.met_by_id in self._account_user_pks:
+                    entry["met_by"] = self._user_slug(row.met_by)
+                if row.met_at is not None:
+                    entry["met_at"] = self._rel_ts(row.met_at)
+            criteria.append(entry)
+        if criteria:
+            block["acceptance_criteria"] = criteria
+
+    def _put_task_core(self, block: dict[str, Any], task: Task) -> None:
+        """Scalar schedule/status fields, each emitted only when non-default."""
+        if task.type and task.type != "task":
+            block["type"] = task.type
+        if task.status and task.status != "NOT_STARTED":
+            block["status"] = task.status
+        if task.is_milestone:
+            block["is_milestone"] = True
+        if task.duration:
+            block["duration"] = task.duration
+        if task.planned_start is not None:
+            block["planned_start"] = self._date_str(task.planned_start)
+        if task.percent_complete:
+            block["percent_complete"] = task.percent_complete
+        _put(block, "notes", task.notes)
+        _put(block, "story_points", task.story_points)
+        _put(block, "remaining_points", task.remaining_points)
+
+    def _put_task_agile(self, block: dict[str, Any], task: Task) -> None:
+        """Assignee, sprint linkage, and agile/governance classification fields."""
+        if task.assignee_id is not None:
+            block["assignee"] = self._user_slug(task.assignee)
+        if task.sprint_id is not None:
+            block["sprint"] = self.sprint_slugs[task.sprint_id]
+        if task.parent_epic_id is not None and task.parent_epic_id in self.task_ref:
+            block["parent_epic"] = self.task_ref[task.parent_epic_id][1]
+        _put(block, "sprint_rank", task.sprint_rank)
+        if task.dor and task.dor != "idea":
+            block["dor"] = task.dor
+        _put(block, "board_lane", task.board_lane)
+        if task.governance_class and task.governance_class != "flow":
+            block["governance_class"] = task.governance_class
+        if task.delivery_mode and task.delivery_mode != "waterfall":
+            block["delivery_mode"] = task.delivery_mode
+        _put(block, "color", task.color)
+
+    def _put_task_blocker(self, block: dict[str, Any], task: Task) -> None:
+        """Emit the blocker cluster when the flag is raised (#3094).
+
+        ``blocked_reason`` is the flag-of-record, so its emptiness decides. The
+        derived companions are emitted only when set, and ``blocked_since`` rides
+        along as ``since`` — an unstamped blocker renders no age, and age is the
+        triage signal the flag exists to carry.
+        """
+        reason = (task.blocked_reason or "").strip()
+        if not reason:
+            return
+        blocked: dict[str, Any] = {"reason": task.blocked_reason}
+        if task.blocked_since is not None:
+            blocked["since"] = self._date_str(task.blocked_since.date())
+        _put(blocked, "type", task.blocker_type)
+        if task.blocking_task_id is not None and task.blocking_task_id in self.task_ref:
+            blocked["blocking_task"] = self.task_ref[task.blocking_task_id][1]
+        if task.blocked_by_id is not None:
+            blocked["by"] = self._user_slug(task.blocked_by)
+        block["blocked"] = blocked
+
+    def _put_task_attachments(self, block: dict[str, Any], task: Task) -> None:
+        """Emit external-link attachments, ordered for a stable round-trip.
+
+        File attachments are skipped rather than half-emitted: a seed is a text
+        document and ``TaskAttachment`` is file XOR ``external_url``, so a file
+        row has nothing expressible. Soft-deleted rows are skipped too — they
+        exist only to keep ``[[attachment:uuid]]`` comment references resolvable.
+        """
+        rows = [
+            row
+            for row in task.attachments.filter(is_deleted=False).order_by("created_at", "pk")
+            if row.external_url
+        ]
+        if not rows:
+            return
+        entries: list[dict[str, Any]] = []
+        for row in rows:
+            entry: dict[str, Any] = {"external_url": row.external_url}
+            _put(entry, "external_title", row.external_title)
+            if row.is_pinned:
+                entry["is_pinned"] = True
+            if row.uploaded_by_id is not None:
+                entry["uploaded_by"] = self._user_slug(row.uploaded_by)
+            entries.append(entry)
+        block["attachments"] = entries
+
+    def _put_task_estimate(self, block: dict[str, Any], task: Task) -> None:
+        if task.optimistic_duration is not None:
+            block["estimate"] = {
+                "optimistic": task.optimistic_duration,
+                "most_likely": task.most_likely_duration,
+                "pessimistic": task.pessimistic_duration,
+            }
+
+    def _put_task_assignments(self, block: dict[str, Any], task: Task) -> None:
+        assignments = [
+            {"resource": self._resource_slug(tr.resource), "units": float(tr.units)}
+            for tr in TaskResource.objects.filter(task=task)
+            .select_related("resource")
+            .order_by("resource__name")
+        ]
+        if assignments:
+            block["assignments"] = assignments
+
+    def _put_task_labels_and_links(self, block: dict[str, Any], task: Task) -> None:
+        label_slugs = self.task_label_slugs.get(task.pk)
+        if label_slugs:
+            block["labels"] = label_slugs
+        links = self._task_relation_blocks(task)
+        if links:
+            block["links"] = links
+
+    def _task_relation_blocks(self, task: Task) -> list[dict[str, Any]]:
+        """Emit this task's outgoing informational relations (ADR-0455).
+
+        Mirrors :meth:`_dependency_blocks`: one block per live ``TaskRelation`` where
+        the task is the *source*, ordered ``(relation_type, target wbs)`` so the
+        round-trip is byte-stable. A relation whose target task is excluded from the
+        export (e.g. a wbs-less promoted task) is dropped, mirroring how a dangling
+        dependency edge is skipped. The target ref is project-qualified only when it
+        crosses a project boundary — the same convention as a dependency predecessor.
+        """
+        src = self.task_ref.get(task.pk)
+        if src is None:
+            return []
+        src_pslug = src[0]
+        blocks: list[dict[str, Any]] = []
+        for rel in (
+            TaskRelation.objects.filter(source=task, is_deleted=False)
+            .select_related("target")
+            .order_by("relation_type", "target__wbs_path", "pk")
+        ):
+            tref = self.task_ref.get(rel.target_id)
+            if tref is None:
+                continue
+            target_ref = tref[1] if tref[0] == src_pslug else f"{tref[0]}:{tref[1]}"
+            block: dict[str, Any] = {"target": target_ref, "link_type": rel.relation_type}
+            _put(block, "note", rel.note)
+            blocks.append(block)
+        return blocks
+
+    def _sprint_block(self, sprint: Sprint) -> dict[str, Any]:
+        block: dict[str, Any] = {
+            "slug": self.sprint_slugs[sprint.pk],
+            "name": sprint.name,
+            "state": sprint.state,
+            "start_date": self._date_str(sprint.start_date) if sprint.start_date else None,
+            "finish_date": self._date_str(sprint.finish_date) if sprint.finish_date else None,
+        }
+        _put(block, "goal", sprint.goal)
+        _put(block, "notes", sprint.notes)
+        _put(block, "committed_points", sprint.committed_points)
+        _put(block, "completed_points", sprint.completed_points)
+        _put(block, "capacity_points", sprint.capacity_points)
+        if sprint.target_milestone_id is not None and sprint.target_milestone_id in self.task_ref:
+            block["target_milestone"] = self.task_ref[sprint.target_milestone_id][1]
+        return block
+
+    def _dependency_blocks(self, project: Project, pslug: str) -> list[dict[str, Any]]:
+        deps = (
+            Dependency.objects.filter(successor__project=project, is_deleted=False)
+            .select_related("predecessor", "successor")
+            .order_by("predecessor__wbs_path", "successor__wbs_path")
+        )
+        blocks = []
+        for dep in deps:
+            pred = self.task_ref.get(dep.predecessor_id)
+            succ = self.task_ref.get(dep.successor_id)
+            if pred is None or succ is None:
+                continue
+            pred_ref = pred[1] if pred[0] == pslug else f"{pred[0]}:{pred[1]}"
+            block: dict[str, Any] = {
+                "predecessor": pred_ref,
+                "successor": succ[1],
+                "dep_type": dep.dep_type,
+            }
+            if dep.lag:
+                block["lag"] = dep.lag
+            blocks.append(block)
+        return blocks
+
+    def _baseline_blocks(self, project: Project, pslug: str) -> list[dict[str, Any]]:
+        blocks = []
+        for baseline in Baseline.objects.filter(project=project).order_by("created_at", "pk"):
+            task_rows = []
+            for bt in BaselineTask.objects.filter(baseline=baseline).order_by("task_name", "pk"):
+                ref = self.task_ref.get(bt.task_id)
+                if ref is None:
+                    continue
+                row: dict[str, Any] = {"task": ref[1]}
+                if bt.start is not None:
+                    row["start"] = self._date_str(bt.start)
+                if bt.finish is not None:
+                    row["finish"] = self._date_str(bt.finish)
+                _put(row, "duration", bt.duration)
+                _put(row, "story_points", bt.story_points)
+                task_rows.append(row)
+            block: dict[str, Any] = {"name": baseline.name, "tasks": task_rows}
+            # Without this the round-trip silently flattens every baseline's
+            # capture date onto import day (#3093), which is the interval
+            # planned-vs-actual is measured over.
+            block["captured_at"] = self._date_str(baseline.created_at.date())
+            if baseline.is_active:
+                block["is_active"] = True
+            blocks.append(block)
+        return blocks
+
+    def _risk_blocks(self, project: Project, pslug: str) -> list[dict[str, Any]]:
+        blocks = []
+        # select_related("owner") + prefetch_related("tasks") keep the per-risk
+        # owner-slug and task-linkage lookups from firing a query inside the loop
+        # (the M2M through rows are batched into a single prefetch query, #2351).
+        risks = (
+            Risk.objects.filter(project=project, is_deleted=False)
+            .select_related("owner")
+            .order_by("title", "pk")
+            .prefetch_related("tasks")
+        )
+        slug_alloc = _SlugAllocator()
+        for risk in risks:
+            risk_slug = slug_alloc.take(risk.title)
+            self.risk_slugs[risk.pk] = risk_slug
+            block: dict[str, Any] = {
+                "slug": risk_slug,
+                "title": risk.title,
+                "status": risk.status,
+                "probability": risk.probability,
+                "impact": risk.impact,
+            }
+            _put(block, "description", risk.description)
+            _put(block, "category", risk.category)
+            _put(block, "response", risk.response)
+            if risk.mitigation_due_date is not None:
+                block["mitigation_due_date"] = self._date_str(risk.mitigation_due_date)
+            _put(block, "trigger", risk.trigger)
+            _put(block, "contingency", risk.contingency)
+            _put(block, "notes", risk.notes)
+            if risk.owner_id is not None:
+                block["owner"] = self._user_slug(risk.owner)
+            refs = []
+            for linked in risk.tasks.all():
+                ref = self.task_ref.get(linked.pk)
+                if ref is None:
+                    continue
+                refs.append(ref[1] if ref[0] == pslug else f"{ref[0]}:{ref[1]}")
+            if refs:
+                block["tasks"] = sorted(refs)
+            blocks.append(block)
+        return blocks
+
+    # --- v2 date + event reconstruction ------------------------------------
+
+    def _date_str(self, d: date) -> str:
+        """Emit a date: ISO literal (v1) or an ``anchor``-relative offset (v2)."""
+        return self._rel_date(d) if self.with_events else d.isoformat()
+
+    def _rel_date(self, d: date) -> str:
+        """A ``seedDate`` anchor offset that lands exactly (``!`` = no snap).
+
+        The ``!`` suffix opts out of weekend-snapping so the resolved date is
+        exactly ``anchor + offset`` — essential for round-trip determinism, since
+        a snapped date would drift on re-import.
+        """
+        offset = (d - self.anchor).days
+        if abs(offset) > _MAX_REL_OFFSET_DAYS:
+            return d.isoformat()
+        return f"A{offset:+d}!"
+
+    def _rel_ts(self, dt: datetime) -> str:
+        """A ``seedTimestamp`` anchor offset (event time; never weekend-snapped).
+
+        Replay builds authored event datetimes in UTC (``resolve_timestamp``
+        defaults to UTC), so we normalize to UTC and emit UTC components; a
+        re-import rebuilds the identical instant, closing the round-trip.
+        """
+        u = dt.astimezone(_UTC)
+        offset = (u.date() - self.anchor).days
+        if abs(offset) > _MAX_REL_OFFSET_DAYS:
+            return u.replace(second=0, microsecond=0, tzinfo=None).isoformat()
+        return f"A{offset:+d}T{u.hour:02d}:{u.minute:02d}"
+
+    def _capture_account_identity(self, accounts: list[dict[str, Any]]) -> None:
+        """Record which users are accounts + the deterministic fallback actor.
+
+        Every user emitted into ``accounts[]`` has a slug in ``self.user_slugs``
+        by the time this runs. The fallback actor — used when a history row is
+        attributed to a user who is not (or is no longer) an account — is the
+        lexically-first OWNER account, else the first account. Resolving every
+        event actor to a real account keeps the emitted ``actor`` from dangling
+        and makes it round-trip (replay re-attributes it, re-export reads it).
+        """
+        self._account_user_pks = set(self.user_slugs.keys())
+        if not accounts:
+            return
+        owners = sorted(a["slug"] for a in accounts if a.get("role") == "OWNER")
+        self._fallback_actor_slug = owners[0] if owners else accounts[0]["slug"]
+
+    def _actor_slug(self, user: Any) -> str:
+        """Resolve a history/audit user to an account slug (fallback if not one)."""
+        if user is not None and user.pk in self._account_user_pks:
+            return self._user_slug(user)
+        return self._fallback_actor_slug
+
+    def _events_block(self) -> list[dict[str, Any]]:
+        """Reconstruct the ordered ``events`` timeline from the history tables.
+
+        Emitted event kinds (each a clean export→import→export fixpoint):
+        ``task.status`` (Task history transitions), ``task.points`` (mid-sprint
+        remaining-point changes — the importer births a progressing task's
+        ``remaining_points`` at ``story_points``, so a burned-down value only
+        survives as an event), ``task.comment`` (``TaskComment`` rows),
+        ``sprint.activate`` / ``sprint.close`` (sprint lifecycle timestamps),
+        ``sprint.scope_inject`` (still-PENDING scope rows), and ``retro.action``
+        (retro action items).
+
+        Deliberately *not* reconstructed (documented fidelity gaps, not
+        determinism breaks): ``task.assign`` / ``task.estimate`` / ``task.ac_met``
+        (their end value is already carried by the task's final-state fields set
+        at creation, so re-emitting them as events would double-apply and break
+        the fixpoint); ``risk.status`` (the importer births risks at their final
+        status, so a status event would be a no-op that does not survive a
+        round-trip); ``sprint.scope_resolve`` and ``retro.promote`` (their target
+        row's final state — task dropped from the sprint, or a wbs-less promoted
+        task — cannot replay from the exported snapshot). The task's/sprint's
+        *final* state is always preserved via its fields; only the intermediate
+        audit rows for those specific transitions are not round-tripped.
+        """
+        collected: list[_RawEvent] = []
+        seq = 0
+
+        def emit(when: datetime, action: str, target: str, data: dict[str, Any]) -> None:
+            nonlocal seq
+            collected.append(_RawEvent(when=when, target=target, action=action, seq=seq, data=data))
+            seq += 1
+
+        for project in self.projects:
+            pslug = self.project_slugs[project.pk]
+            for task in self._project_tasks[project.pk]:
+                self._emit_task_history(task, pslug, emit)
+                self._emit_task_comments(task, pslug, emit)
+            for sprint in self._project_sprints[project.pk]:
+                self._emit_sprint_lifecycle(sprint, pslug, emit)
+                self._emit_retro_actions(sprint, pslug, emit)
+            self._emit_scope_injections(project, emit)
+            self._emit_risk_notes(project, emit)
+
+        # Chronological order; ties broken deterministically so re-export is
+        # byte-identical. The array index is the replay tiebreak for same-instant
+        # events (matching the importer's `_resolve_authored` order semantics).
+        collected.sort(key=lambda e: (e.when, e.target, e.action, e.seq))
+        out: list[dict[str, Any]] = []
+        for e in collected:
+            event: dict[str, Any] = {"at": self._rel_ts(e.when), "action": e.action}
+            event.update(e.data)
+            event["target"] = e.target
+            out.append(event)
+        return out
+
+    def _emit_task_history(self, task: Task, pslug: str, emit: _Emit) -> None:
+        """Emit ``task.status`` + ``task.points`` events from Task history.
+
+        The earliest (creation) row establishes the base status/remaining; each
+        later row is inspected for two independent changes:
+
+        - **status** changed → ``task.status`` (from/to). Replay re-creates the
+          task at NOT_STARTED and walks it forward, reproducing the same rows.
+        - **remaining_points** changed *without* a status change → ``task.points``.
+          A remaining change that coincides with a status change is the COMPLETE
+          handler zeroing remaining_points (``_apply_task_status``), which replay
+          re-applies on its own, so emitting a ``task.points`` for it would be a
+          redundant, non-round-tripping write — hence the ``not status_changed``
+          guard.
+        """
+        target = f"task:{pslug}:{task.wbs_path}"
+        prev_status: str | None = None
+        prev_remaining: int | None = None
+        rows = task.history.select_related("history_user").order_by("history_date", "history_id")
+        for row in rows:
+            if prev_status is None:
+                prev_status = row.status
+                prev_remaining = row.remaining_points
+                continue
+            status_changed = row.status != prev_status
+            if status_changed:
+                emit(
+                    row.history_date,
+                    "task.status",
+                    target,
+                    {
+                        "actor": self._actor_slug(row.history_user),
+                        "from": prev_status,
+                        "to": row.status,
+                    },
+                )
+                prev_status = row.status
+            if (
+                not status_changed
+                and row.remaining_points is not None
+                and row.remaining_points != prev_remaining
+            ):
+                emit(
+                    row.history_date,
+                    "task.points",
+                    target,
+                    {
+                        "actor": self._actor_slug(row.history_user),
+                        "remaining_points": row.remaining_points,
+                    },
+                )
+            prev_remaining = row.remaining_points
+
+    def _emit_task_comments(self, task: Task, pslug: str, emit: _Emit) -> None:
+        """Emit comments — and under v2.1, their threads, reactions, acks, and notes.
+
+        A comment gets a ``slug`` only when something refers to it (a reply, a
+        reaction or an acknowledgement), so a program with flat comments exports
+        exactly as it did under 2.0. Reactions and acknowledgements are emitted
+        only for users who already hold an account: attributing them to the
+        fallback actor would invent a reaction nobody gave.
+        """
+        target = f"task:{pslug}:{task.wbs_path}"
+        comments = list(
+            TaskComment.objects.filter(task=task)
+            .select_related("author")
+            .order_by("created_at", "pk")
+        )
+        if not self.with_events or not comments:
+            for c in comments:
+                emit(
+                    c.created_at,
+                    "task.comment",
+                    target,
+                    {"actor": self._actor_slug(c.author), "body": c.body},
+                )
+            self._emit_task_notes(task, target, emit)
+            return
+
+        reactions = list(
+            CommentReaction.objects.filter(comment__in=comments, user_id__in=self._account_user_pks)
+            .select_related("user")
+            .order_by("created_at", "pk")
+        )
+        acks = list(
+            CommentAcknowledgement.objects.filter(
+                comment__in=comments, user_id__in=self._account_user_pks
+            )
+            .select_related("user")
+            .order_by("created_at", "pk")
+        )
+        referenced = {c.parent_id for c in comments if c.parent_id is not None}
+        referenced |= {r.comment_id for r in reactions} | {a.comment_id for a in acks}
+        slugs: dict[Any, str] = {}
+        for n, c in enumerate(comments, start=1):
+            if c.pk in referenced:
+                slugs[c.pk] = self.comment_slug.take(f"{pslug}-{task.wbs_path}-comment-{n}")
+
+        for c in comments:
+            data: dict[str, Any] = {"actor": self._actor_slug(c.author), "body": c.body}
+            if c.pk in slugs:
+                data["slug"] = slugs[c.pk]
+            if c.parent_id in slugs:
+                data["reply_to"] = slugs[c.parent_id]
+            emit(c.created_at, "task.comment", target, data)
+        for r in reactions:
+            emit(
+                r.created_at,
+                "task.react",
+                f"comment:{slugs[r.comment_id]}",
+                {"actor": self._user_slug(r.user), "emoji": r.emoji},
+            )
+        for a in acks:
+            emit(
+                a.created_at,
+                "task.ack",
+                f"comment:{slugs[a.comment_id]}",
+                {"actor": self._user_slug(a.user)},
+            )
+        self._emit_task_notes(task, target, emit)
+
+    def _emit_task_notes(self, task: Task, target: str, emit: _Emit) -> None:
+        """Emit ``task.note`` beats from live ``TaskNote`` rows (v2.1, #3492). v2 only.
+
+        A note is append-only like a comment, so replaying it reproduces the row it
+        came from. Per-person logged time is deliberately *not* reconstructed the
+        same way: exporting ``time.log`` would hand every program Admin who can run
+        an export each contributor's hours, which ADR-0104 keeps off management
+        surfaces.
+        """
+        if not self.with_events:
+            return
+        for note in (
+            TaskNote.objects.filter(task=task, is_deleted=False)
+            .select_related("author")
+            .order_by("created_at", "pk")
+        ):
+            data: dict[str, Any] = {"actor": self._actor_slug(note.author), "body": note.body}
+            if note.pinned:
+                data["pinned"] = True
+            if note.decision:
+                data["decision"] = True
+            emit(note.created_at, "task.note", target, data)
+
+    def _emit_risk_notes(self, project: Project, emit: _Emit) -> None:
+        """Emit ``risk.note`` events from RiskComment rows (#3094).
+
+        Safe to reconstruct, unlike ``risk.status``: a comment is an append-only
+        artifact that does not depend on the risk's current status, so replaying
+        it reproduces exactly the rows it came from — the same reason
+        ``task.comment`` round-trips.
+        """
+        for comment in (
+            RiskComment.objects.filter(risk__project=project, risk__is_deleted=False)
+            .select_related("author", "risk")
+            .order_by("created_at", "pk")
+        ):
+            slug = self.risk_slugs.get(comment.risk_id)
+            if slug is None:
+                continue
+            emit(
+                comment.created_at,
+                "risk.note",
+                f"risk:{slug}",
+                {"actor": self._actor_slug(comment.author), "body": comment.message},
+            )
+
+    def _emit_sprint_lifecycle(self, sprint: Sprint, pslug: str, emit: _Emit) -> None:
+        """Emit activate/close from the sprint's lifecycle timestamps.
+
+        ``activated_at`` / ``closed_at`` carry the beat time; the actor is not
+        persisted on the sprint, so the deterministic fallback (OWNER) is used —
+        the sprint's committed/completed points ride their fields (snapshotted at
+        activate/close on replay), and ``goal_outcome`` rides the close event.
+        """
+        target = f"sprint:{pslug}:{self.sprint_slugs[sprint.pk]}"
+        if sprint.activated_at is not None:
+            emit(
+                sprint.activated_at,
+                "sprint.activate",
+                target,
+                {"actor": self._fallback_actor_slug},
+            )
+        if sprint.closed_at is not None:
+            data: dict[str, Any] = {"actor": self._fallback_actor_slug}
+            if sprint.goal_outcome:
+                data["goal_outcome"] = sprint.goal_outcome
+            emit(sprint.closed_at, "sprint.close", target, data)
+
+    def _emit_scope_injections(self, project: Project, emit: _Emit) -> None:
+        """Emit ``sprint.scope_inject`` for still-PENDING scope-change rows.
+
+        Only PENDING rows round-trip cleanly: the injected task is still in its
+        sprint (so replay's ``_apply_scope_inject`` re-creates the audit row), and
+        ``added_at`` is backdated by replay so the timestamp is stable. ACCEPTED /
+        REJECTED rows are skipped — the resolve timestamp is not persisted and a
+        rejected injection removed the task from its sprint.
+        """
+        rows = (
+            SprintScopeChange.objects.filter(
+                sprint__project=project, status=ScopeChangeStatus.PENDING
+            )
+            .select_related("task", "added_by")
+            .order_by("added_at", "pk")
+        )
+        for sc in rows:
+            ref = self.task_ref.get(sc.task_id)
+            if ref is None:
+                continue  # task excluded from export (e.g. no wbs_path)
+            data: dict[str, Any] = {"actor": self._actor_slug(sc.added_by)}
+            if sc.goal_impact:
+                data["goal_impact"] = True
+            emit(sc.added_at, "sprint.scope_inject", f"task:{ref[0]}:{ref[1]}", data)
+
+    def _emit_retro_actions(self, sprint: Sprint, pslug: str, emit: _Emit) -> None:
+        """Emit a ``retro.action`` per retro action item on the sprint's retro.
+
+        A non-empty ``SprintRetro.notes`` rides on the last item's beat (as
+        ``notes``) rather than its own event — there is no standalone "open
+        retro" action, so a retro's summary text can only round-trip attached
+        to an action item that already exists (#3497). A retro with notes but
+        no action items cannot be reconstructed as v2 events; that gap predates
+        this change (the retro itself couldn't be created via replay either).
+        """
+        retro = SprintRetro.objects.filter(sprint=sprint).first()
+        if retro is None:
+            return
+        target = f"sprint:{pslug}:{self.sprint_slugs[sprint.pk]}"
+        actor = self._actor_slug(retro.created_by)
+        items = list(
+            RetroActionItem.objects.filter(retro=retro)
+            .select_related("assignee")
+            .order_by("created_at", "pk")
+        )
+        for i, item in enumerate(items):
+            data: dict[str, Any] = {"actor": actor, "body": item.text}
+            if item.assignee_id is not None and item.assignee_id in self._account_user_pks:
+                data["assignee"] = self._user_slug(item.assignee)
+            if item.story_points is not None:
+                data["points"] = item.story_points
+            if i == len(items) - 1 and retro.notes:
+                data["notes"] = retro.notes
+            emit(item.created_at, "retro.action", target, data)
+
+    # --- slug helpers ------------------------------------------------------
+
+    def _user_slug(self, user: Any) -> str:
+        if user.pk not in self.user_slugs:
+            self.user_slugs[user.pk] = self.account_slug.take(user.get_username())
+        return self.user_slugs[user.pk]
+
+    def _calendar_slug(self, calendar: Any) -> str:
+        if calendar.pk not in self.calendar_slugs:
+            self.calendar_slugs[calendar.pk] = self.calendar_slug.take(calendar.name)
+        return self.calendar_slugs[calendar.pk]
+
+    def _resource_slug(self, resource: Resource) -> str:
+        if resource.pk not in self.resource_slugs:
+            self.resource_slugs[resource.pk] = self.resource_slug.take(resource.name)
+        return self.resource_slugs[resource.pk]
+
+    # --- collection helpers ------------------------------------------------
+
+    def _all_tasks(self) -> list[Task]:
+        return list(
+            Task.objects.filter(project__in=self.projects, is_deleted=False).select_related(
+                "assignee"
+            )
+        )
+
+    def _all_resources(self) -> list[Resource]:
+        # Resources referenced by either a task assignment or the project roster.
+        if self._resources_cache is not None:
+            return self._resources_cache
+        ids = set(
+            TaskResource.objects.filter(task__project__in=self.projects).values_list(
+                "resource_id", flat=True
+            )
+        )
+        ids |= set(
+            ProjectResource.objects.filter(project__in=self.projects, is_deleted=False).values_list(
+                "resource_id", flat=True
+            )
+        )
+        self._resources_cache = list(
+            Resource.objects.filter(pk__in=ids)
+            .select_related("calendar", "user")
+            .order_by("name", "pk")
+        )
+        return self._resources_cache