trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/msproject/exporter.py

@@ -0,0 +1,551 @@
+"""Export TruePPM project data to MS Project XML format."""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from datetime import date
+from typing import Any
+
+from trueppm_api.apps.msproject.extended_attributes import (
+    DURATION1_FIELD_ID,
+    DURATION2_FIELD_ID,
+    DURATION3_FIELD_ID,
+    DURATION4_FIELD_ID,
+    PERT_ALIAS_LABELS,
+    PERT_EXPECTED_FORMULA,
+    PERT_FIELD_NAMES,
+)
+from trueppm_api.apps.scheduling.units import (
+    HOURS_PER_WORKING_DAY,
+    MSPDI_LAG_TENTHS_PER_WORKING_DAY,
+)
+
+# MS Project XML namespace.
+_NS = "http://schemas.microsoft.com/project"
+
+# MSPDI <ConstraintType> codes this exporter emits (#2891). Named rather than
+# inlined because the importer's mapping table (`CONSTRAINT_TYPES_APPLIED_AS_SNET`
+# in `dataclasses`) has to stay in agreement with them for the round trip to close.
+MSPDI_CONSTRAINT_AS_SOON_AS_POSSIBLE = 0
+MSPDI_CONSTRAINT_START_NO_EARLIER_THAN = 4
+
+# TruePPM dep_type -> MS Project PredecessorLink/Type.
+_DEP_TYPE_TO_LINK_TYPE = {
+    "FF": "0",
+    "FS": "1",
+    "SF": "2",
+    "SS": "3",
+}
+
+# MSPDI WeekDay/DayType (1=Sunday … 7=Saturday) paired with the TruePPM
+# Calendar.working_days bit (Mon=1 … Sun=64), in MSPDI emission order.
+# Keep in lockstep with parser._DAY_TYPE_TO_BIT.
+_DAY_TYPES_AND_BITS = (
+    ("1", 64),  # Sunday
+    ("2", 1),  # Monday
+    ("3", 2),  # Tuesday
+    ("4", 4),  # Wednesday
+    ("5", 8),  # Thursday
+    ("6", 16),  # Friday
+    ("7", 32),  # Saturday
+)
+
+
+def export_project_xml(project_id: str) -> bytes:
+    """Export a TruePPM project to MS Project XML format.
+
+    Returns:
+        UTF-8 encoded XML bytes.
+    """
+    from trueppm_api.apps.projects.models import Dependency, Project, Task
+    from trueppm_api.apps.resources.models import Resource, TaskResource
+    from trueppm_api.apps.scheduling.calendars import resolve_applied_calendars
+
+    # calendar__exceptions + calendar_layers__calendar__exceptions: the calendar
+    # emission below walks every applied calendar's exceptions (#1769).
+    project = Project.objects.prefetch_related(
+        "calendar__exceptions", "calendar_layers__calendar__exceptions"
+    ).get(pk=project_id)
+    applied_calendars = resolve_applied_calendars(project)
+    tasks = list(
+        Task.objects.filter(project_id=project_id, is_deleted=False).order_by("wbs_path", "name")
+    )
+    dependencies = list(
+        Dependency.objects.filter(
+            predecessor__project_id=project_id, is_deleted=False
+        ).select_related("predecessor", "successor")
+    )
+    task_ids = [str(t.pk) for t in tasks]
+    assignments = list(TaskResource.objects.filter(task_id__in=task_ids).select_related("resource"))
+    resource_ids = {a.resource_id for a in assignments}
+    resources = list(Resource.objects.filter(pk__in=resource_ids))
+
+    # UID maps - MS Project expects sequential integer UIDs.
+    task_pk_to_uid = {str(t.pk): i for i, t in enumerate(tasks, start=1)}
+    resource_pk_to_uid = {str(r.pk): i for i, r in enumerate(resources, start=1)}
+    dep_by_successor = _build_dep_lookup(dependencies)
+
+    # --- Build XML ---
+    ET.register_namespace("", _NS)
+    root = ET.Element(f"{{{_NS}}}Project")
+
+    _sub_text(root, "Name", project.name)
+    _sub_text(root, "StartDate", _format_date(project.start_date))
+    if applied_calendars:
+        # The merged working calendar is always emitted as UID 1 (see
+        # _add_calendars_block). Header element order follows the MSPDI schema:
+        # CalendarUID sits among the project properties, before
+        # ExtendedAttributes and Calendars.
+        _sub_text(root, "CalendarUID", "1")
+
+    # --- Project-level ExtendedAttribute definitions (#798, ADR-0093) ---
+    # Emit the four PERT slots only when at least one non-summary, non-milestone
+    # task carries all three values. MS Project tolerates the block being
+    # absent; emitting it unconditionally would clutter files that don't use
+    # three-point estimates.
+    pert_tasks = _select_pert_tasks(tasks)
+    if pert_tasks:
+        _add_pert_extended_attribute_defs(root)
+
+    # --- Calendars (#1769) ---
+    # Emitted between ExtendedAttributes and Tasks, matching the MSPDI element
+    # order. Omitted entirely when the project has no applied calendar (the
+    # engine's implicit Mon-Fri/8h default), which MS Project also defaults to.
+    if applied_calendars:
+        _add_calendars_block(root, applied_calendars)
+
+    # --- Tasks ---
+    tasks_el = ET.SubElement(root, f"{{{_NS}}}Tasks")
+
+    # Task UID 0: project summary task
+    _add_summary_task(tasks_el, project)
+
+    pert_task_pks = {str(t.pk) for t in pert_tasks}
+    day_end_time = _milestone_day_end_time(applied_calendars)
+    for task in tasks:
+        _add_task_element(
+            tasks_el,
+            task,
+            task_pk_to_uid[str(task.pk)],
+            is_pert=str(task.pk) in pert_task_pks,
+            preds=dep_by_successor.get(str(task.pk), []),
+            task_pk_to_uid=task_pk_to_uid,
+            day_end_time=day_end_time,
+        )
+
+    _add_resources_block(root, resources, resource_pk_to_uid)
+    _add_assignments_block(root, assignments, task_pk_to_uid, resource_pk_to_uid)
+
+    # Serialize
+    tree = ET.ElementTree(root)
+    ET.indent(tree, space="  ")
+
+    xml_decl = b'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n'
+    return xml_decl + ET.tostring(root, encoding="unicode").encode("utf-8")
+
+
+def _build_dep_lookup(dependencies: list[Any]) -> dict[str, list[tuple[str, str, int]]]:
+    """Index dependencies by successor: ``successor_pk -> [(pred_pk, dep_type, lag)]``."""
+    dep_by_successor: dict[str, list[tuple[str, str, int]]] = {}
+    for dep in dependencies:
+        dep_by_successor.setdefault(str(dep.successor_id), []).append(
+            (str(dep.predecessor_id), dep.dep_type, dep.lag)
+        )
+    return dep_by_successor
+
+
+def _select_pert_tasks(tasks: list[Any]) -> list[Any]:
+    """Return the leaf, non-milestone tasks carrying all three PERT durations.
+
+    The summary set is precomputed once for O(N) filtering — a summary or
+    milestone task never emits three-point values (ADR-0093 Q5).
+    """
+    summary_pks = _summary_pks_from_tasks(tasks)
+    return [
+        t
+        for t in tasks
+        if (
+            str(t.pk) not in summary_pks
+            and not t.is_milestone
+            and t.optimistic_duration is not None
+            and t.most_likely_duration is not None
+            and t.pessimistic_duration is not None
+        )
+    ]
+
+
+def _add_task_dates(task_el: ET.Element, task: Any, day_end_time: str = "00:00:00") -> None:
+    """Emit the contiguous Start/Finish/Constraint/Actual date run for one ``<Task>``.
+
+    MSPDI is order-sensitive, and ``ET.SubElement`` appends at call time, so the
+    caller's invocation position *is* the positional guarantee for every element
+    below — it must stay exactly where it sits in ``_add_task_element``'s append
+    sequence (after ``Notes``, before the PERT ExtendedAttribute values).
+
+    Constraint + actuals round-trip (#2891). ``planned_start`` IS a
+    start-no-earlier-than floor, so emitting it as MSPDI ConstraintType 4 with a
+    ConstraintDate is a faithful translation rather than an approximation — and
+    it is what makes the round trip closed: the importer reads the constraint
+    date back as ``planned_start``. Emitting only <Start> (which is CPM output, and
+    per ADR-0132 a remaining-work date on a partially-complete task) meant a
+    re-import silently promoted computed dates to committed ones.
+
+    Tasks with no floor get ConstraintType 0 (As Soon As Possible), which is
+    TruePPM's own default: an omitted element would leave MS Project to infer a
+    constraint from the <Start> we emit, re-creating the same promotion.
+
+    End-of-day milestones (#4079). A milestone that follows work sits at the END
+    of its ``early_start`` day, and MS Project places it there too — at the
+    calendar's finish time, not at midnight. Writing midnight would put it at the
+    start of the day, before its own predecessor finishes. ``day_end_time`` is
+    the end of the working day MS Project will schedule the file on
+    (:func:`_milestone_day_end_time`).
+    """
+    at_day_end = bool(task.is_milestone and getattr(task, "milestone_at_day_end", False))
+    time_of_day = day_end_time if at_day_end else "00:00:00"
+    if task.early_start:
+        _sub_text(task_el, "Start", _format_date(task.early_start, time_of_day))
+    elif task.planned_start:
+        _sub_text(task_el, "Start", _format_date(task.planned_start))
+    if task.early_finish:
+        _sub_text(task_el, "Finish", _format_date(task.early_finish, time_of_day))
+
+    if task.planned_start:
+        _sub_text(task_el, "ConstraintType", str(MSPDI_CONSTRAINT_START_NO_EARLIER_THAN))
+        _sub_text(task_el, "ConstraintDate", _format_date(task.planned_start))
+    else:
+        _sub_text(task_el, "ConstraintType", str(MSPDI_CONSTRAINT_AS_SOON_AS_POSSIBLE))
+    # A milestone closed after work keeps its end-of-day edge (#4433), and MS
+    # Project reads a 100%-complete task's Finish from its ActualFinish: the
+    # actuals carry the same time of day as Start/Finish, or the re-imported
+    # milestone sits at the start of its day and its successors land a day early.
+    if task.actual_start:
+        _sub_text(task_el, "ActualStart", _format_date(task.actual_start, time_of_day))
+    if task.actual_finish:
+        _sub_text(task_el, "ActualFinish", _format_date(task.actual_finish, time_of_day))
+
+
+def _add_task_element(
+    tasks_el: ET.Element,
+    task: Any,
+    uid: int,
+    *,
+    is_pert: bool,
+    preds: list[tuple[str, str, int]],
+    task_pk_to_uid: dict[str, int],
+    day_end_time: str = "00:00:00",
+) -> None:
+    """Emit one ``<Task>`` element, including PERT values and predecessor links."""
+    task_el = ET.SubElement(tasks_el, f"{{{_NS}}}Task")
+    _sub_text(task_el, "UID", str(uid))
+    _sub_text(task_el, "Name", task.name)
+    _sub_text(task_el, "Duration", _days_to_duration(task.duration))
+    _sub_text(task_el, "DurationFormat", "7")
+    if task.wbs_path:
+        _sub_text(task_el, "OutlineNumber", task.wbs_path)
+        _sub_text(task_el, "OutlineLevel", str(task.wbs_path.count(".") + 1))
+    else:
+        _sub_text(task_el, "OutlineLevel", "1")
+    _sub_text(task_el, "Milestone", "1" if task.is_milestone else "0")
+    # Task.percent_complete is already a 0-100 percent (#1759) and MSPDI
+    # PercentComplete is the same 0-100 scale, so emit it as-is. The earlier
+    # `* 100` turned a native 50% task into an invalid PercentComplete=5000.
+    _sub_text(task_el, "PercentComplete", str(round(task.percent_complete or 0)))
+    if task.notes:
+        _sub_text(task_el, "Notes", task.notes)
+    _add_task_dates(task_el, task, day_end_time)
+
+    # PERT three-point per-task values. Only emitted for the leaf, non-milestone
+    # tasks selected by _select_pert_tasks. Duration4 is the PERT-Expected
+    # formula slot; MS Project derives it on read from the project-level Formula
+    # definition, so we never emit a per-task Duration4 value.
+    if is_pert:
+        # All three are non-None by the _select_pert_tasks filter, but mypy
+        # can't carry that proof across the call boundary.
+        assert task.optimistic_duration is not None
+        assert task.most_likely_duration is not None
+        assert task.pessimistic_duration is not None
+        _add_pert_task_values(
+            task_el,
+            task.optimistic_duration,
+            task.most_likely_duration,
+            task.pessimistic_duration,
+        )
+
+    for pred_pk, dep_type, lag in preds:
+        pred_uid = task_pk_to_uid.get(pred_pk)
+        if pred_uid is None:
+            continue
+        pred_el = ET.SubElement(task_el, f"{{{_NS}}}PredecessorLink")
+        _sub_text(pred_el, "PredecessorUID", str(pred_uid))
+        _sub_text(pred_el, "Type", _DEP_TYPE_TO_LINK_TYPE.get(dep_type, "1"))
+        # LinkLag is tenths of a minute; one working day of lag is
+        # MSPDI_LAG_TENTHS_PER_WORKING_DAY (#2290 unit seam).
+        _sub_text(pred_el, "LinkLag", str(lag * MSPDI_LAG_TENTHS_PER_WORKING_DAY))
+        _sub_text(pred_el, "LagFormat", "7")
+
+
+def _add_resources_block(
+    root: ET.Element, resources: list[Any], resource_pk_to_uid: dict[str, int]
+) -> None:
+    """Emit the ``<Resources>`` block."""
+    resources_el = ET.SubElement(root, f"{{{_NS}}}Resources")
+    for resource in resources:
+        uid = resource_pk_to_uid[str(resource.pk)]
+        res_el = ET.SubElement(resources_el, f"{{{_NS}}}Resource")
+        _sub_text(res_el, "UID", str(uid))
+        _sub_text(res_el, "Name", resource.name)
+        # The resource's own catalog capacity, NOT its project-effective figure
+        # (#3574). MSPDI has no per-project override concept, so writing the
+        # effective value here would bake one project's slice into the resource
+        # default — and the importer reads MaxUnits straight back into
+        # ``Resource.max_units``, so a round trip would make the override permanent
+        # and global. The override is a TruePPM-side fact with no MSPDI counterpart.
+        _sub_text(res_el, "MaxUnits", f"{float(resource.max_units):.2f}")
+
+
+def _add_assignments_block(
+    root: ET.Element,
+    assignments: list[Any],
+    task_pk_to_uid: dict[str, int],
+    resource_pk_to_uid: dict[str, int],
+) -> None:
+    """Emit the ``<Assignments>`` block, skipping any dangling task/resource ref."""
+    assignments_el = ET.SubElement(root, f"{{{_NS}}}Assignments")
+    asgn_uid = 1
+    for asgn in assignments:
+        task_uid = task_pk_to_uid.get(str(asgn.task_id))
+        res_uid = resource_pk_to_uid.get(str(asgn.resource_id))
+        if task_uid is None or res_uid is None:
+            continue
+        asgn_el = ET.SubElement(assignments_el, f"{{{_NS}}}Assignment")
+        _sub_text(asgn_el, "UID", str(asgn_uid))
+        _sub_text(asgn_el, "TaskUID", str(task_uid))
+        _sub_text(asgn_el, "ResourceUID", str(res_uid))
+        _sub_text(asgn_el, "Units", f"{float(asgn.units):.2f}")
+        asgn_uid += 1
+
+
+def _sub_text(parent: ET.Element, tag: str, text: str) -> ET.Element:
+    """Add a child element with text content."""
+    el = ET.SubElement(parent, f"{{{_NS}}}{tag}")
+    el.text = text
+    return el
+
+
+def _format_date(d: date, time_of_day: str = "00:00:00") -> str:
+    """Format a date as MS Project expects: ``YYYY-MM-DDTHH:MM:SS`` (midnight by default)."""
+    return f"{d.isoformat()}T{time_of_day}"
+
+
+def _days_to_duration(days: int) -> str:
+    """Convert working days to MS Project ISO 8601 duration.
+
+    Uses the nominal working-day length from the unit seam (#2290) rather than a
+    bare ``* 8`` so a 0.5 canonical-unit change re-homes in one place.
+    """
+    hours = days * HOURS_PER_WORKING_DAY
+    return f"PT{hours}H0M0S"
+
+
+def _minutes_to_time(minutes: int) -> str:
+    """Format minutes-since-midnight as an MSPDI time-of-day (``HH:MM:00``)."""
+    return f"{minutes // 60:02d}:{minutes % 60:02d}:00"
+
+
+def _add_calendars_block(root: ET.Element, applied_calendars: list[Any]) -> None:
+    """Emit ``<Calendars>`` with one base calendar folding every applied layer (#1769).
+
+    MSPDI has no equivalent of TruePPM's composable calendar layers (#906,
+    ADR-0251), so the export flattens them exactly the way the CPM pass composes
+    them: weekday masks AND-ed, exception ranges unioned, ``hours_per_day`` and
+    name from the base (first) calendar. The exported file then schedules on the
+    same non-working mask TruePPM computed, at the cost of the layer structure.
+
+    TruePPM stores only a daily hour total, not shift times, so each working day
+    is synthesized as a single continuous shift starting at 08:00 (falling back
+    to midnight when the total would run past midnight). The caller must invoke
+    this before the ``<Tasks>`` block is appended — ``ET.SubElement`` appends at
+    call time, so call ordering is the positional guarantee (same contract as
+    ``_add_pert_extended_attribute_defs``).
+    """
+    base = applied_calendars[0]
+    mask, merged_exceptions = _merge_applied_calendars(applied_calendars)
+
+    cals_el = ET.SubElement(root, f"{{{_NS}}}Calendars")
+    cal_el = ET.SubElement(cals_el, f"{{{_NS}}}Calendar")
+    _sub_text(cal_el, "UID", "1")
+    _sub_text(cal_el, "Name", base.name)
+    _sub_text(cal_el, "IsBaseCalendar", "1")
+    _sub_text(cal_el, "BaseCalendarUID", "-1")
+
+    start_minute, shift_minutes = _shift_window(base.hours_per_day)
+    _add_weekday_elements(cal_el, mask, start_minute, shift_minutes)
+    if merged_exceptions:
+        _add_calendar_exception_elements(cal_el, merged_exceptions)
+
+
+def _shift_window(hours_per_day: float) -> tuple[int, int]:
+    """``(start_minute, shift_minutes)`` of the one synthesized daily shift.
+
+    08:00 plus the daily hour total, falling back to a midnight start when that
+    would run past midnight. Shared by the ``<Calendars>`` block and the
+    end-of-day milestone time (#4079) so the two can never disagree.
+    """
+    start_minute = 8 * 60
+    shift_minutes = max(0, min(round(hours_per_day * 60), 24 * 60))
+    if start_minute + shift_minutes > 24 * 60:
+        start_minute = 0
+    return start_minute, shift_minutes
+
+
+# MS Project's built-in "Standard" calendar works 08:00-12:00 and 13:00-17:00.
+_MSP_STANDARD_DAY_END = "17:00:00"
+# The last representable time of day. ``T24:00:00`` is not a valid xs:dateTime
+# for MS Project, which would reject or misplace the milestone.
+_LAST_MINUTE_OF_DAY = 24 * 60 - 1
+
+
+def _milestone_day_end_time(applied_calendars: list[Any]) -> str:
+    """The time of day an end-of-day milestone is written at (#4079).
+
+    It must be the end of the working day of the calendar MS Project will actually
+    schedule the file on. With an applied calendar that is the synthesized shift
+    the ``<Calendars>`` block declares (:func:`_shift_window`). With none, no
+    ``<Calendars>`` block is emitted and MS Project falls back to its own Standard
+    calendar, whose day ends at 17:00 — not at the 16:00 the engine's 8-hour
+    default would give from an 08:00 start. A shift that runs to midnight
+    (``hours_per_day`` >= 16 makes it start at 00:00 and end at 24:00, or a
+    24-hour day) is clamped to 23:59, the last time of day xs:dateTime can say.
+    """
+    if not applied_calendars:
+        return _MSP_STANDARD_DAY_END
+    start_minute, shift_minutes = _shift_window(applied_calendars[0].hours_per_day)
+    return _minutes_to_time(min(start_minute + shift_minutes, _LAST_MINUTE_OF_DAY))
+
+
+def _merge_applied_calendars(
+    applied_calendars: list[Any],
+) -> tuple[int, dict[tuple[Any, Any], str]]:
+    """Fold the applied calendar layers into one working mask and exception set.
+
+    Weekday masks are AND-ed and exception ranges unioned, matching how the CPM
+    pass composes layers. First writer wins on a duplicate range so the base
+    calendar's description (not an overlay's) labels the exception.
+    """
+    mask = applied_calendars[0].working_days
+    merged_exceptions: dict[tuple[Any, Any], str] = {}
+    for cal in applied_calendars:
+        mask &= cal.working_days
+        for exc in cal.exceptions.all():
+            merged_exceptions.setdefault((exc.exc_start, exc.exc_end), exc.description)
+    return mask, merged_exceptions
+
+
+def _add_weekday_elements(
+    cal_el: ET.Element, mask: int, start_minute: int, shift_minutes: int
+) -> None:
+    """Emit the seven ``<WeekDay>`` entries, each with a single synthesized shift."""
+    weekdays_el = ET.SubElement(cal_el, f"{{{_NS}}}WeekDays")
+    for day_type, bit in _DAY_TYPES_AND_BITS:
+        day_el = ET.SubElement(weekdays_el, f"{{{_NS}}}WeekDay")
+        _sub_text(day_el, "DayType", day_type)
+        working = bool(mask & bit)
+        _sub_text(day_el, "DayWorking", "1" if working else "0")
+        if working and shift_minutes > 0:
+            times_el = ET.SubElement(day_el, f"{{{_NS}}}WorkingTimes")
+            wt_el = ET.SubElement(times_el, f"{{{_NS}}}WorkingTime")
+            _sub_text(wt_el, "FromTime", _minutes_to_time(start_minute))
+            _sub_text(wt_el, "ToTime", _minutes_to_time(start_minute + shift_minutes))
+
+
+def _add_calendar_exception_elements(
+    cal_el: ET.Element, merged_exceptions: dict[tuple[Any, Any], str]
+) -> None:
+    """Emit the ``<Exceptions>`` block for the merged non-working date ranges."""
+    excs_el = ET.SubElement(cal_el, f"{{{_NS}}}Exceptions")
+    for (exc_start, exc_end), description in sorted(merged_exceptions.items()):
+        exc_el = ET.SubElement(excs_el, f"{{{_NS}}}Exception")
+        period_el = ET.SubElement(exc_el, f"{{{_NS}}}TimePeriod")
+        _sub_text(period_el, "FromDate", f"{exc_start.isoformat()}T00:00:00")
+        _sub_text(period_el, "ToDate", f"{exc_end.isoformat()}T23:59:00")
+        if description:
+            _sub_text(exc_el, "Name", description)
+        _sub_text(exc_el, "DayWorking", "0")
+
+
+def _add_summary_task(tasks_el: ET.Element, project: object) -> None:
+    """Add the UID 0 project summary task."""
+    task_el = ET.SubElement(tasks_el, f"{{{_NS}}}Task")
+    _sub_text(task_el, "UID", "0")
+    _sub_text(task_el, "Name", project.name)  # type: ignore[attr-defined]
+    _sub_text(task_el, "OutlineLevel", "0")
+    _sub_text(task_el, "OutlineNumber", "0")
+
+
+def _summary_pks_from_tasks(tasks: list[Any]) -> set[str]:
+    """Return the set of task primary keys that are summary tasks.
+
+    A task is a summary when another task's ``wbs_path`` is strictly descended
+    from this one's (e.g. ``"1"`` is a summary if any task has path ``"1.1"``).
+    O(N) over the task list: build the set of strict ancestor paths from every
+    leaf path in one pass, then mark every task whose own path is in that set.
+    """
+    ancestor_paths: set[str] = set()
+    for t in tasks:
+        path = getattr(t, "wbs_path", None)
+        if not path:
+            continue
+        path = str(path)
+        parts = path.split(".")
+        for end in range(1, len(parts)):
+            ancestor_paths.add(".".join(parts[:end]))
+    return {
+        str(t.pk)
+        for t in tasks
+        if getattr(t, "wbs_path", None) and str(t.wbs_path) in ancestor_paths
+    }
+
+
+def _add_pert_extended_attribute_defs(root: ET.Element) -> None:
+    """Emit the four PERT ExtendedAttribute definitions at project level.
+
+    Duration1–3 carry the aliases Optimistic / Most Likely / Pessimistic.
+    Duration4 carries the formula MS Project uses to derive PERT Expected
+    on file open. The caller is responsible for invoking this **before** the
+    ``<Tasks>`` block is appended, so the resulting element order
+    (``<ExtendedAttributes>`` then ``<Tasks>``) matches MS Project's own
+    element order. ``ET.SubElement`` appends at call time, so call ordering
+    is the positional guarantee — don't move this call after ``<Tasks>``.
+    """
+    ea_block = ET.SubElement(root, f"{{{_NS}}}ExtendedAttributes")
+    for fid in (DURATION1_FIELD_ID, DURATION2_FIELD_ID, DURATION3_FIELD_ID, DURATION4_FIELD_ID):
+        ea = ET.SubElement(ea_block, f"{{{_NS}}}ExtendedAttribute")
+        _sub_text(ea, "FieldID", fid)
+        _sub_text(ea, "FieldName", PERT_FIELD_NAMES[fid])
+        _sub_text(ea, "Alias", PERT_ALIAS_LABELS[fid])
+        if fid == DURATION4_FIELD_ID:
+            _sub_text(ea, "Formula", PERT_EXPECTED_FORMULA)
+
+
+def _add_pert_task_values(
+    task_el: ET.Element,
+    optimistic_days: int,
+    most_likely_days: int,
+    pessimistic_days: int,
+) -> None:
+    """Emit per-task <ExtendedAttribute> values for Duration1/2/3.
+
+    Values are encoded as ISO-8601 ``PT{hours}H0M0S`` (8h working day) using
+    the same convention as the primary Duration field. ``DurationFormat=7``
+    marks the value as a duration in days for MS Project's UI.
+    """
+    for fid, days in (
+        (DURATION1_FIELD_ID, optimistic_days),
+        (DURATION2_FIELD_ID, most_likely_days),
+        (DURATION3_FIELD_ID, pessimistic_days),
+    ):
+        ea = ET.SubElement(task_el, f"{{{_NS}}}ExtendedAttribute")
+        _sub_text(ea, "FieldID", fid)
+        _sub_text(ea, "Value", _days_to_duration(days))
+        _sub_text(ea, "DurationFormat", "7")

