trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/projects/backfill.py

@@ -0,0 +1,287 @@
+"""Data-backfill helpers for the projects app migrations.
+
+These functions are extracted from migration files so tests can import them
+without coupling to migration file names, which break on squash (CLAUDE.md rule 3).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, NamedTuple
+
+from django.db.models import Count, F
+
+logger = logging.getLogger(__name__)
+
+
+def backfill_risk_short_ids(apps: Any, schema_editor: Any) -> None:
+    """Renumber existing risks to a contiguous decimal sequence per project (#929).
+
+    Existing risks carry 8-char hex short_ids allocated from the shared
+    ``object_sequence`` — the bug behind every register row collapsing to
+    ``R-0000``. For each project, order *all* risks (including soft-deleted ones)
+    by ``created_at`` and assign ``1, 2, 3 …`` as the new decimal ``short_id``,
+    then set ``project.risk_sequence`` to the high-water mark so new risks never
+    reuse a number.
+
+    Soft-deleted risks are included in the ordering on purpose: the VoC panel
+    required immutability with *no reuse after deletion* (deletion leaves a gap —
+    "where is R-8?" is an expected audit finding, not a bug). Numbering only the
+    live rows would silently re-pack the sequence and reuse a dead risk's number.
+
+    ``server_version`` is bumped on every renumbered risk so offline/mobile
+    clients re-pull the corrected identifier on their next sync delta. The writes
+    use bulk ``.update()`` / ``bulk_update()`` — a one-time data correction, not
+    an audited user edit, so they intentionally leave no HistoricalRisk rows
+    (matching the 0071 backfill precedent).
+    """
+    Project = apps.get_model("projects", "Project")
+    Risk = apps.get_model("projects", "Risk")
+
+    for project_id in Project.objects.values_list("pk", flat=True):
+        risks = list(Risk.objects.filter(project_id=project_id).order_by("created_at", "pk"))
+        if not risks:
+            continue
+
+        # Two-pass renumber. ``unique_risk_short_id_per_project`` is a plain
+        # (non-deferrable) UniqueConstraint, so Postgres checks it per-row inside
+        # the bulk UPDATE. Writing the final decimals in one pass is only safe
+        # because legacy hex short_ids can't equal a bare decimal — but a
+        # mixed-version deploy window (new app code minting decimal short_ids
+        # before this migration runs) could break that assumption and abort the
+        # migration with an IntegrityError. Routing through a sentinel namespace
+        # that is disjoint from BOTH legacy hex (uppercase ``[0-9A-F]``) and the
+        # final decimals (the lowercase ``x`` prefix guarantees this) makes the
+        # renumber collision-proof regardless of the starting values.
+        for seq, risk in enumerate(risks, start=1):
+            risk.short_id = f"x{seq:07d}"
+        Risk.objects.bulk_update(risks, ["short_id"], batch_size=2000)
+        for seq, risk in enumerate(risks, start=1):
+            risk.short_id = str(seq)
+        Risk.objects.bulk_update(risks, ["short_id"], batch_size=2000)
+
+        # Bump server_version so sync clients see the changed short_id. Done as a
+        # single bulk UPDATE per project rather than per-row save().
+        Risk.objects.filter(project_id=project_id).update(server_version=F("server_version") + 1)
+        Project.objects.filter(pk=project_id).update(risk_sequence=len(risks))
+
+
+def _backfill_wbs_paths(apps: Any, schema_editor: object) -> None:
+    """Assign sequential root-level wbs_path values to tasks that have none (#138).
+
+    Tasks with null wbs_path have no hierarchy information (parent_id is derived
+    from wbs_path, not stored separately), so they are assigned sequential
+    root-level paths within their project, ordered by short_id (project-scoped
+    insertion order).
+    """
+    Task = apps.get_model("projects", "Task")
+
+    # Order by short_id, not pk: Task.id is a UUID (random), so pk ordering is
+    # non-deterministic. short_id is allocated from Project.object_sequence on
+    # INSERT and zero-padded to 8 hex digits, so its lexicographic order matches
+    # creation order within a project. Backfill from migration 0015 ensures
+    # every pre-existing Task has a short_id assigned.
+    null_tasks = (
+        Task.objects.filter(wbs_path__isnull=True, is_deleted=False)
+        .order_by("project_id", "short_id")
+        .values_list("id", "project_id")
+    )
+
+    project_root_counts: dict[Any, int] = {}
+    updates = []
+    for task_id, project_id in null_tasks:
+        # Count existing root-level tasks (wbs_path matches ^\d+$) for this project.
+        # Computed once per project and cached; the update list preserves order so
+        # each new task sees the correct next position.
+        if project_id not in project_root_counts:
+            project_root_counts[project_id] = Task.objects.filter(
+                project_id=project_id,
+                is_deleted=False,
+                wbs_path__isnull=False,
+                wbs_path__regex=r"^\d+$",
+            ).count()
+        project_root_counts[project_id] += 1
+        updates.append((task_id, str(project_root_counts[project_id])))
+
+    for task_id, new_path in updates:
+        Task.objects.filter(id=task_id).update(wbs_path=new_path)
+
+
+class RepairedWbsPath(NamedTuple):
+    """One row moved off a duplicated ``wbs_path`` by :func:`repair_duplicate_wbs_paths`."""
+
+    project_id: str
+    task_id: str
+    old_path: str
+    new_path: str
+    kept_task_id: str
+    #: Live rows under ``old_path`` that stayed with the kept task. See the
+    #: function docstring — they are ambiguous by construction, not merely unmoved.
+    stranded_descendants: int
+
+
+def _free_sibling_path(taken: set[str], prefix: str, start: int) -> tuple[str, int]:
+    """The next unused path under ``prefix``, and the ordinal to resume searching from.
+
+    ``taken`` is every live path already claimed in the project, including the ones
+    this repair has just handed out — so two duplicates in the same group cannot
+    collide with each other.
+    """
+    ordinal = start
+    while True:
+        candidate = f"{prefix}{ordinal}" if prefix else str(ordinal)
+        if candidate not in taken:
+            return candidate, ordinal + 1
+        ordinal += 1
+
+
+def repair_duplicate_wbs_paths(task_model: Any) -> list[RepairedWbsPath]:
+    """Re-path duplicate live ``(project, wbs_path)`` rows and report every move (#3068).
+
+    Migration ``0148`` adds ``unique_task_wbs_path_per_project_live`` as an
+    ``ExclusionConstraint``. ``AddConstraint`` builds and **validates** the GiST index
+    against every existing row, so on a database that already holds two live tasks
+    sharing a path, ``migrate`` aborts. Migrations run on container start, which makes
+    that an upgrade crash-loop rather than an error an operator can step around — and
+    the state is not hypothetical. It is exactly the corruption #3048 was filed to stop,
+    which any database running the pre-#3048 code could have accumulated (#3061 and the
+    three importer paths in #3069 are the known producers).
+
+    Repairing rather than refusing is deliberate: refusing leaves the operator with a
+    crash loop and no tooling to get out of it. But rows are being moved out from under
+    them, so **every move is logged at WARNING here**, not by the caller. A silent
+    reshuffle of someone's WBS would be worse than failing loudly, and the migration
+    output is the only record the operator will have — so the log is part of this
+    function's contract and is testable with it, rather than living in the migration
+    wrapper where CLAUDE.md rule 3 forbids a test from reaching it.
+
+    **Which row keeps the path.** #3068 proposed "oldest ``created_at``, tie-break on
+    ``pk``". ``Task`` has no ``created_at`` — it carries ``blocked_since``,
+    ``status_changed_at``, ``deleted_at``, ``seeded_at`` and ``edited_at``, none of
+    which is a creation stamp and each of which is null on most rows. The rule used is
+    **lowest ``sync_seq``, then lowest ``id``**: ``sync_seq`` is the owning project's
+    monotonic write cursor (ADR-0686), so the row that reached the project's sequence
+    first keeps the path — the closest thing to "created first" this table records.
+    Both terms are stable, so repairing the same database twice, or two replicas of it,
+    produces identical output.
+
+    **Descendant count deliberately does not enter the rule, and that is the crux.** The
+    instinct is "keep whichever row owns the subtree" — but descendants are addressed BY
+    PATH, and every row in a duplicate group shares the path. A row at ``4.2.1`` is a
+    child of "the ``4.2`` in this project"; when there are two of those, nothing in the
+    data says which. The count is identical for every candidate and cannot rank them.
+    Using it would look principled while sorting on a constant.
+
+    So the subtree stays with the kept row, and the moved row becomes childless at its
+    new path. That is a real consequence for the operator, which is why the count rides
+    back on :attr:`RepairedWbsPath.stranded_descendants` instead of being dropped.
+
+    A moved row is re-pathed among its **own siblings** — ``4.2`` becomes ``4.9``, not a
+    new root — so it stays inside the phase a planner put it in. A root-level duplicate
+    shifts to a free root ordinal past the project's current max, the same rule
+    ``root_ordinal_offset()`` applies to template adoption, so repaired and seeded rows
+    agree about what "the next free root" means.
+
+    Takes the model class rather than reaching for ``Task`` directly so the migration can
+    pass its historical model and a test can pass the real one (CLAUDE.md rule 3: never
+    import a migration module in a test).
+
+    On the overwhelmingly common clean database this is one aggregate query and a return.
+    """
+    dupes = (
+        task_model.objects.filter(is_deleted=False, wbs_path__isnull=False)
+        .values("project_id", "wbs_path")
+        .annotate(n=Count("id"))
+        .filter(n__gt=1)
+    )
+    affected = {(g["project_id"], str(g["wbs_path"])) for g in dupes}
+    if not affected:
+        return []
+
+    repaired: list[RepairedWbsPath] = []
+
+    for project_id in sorted({pid for pid, _ in affected}, key=str):
+        rows = list(
+            task_model.objects.filter(
+                project_id=project_id, is_deleted=False, wbs_path__isnull=False
+            ).values("id", "wbs_path", "sync_seq")
+        )
+        taken = {str(r["wbs_path"]) for r in rows}
+
+        by_path: dict[str, list[dict[str, Any]]] = {}
+        for row in rows:
+            by_path.setdefault(str(row["wbs_path"]), []).append(row)
+
+        # Live descendants per path — for the operator-facing report ONLY, never for
+        # the keep rule (see the docstring). A path's descendants are the rows whose
+        # path starts with it plus a separator; the string test is exact because an
+        # ltree label cannot contain a dot.
+        descendants = {
+            path: sum(len(v) for p, v in by_path.items() if p.startswith(path + "."))
+            for path in by_path
+        }
+
+        # Resume the ordinal search per prefix so a group of three duplicates does not
+        # rescan from 1 for each move.
+        next_ordinal: dict[str, int] = {}
+
+        for path in sorted(p for pid, p in affected if pid == project_id):
+            group = by_path.get(path, [])
+            if len(group) < 2:
+                continue
+            # Earliest position in the project's write sequence keeps the path; the pk
+            # breaks a tie. Both are stable, so this is reproducible.
+            group.sort(key=lambda r: (r["sync_seq"], str(r["id"])))
+            keeper, movers = group[0], group[1:]
+
+            head, _, _ = path.rpartition(".")
+            prefix = f"{head}." if head else ""
+            start = next_ordinal.get(prefix, 1)
+
+            for mover in movers:
+                new_path, start = _free_sibling_path(taken, prefix, start)
+                taken.add(new_path)
+                task_model.objects.filter(pk=mover["id"]).update(wbs_path=new_path)
+                repaired.append(
+                    RepairedWbsPath(
+                        project_id=str(project_id),
+                        task_id=str(mover["id"]),
+                        old_path=path,
+                        new_path=new_path,
+                        kept_task_id=str(keeper["id"]),
+                        stranded_descendants=descendants.get(path, 0),
+                    )
+                )
+            next_ordinal[prefix] = start
+
+    _log_repairs(repaired)
+    return repaired
+
+
+def _log_repairs(repaired: list[RepairedWbsPath]) -> None:
+    """Report every moved row at WARNING. See :func:`repair_duplicate_wbs_paths`."""
+    if not repaired:
+        return
+    logger.warning(
+        "wbs_path repair (#3068): %d row(s) across %d project(s) shared a live WBS path "
+        "with another row and have been moved so the uniqueness constraint can be "
+        "applied. Review the moves below.",
+        len(repaired),
+        len({r.project_id for r in repaired}),
+    )
+    for row in repaired:
+        logger.warning(
+            "wbs_path repair (#3068): project=%s task=%s moved %s -> %s (kept task=%s)%s",
+            row.project_id,
+            row.task_id,
+            row.old_path,
+            row.new_path,
+            row.kept_task_id,
+            (
+                f"; {row.stranded_descendants} live row(s) under {row.old_path} stayed "
+                f"with task {row.kept_task_id} - a duplicated path makes their parent "
+                "ambiguous and nothing in the data distinguishes them"
+                if row.stranded_descendants
+                else ""
+            ),
+        )

trueppm_api/apps/projects/backlog_services.py

@@ -0,0 +1,324 @@
+"""Service layer for the program backlog pull-down (ADR-0069 Erratum, #737).
+
+The pull action is the one place where a program-level ``BacklogItem`` crosses
+into a project: it converts a PROPOSED item into a project-backlog ``Task``
+(``status=BACKLOG``, ``sprint=NULL``) and records the conversion on the item.
+Sprint sovereignty is preserved by design — pull never assigns a sprint
+(Morgan's VoC blocker, resolved in ADR-0069).
+
+Kept as a service (not inline in the view) so the atomic transition is testable
+in isolation and reusable by a future batch-pull from Sprint Planning.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from django.db import IntegrityError, transaction
+from django.db.models import Max
+from django.utils import timezone
+
+from trueppm_api.apps.projects.models import (
+    BacklogItem,
+    BacklogItemStatus,
+    BacklogItemType,
+    Label,
+    LabelColor,
+    Project,
+    Task,
+    TaskLabel,
+    TaskStatus,
+    TaskType,
+)
+
+# Map the program intake taxonomy (ADR-0069) onto the project work-item taxonomy
+# (ADR-0105). The two enums are reconciled (#1995): every intake type maps to a
+# distinct Task type so a pulled bug/spike/chore keeps its kind instead of
+# silently collapsing to a plain task. ``chore`` is the intake name for
+# ``TaskType.TECH_DEBT``; ``feature`` has no Task analogue and maps to ``TASK``.
+_ITEM_TYPE_TO_TASK_TYPE: dict[str, TaskType] = {
+    BacklogItemType.EPIC: TaskType.EPIC,
+    BacklogItemType.STORY: TaskType.STORY,
+    BacklogItemType.TASK: TaskType.TASK,
+    BacklogItemType.BUG: TaskType.BUG,
+    BacklogItemType.SPIKE: TaskType.SPIKE,
+    BacklogItemType.CHORE: TaskType.TECH_DEBT,
+    BacklogItemType.FEATURE: TaskType.TASK,
+}
+
+
+class BacklogItemNotPullable(Exception):
+    """Raised when a pull is attempted on an item that is not PROPOSED.
+
+    The view maps this to ``409 Conflict`` — the item was already pulled or
+    archived (or a concurrent pull won the row lock first).
+    """
+
+
+class CrossProgramPullError(Exception):
+    """Raised when the pull target project does not belong to the item's program.
+
+    The view maps this to ``400 Bad Request``. Single-program scoping is the OSS
+    boundary (ADR-0069): a program backlog item can only be pulled into one of
+    its own program's projects, never into another program's project.
+    """
+
+
+def pull_to_project_backlog(
+    item_id: str,
+    project: Project,
+    actor: Any,
+) -> Task:
+    """Atomically convert a PROPOSED ``BacklogItem`` into a project-backlog Task.
+
+    Locks the item ``FOR UPDATE`` and asserts it is still PROPOSED before doing
+    any work, so two concurrent pulls cannot both succeed — the loser raises
+    :class:`BacklogItemNotPullable` (→ 409). The new Task lands in the project
+    backlog (``status=BACKLOG``, ``sprint=None``); the item is flipped to PULLED
+    with ``pulled_task``/``pulled_at``/``pulled_by`` recorded. Both rows bump
+    ``server_version`` via their ``save()``.
+
+    On commit it enqueues a CPM recalculation (existing scheduling outbox — no
+    new outbox category), broadcasts a ``task_created`` board event, and fires the
+    ``task.created`` outbound webhook (#752) — matching every other Task-create
+    path so external subscribers see backlog pulls like any other create. All
+    three are deferred with ``transaction.on_commit`` so a rolled-back pull never
+    leaks a recalc request, a phantom WS event, or a webhook delivery.
+
+    Args:
+        item_id: PK of the ``BacklogItem`` to pull.
+        project: The resolved target ``Project`` (must belong to the item's program).
+        actor: The user performing the pull (recorded as ``pulled_by``).
+
+    Returns:
+        The created project-backlog ``Task``.
+
+    Raises:
+        BacklogItem.DoesNotExist: if no such item exists.
+        CrossProgramPullError: if ``project`` is not in the item's program.
+        BacklogItemNotPullable: if the item is not in PROPOSED status.
+    """
+    # Call-time import (not module-level) to avoid a views→services→views cycle.
+    # By the time this service runs, the app is fully loaded, so reusing the
+    # canonical task payload builder keeps the pull's task.created shape identical
+    # to the REST create path with zero drift risk.
+    from trueppm_api.apps.access.permissions import assert_project_not_archived
+    from trueppm_api.apps.projects.views import _task_webhook_payload
+    from trueppm_api.apps.scheduling.services import enqueue_recalculate
+    from trueppm_api.apps.sync.broadcast import broadcast_board_event
+    from trueppm_api.apps.webhooks.dispatch import dispatch_webhooks
+
+    # A pull creates a Task, and archived plans take no writes (#3354). The view
+    # checks this too, but archived is lifecycle state — a property of the target
+    # plan, not of the caller — so it holds for every caller rather than only for
+    # one that arrives through DRF. Every caller is a view today; the point is that
+    # nothing makes that stay true. Placed before the transaction so nothing is
+    # opened on a write that must not happen.
+    assert_project_not_archived(project.pk)
+
+    new_label_ids: list[str] = []
+    with transaction.atomic():
+        item = BacklogItem.objects.select_for_update().get(pk=item_id, is_deleted=False)
+
+        if project.program_id != item.program_id:
+            raise CrossProgramPullError("The target project is not part of this program.")
+
+        if item.status != BacklogItemStatus.PROPOSED:
+            raise BacklogItemNotPullable(
+                f"This item is '{item.status}' and can no longer be pulled."
+            )
+
+        task = Task.objects.create(
+            project=project,
+            name=item.title,
+            # BacklogItem.description maps to Task.notes — Task has no separate
+            # description field; the Board/drawer render notes as the body.
+            notes=item.description,
+            story_points=item.story_points,
+            # The PO's intake ordering is the whole point of ranking a program
+            # backlog, and it is not reconstructable after the crossing — there is
+            # no un-pull endpoint, so a lost rank cannot be recovered by undoing.
+            # Both fields are nullable PositiveIntegerFields meaning "lower = higher
+            # priority", so the raw value carries: it preserves relative order among
+            # items pulled from the same pool. Ranks are not unique and ties already
+            # break on a secondary sort, so colliding with an existing project task's
+            # rank is harmless — whereas leaving it null sorts the pulled item last
+            # (the 9999 client sentinel), which is the defect (#2906).
+            priority_rank=item.priority_rank,
+            status=TaskStatus.BACKLOG,
+            sprint=None,
+            # ADR-0105: carry the intake item's type into the project work-item
+            # taxonomy so a pulled story/bug/spike keeps its kind. The taxonomies
+            # are reconciled (#1995), so ``.get`` always hits; the TASK fallback is
+            # defensive only (an unknown value can no longer be created).
+            type=_ITEM_TYPE_TO_TASK_TYPE.get(item.item_type, TaskType.TASK),
+        )
+
+        # Carry the intake item's free-text tags onto the task as project labels
+        # (#1992) so a PO's thematic grouping survives the crossing. Runs inside
+        # the atomic block so a rolled-back pull leaves no orphan labels.
+        new_label_ids = _apply_tags_as_labels(task, project, item.tags, actor)
+
+        item.status = BacklogItemStatus.PULLED
+        item.pulled_task = task
+        item.pulled_at = timezone.now()
+        item.pulled_by = actor if getattr(actor, "is_authenticated", False) else None
+        # server_version is bumped automatically by VersionedModel.save() (it is
+        # stripped from update_fields and incremented via F()), so it is omitted here.
+        item.save(update_fields=["status", "pulled_task", "pulled_at", "pulled_by"])
+
+    project_id = str(project.pk)
+    task_id = str(task.pk)
+    # source="backlog_pull" tells external consumers which surface originated the
+    # create (ADR-0065 X-Source semantics) so a pull is distinguishable from a
+    # board/schedule/sync create on the same task.created event.
+    webhook_payload = _task_webhook_payload(task, source="backlog_pull")
+    # CPM recalc via the existing scheduling outbox (ADR-0027). A BACKLOG task is
+    # excluded from the CPM graph, so this coalesces to a no-op run today, but we
+    # keep it on the standard Task-create path for consistency and forward-safety.
+    transaction.on_commit(lambda: enqueue_recalculate(project_id))
+    transaction.on_commit(
+        lambda: broadcast_board_event(project_id, "task_created", {"id": task_id})
+    )
+
+    # Any labels coined from the item's tags are new project vocabulary — tell open
+    # boards/label managers so they can render the pulled task's pills (#1992). Bind
+    # the id through a function arg so closure late-binding can't collapse the loop's
+    # events to the last id.
+    def _broadcast_label(lid: str) -> None:
+        transaction.on_commit(
+            lambda: broadcast_board_event(project_id, "label_created", {"id": lid})
+        )
+
+    for _label_id in new_label_ids:
+        _broadcast_label(_label_id)
+
+    # Bind the payload via a default arg so closure late-binding can never swap it
+    # if this function grows more branches later (matches inbound_sync.py).
+    def _dispatch(pid: str = project_id, wp: dict[str, Any] = webhook_payload) -> None:
+        dispatch_webhooks(pid, "task.created", wp)
+
+    transaction.on_commit(_dispatch)
+    return task
+
+
+def _apply_tags_as_labels(
+    task: Task,
+    project: Project,
+    tags: list[str],
+    actor: Any,
+) -> list[str]:
+    """Carry a pulled item's free-text tags onto the task as project labels (#1992).
+
+    Each tag becomes — or, case-insensitively, reuses — a project-scoped ``Label``
+    and is attached to ``task`` via ``TaskLabel``. Reuse keeps the catalog from
+    sprouting a near-duplicate on every pull; new labels take the neutral default
+    slot (``SLATE``) appended to the end of the palette order, which a project admin
+    can recolor later. Idempotent per tag via ``TaskLabel.get_or_create``.
+
+    Must be called inside the pull's ``transaction.atomic`` block so a rolled-back
+    pull leaves no orphan labels. The label soft cap is honored: once the project is
+    at the ceiling, further *new* tags are skipped (existing matches still attach) so
+    a pull can never blow past the curation floor the ``LabelViewSet`` enforces.
+
+    Args:
+        task: The freshly created project-backlog Task to label.
+        project: The task's project (labels are project-scoped).
+        tags: The item's tags — already normalized (trimmed, de-duped) by the
+            serializer's ``validate_tags``.
+        actor: The pulling user, recorded as ``created_by`` on any new label.
+
+    Returns:
+        The ids of labels *created* here (not reused), so the caller can broadcast
+        ``label_created`` once the transaction commits.
+    """
+    if not tags:
+        return []
+    # Call-time import mirrors the pull's views import — avoids a services→views cycle.
+    from trueppm_api.apps.projects.views import _label_soft_cap
+
+    cap = _label_soft_cap()
+    live = Label.objects.filter(project=project, is_deleted=False)
+    label_count = live.count()
+    next_position = (live.aggregate(m=Max("position"))["m"] or 0) + 1
+    creator = actor if getattr(actor, "is_authenticated", False) else None
+
+    created_ids: list[str] = []
+    for tag in tags:
+        # Label.name is capped at 50 chars; BacklogItem tags are unbounded, so clamp
+        # to keep an over-long tag from raising instead of degrading gracefully.
+        name = tag[:50]
+        existing = Label.objects.filter(
+            project=project, name__iexact=name, is_deleted=False
+        ).first()
+        if existing is not None:
+            TaskLabel.objects.get_or_create(task=task, label=existing)
+            continue
+        if label_count >= cap:
+            # At the curation ceiling — skip coining a new label but keep going;
+            # a pull must not fail because the project's label catalog is full.
+            continue
+        label, created = _coin_label(project, name, next_position, creator)
+        if label is None:
+            continue
+        if created:
+            next_position += 1
+            label_count += 1
+            created_ids.append(str(label.pk))
+        TaskLabel.objects.get_or_create(task=task, label=label)
+    return created_ids
+
+
+def _coin_label(
+    project: Project,
+    name: str,
+    position: int,
+    creator: Any,
+) -> tuple[Any, bool]:
+    """Create a new project label at ``position``, or reuse the race winner.
+
+    Returns ``(label, created)`` where ``created`` is True only when this call
+    coined the label (so the caller can bump the position/count and broadcast).
+
+    Savepoint the create so a concurrent pull that coined the same tag first raises
+    only a local IntegrityError (on uniq_label_name_per_project) instead of poisoning
+    the whole pull transaction. Without the nested atomic the outer pull would roll
+    back to a transient 500. On a lost race the other transaction's label is now
+    committed and visible; reuse it (exact-name match, since the unique constraint is
+    on exact (project, name)).
+    """
+    try:
+        with transaction.atomic():
+            label = Label.objects.create(
+                project=project,
+                name=name,
+                color=LabelColor.SLATE,
+                position=position,
+                created_by=creator,
+            )
+    except IntegrityError:
+        return Label.objects.filter(project=project, name=name, is_deleted=False).first(), False
+    return label, True
+
+
+def reset_pulled_item_on_task_delete(task_id: str) -> None:
+    """Reset a BacklogItem to PROPOSED when its pulled Task is (soft-)deleted.
+
+    Rollback path (ADR-0069): if the Task created by a pull is deleted, the
+    originating item must become re-pullable. ``pulled_task`` is ``SET_NULL`` so
+    deletion never cascades to the item; this restores the lifecycle by clearing
+    the pull bookkeeping and flipping the item back to PROPOSED.
+
+    Idempotent and a no-op when no item points at the task. Called from the Task
+    post_save soft-delete receiver (TruePPM Tasks soft-delete, not hard-delete).
+    """
+    item = BacklogItem.objects.filter(pulled_task_id=uuid.UUID(task_id), is_deleted=False).first()
+    if item is None or item.status != BacklogItemStatus.PULLED:
+        return
+    item.status = BacklogItemStatus.PROPOSED
+    item.pulled_task = None
+    item.pulled_at = None
+    item.pulled_by = None
+    # server_version auto-bumps in VersionedModel.save() — omitted from update_fields.
+    item.save(update_fields=["status", "pulled_task", "pulled_at", "pulled_by"])