trueppm_api/apps/msproject/extended_attributes.py

@@ -0,0 +1,77 @@
+"""MS Project ExtendedAttribute FieldID constants and PERT mapping.
+
+These FieldIDs are the canonical MS Project Custom Field identifiers for the
+idiomatic three-point / PERT estimate convention. They are sourced from MPXJ's
+``TaskField`` enum (via the mpp-sample-generator's ``field_id_reference.md``)
+and cross-checked against Microsoft's one documented anchor:
+``pjCustomTaskText1 = 188743731``
+(https://learn.microsoft.com/en-us/previous-versions/office/developer/office-2007/bb968474(v=office.12)).
+
+The Duration family is **non-contiguous** within the Custom Field enumeration:
+``Duration1``–``Duration3`` sit at 188743783–785 (contiguous), but ``Duration4``
+(the PERT-Expected formula slot) lives 170 IDs higher at 188743955, in a
+separate sub-range. Inferring one Duration FieldID by offset arithmetic from
+another is wrong. Use these named constants — never a range.
+
+ADR-0093 covers the import/export mapping decisions (alias-vs-FieldID
+precedence, all-or-none rule, summary/milestone skipping, round-trip
+tolerance).
+"""
+
+from __future__ import annotations
+
+# Locked FieldIDs (sourced, not guessed). Strings because MSPDI carries them
+# as text and we compare against text from the parsed XML.
+DURATION1_FIELD_ID = "188743783"  # Optimistic
+DURATION2_FIELD_ID = "188743784"  # Most Likely
+DURATION3_FIELD_ID = "188743785"  # Pessimistic
+DURATION4_FIELD_ID = "188743955"  # PERT Expected (formula slot, not imported)
+
+# Semantic role -> FieldID. Duration4 is informational only: the formula slot
+# is derived from the other three at file-read time by MS Project, so the
+# importer never reads its value. The exporter still emits the definition so
+# Project knows the alias and formula.
+PERT_FIELD_IDS: dict[str, str] = {
+    "optimistic": DURATION1_FIELD_ID,
+    "most_likely": DURATION2_FIELD_ID,
+    "pessimistic": DURATION3_FIELD_ID,
+    "expected": DURATION4_FIELD_ID,
+}
+
+# FieldID -> the role it should play (used during import to recognize standard
+# definitions).
+PERT_ROLE_BY_FIELD_ID: dict[str, str] = {v: k for k, v in PERT_FIELD_IDS.items()}
+
+# Canonical alias labels emitted on export.
+PERT_ALIAS_LABELS: dict[str, str] = {
+    DURATION1_FIELD_ID: "Optimistic",
+    DURATION2_FIELD_ID: "Most Likely",
+    DURATION3_FIELD_ID: "Pessimistic",
+    DURATION4_FIELD_ID: "PERT Expected",
+}
+
+# Canonical FieldName labels (Duration1..4). MS Project uses these as the
+# native field identifiers; the Alias is the user-visible label.
+PERT_FIELD_NAMES: dict[str, str] = {
+    DURATION1_FIELD_ID: "Duration1",
+    DURATION2_FIELD_ID: "Duration2",
+    DURATION3_FIELD_ID: "Duration3",
+    DURATION4_FIELD_ID: "Duration4",
+}
+
+# Duration4 carries the PERT expected formula so MS Project re-derives the
+# value on file open. Not a TruePPM field.
+PERT_EXPECTED_FORMULA = "([Duration1] + 4*[Duration2] + [Duration3]) / 6"
+
+# Substring tokens for alias confirmation (case-insensitive, first-match).
+# These let us spot when a file has repurposed Duration1/2/3 with an alias
+# that explicitly contradicts the PERT role (e.g. Duration1 aliased
+# "Risk Score") and refuse the import for that field rather than silently
+# treat unrelated values as estimates. Empty / missing aliases are treated
+# as "no contradiction" — we trust the FieldID.
+PERT_ALIAS_TOKENS: dict[str, tuple[str, ...]] = {
+    DURATION1_FIELD_ID: ("optimistic",),
+    DURATION2_FIELD_ID: ("most likely", "most-likely"),
+    DURATION3_FIELD_ID: ("pessimistic",),
+    DURATION4_FIELD_ID: ("pert", "expected"),
+}