sqlmirror 0.2.0__py3-none-any.whl

sqlmirror/dev/synth.py

@@ -0,0 +1,769 @@
+"""Synthetic Jira Cloud tenant.
+
+Builds an in-memory tenant whose JSON matches the Jira Cloud REST v2 shapes
+the mirror consumes: issues with system and custom fields, epics, sub-tasks,
+links, sprints, versions, components, changelogs, comments and worklogs.
+
+The same tenant is served by the mock Jira server (``mock_jira``) so the CLI
+backfill and the Forge app's sync code can both run against it, and
+``mutate`` applies realistic edits and deletions and reports the Jira events
+they would fire, so incremental sync can be tested offline.
+"""
+from __future__ import annotations
+
+import copy
+import gzip
+import json
+import random
+import string
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+SITE = "https://synthetic-sqlmirror.atlassian.net"
+EPOCH = datetime(2026, 10, 1, 12, 0, tzinfo=timezone.utc)
+
+STATUS_TODO, STATUS_PROGRESS, STATUS_REVIEW, STATUS_DONE, STATUS_WONTDO = "10000", "3", "10002", "10001", "10003"
+STATUSES = [
+    {"id": STATUS_TODO, "name": "To Do", "cat": (2, "new", "blue-gray", "To Do")},
+    {"id": STATUS_PROGRESS, "name": "In Progress", "cat": (4, "indeterminate", "yellow", "In Progress")},
+    {"id": STATUS_REVIEW, "name": "In Review", "cat": (4, "indeterminate", "yellow", "In Progress")},
+    {"id": STATUS_DONE, "name": "Done", "cat": (3, "done", "green", "Done")},
+    {"id": STATUS_WONTDO, "name": "Won't Do", "cat": (3, "done", "green", "Done")},
+]
+PRIORITIES = [("1", "Highest", "#d04437"), ("2", "High", "#f15C75"), ("3", "Medium", "#f79232"),
+              ("4", "Low", "#707070"), ("5", "Lowest", "#999999")]
+RESOLUTIONS = [("10000", "Done"), ("10001", "Won't Do"), ("10002", "Duplicate"), ("10003", "Cannot Reproduce")]
+ISSUE_TYPES = [
+    ("10000", "Epic", False, 1), ("10001", "Story", False, 0), ("10002", "Task", False, 0),
+    ("10003", "Bug", False, 0), ("10004", "Sub-task", True, -1),
+]
+LINK_TYPES = [("10000", "Blocks", "is blocked by", "blocks"), ("10001", "Cloners", "is cloned by", "clones"),
+              ("10002", "Duplicate", "is duplicated by", "duplicates"), ("10003", "Relates", "relates to", "relates to")]
+
+CFT = "com.atlassian.jira.plugin.system.customfieldtypes:"
+GH = "com.pyxis.greenhopper.jira:"
+CUSTOM_FIELDS = [
+    # (number, name, type key, schema type)
+    (10020, "Sprint", GH + "gh-sprint", "array"),
+    (10019, "Rank", GH + "gh-lexo-rank", "any"),
+    (10011, "Epic Name", GH + "gh-epic-label", "string"),
+    (10028, "Story Points", CFT + "float", "number"),
+    (10100, "Customer Impact", CFT + "select", "option"),
+    (10101, "Platforms", CFT + "multiselect", "array"),
+    (10102, "Customer", CFT + "textfield", "string"),
+    (10103, "Acceptance Criteria", CFT + "textarea", "string"),
+    (10104, "Cost", CFT + "float", "number"),
+    (10105, "Target Date", CFT + "datepicker", "date"),
+    (10106, "QA Owner", CFT + "userpicker", "user"),
+    (10107, "Region", CFT + "cascadingselect", "option-with-child"),
+    (10108, "Tags", CFT + "labels", "array"),
+    (10109, "Go-live", CFT + "datetime", "datetime"),
+    (10110, "Reviewers", CFT + "multiuserpicker", "array"),
+    (10111, "Team", "com.atlassian.jira.plugin.system.customfieldtypes:atlassian-team", "team"),
+    (10112, "Severity", CFT + "radiobuttons", "option"),
+]
+SELECT_OPTIONS = {
+    10100: [("10200", "Low"), ("10201", "Medium"), ("10202", "High"), ("10203", "Critical")],
+    10101: [("10210", "Web"), ("10211", "iOS"), ("10212", "Android"), ("10213", "Desktop")],
+    10112: [("10220", "S1"), ("10221", "S2"), ("10222", "S3"), ("10223", "S4")],
+}
+REGION_OPTIONS = {("10230", "EMEA"): [("10240", "UK"), ("10241", "Germany"), ("10242", "France")],
+                  ("10231", "AMER"): [("10243", "US"), ("10244", "Canada"), ("10245", "Brazil")],
+                  ("10232", "APAC"): [("10246", "Japan"), ("10247", "Australia"), ("10248", "India")]}
+TEAMS = [{"id": str(uuid.UUID(int=i + 1)), "name": n} for i, n in enumerate(["Platform", "Mobile", "Growth"])]
+
+FIRST = ["Ana", "Ben", "Chen", "Dana", "Eli", "Fatima", "Goran", "Hana", "Ivan", "Jia", "Kofi", "Lena",
+         "Mateo", "Nora", "Omar", "Priya", "Quinn", "Rosa", "Sven", "Tara", "Umar", "Vera", "Wei", "Xena",
+         "Yusuf", "Zoe"]
+LAST = ["Smith", "Garcia", "Kim", "Okafor", "Novak", "Silva", "Tanaka", "Muller", "Rossi", "Nguyen", "Brown",
+        "Ahmed", "Larsen", "Costa", "Ivanova"]
+WORDS = ("login checkout payment search cache api export report dashboard sync timeout crash mobile "
+         "invoice billing token session upload import permission email notification onboarding filter "
+         "sprint backlog latency memory index migration webhook audit").split()
+
+
+def jts(dt: datetime) -> str:
+    """Jira's timestamp format: 2026-01-02T10:00:00.000+0000."""
+    return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}+0000"
+
+
+def iso_z(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"
+
+
+class Tenant:
+    """A synthetic Jira Cloud site."""
+
+    def __init__(self, data: dict[str, Any]):
+        self.data = data
+
+    # ------------------------------------------------------------ persistence
+    def save(self, path: str | Path) -> None:
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with gzip.open(path, "wt", encoding="utf-8") as fh:
+            json.dump(self.data, fh)
+
+    @classmethod
+    def load(cls, path: str | Path) -> "Tenant":
+        with gzip.open(path, "rt", encoding="utf-8") as fh:
+            return cls(json.load(fh))
+
+    # --------------------------------------------------------------- helpers
+    @property
+    def issues(self) -> dict[str, dict[str, Any]]:
+        return self.data["issues"]
+
+    def user(self, account_id: str | None) -> dict[str, Any] | None:
+        if account_id is None:
+            return None
+        return copy.deepcopy(self.data["usersById"][account_id])
+
+    def issue_ref(self, iid: str) -> dict[str, Any]:
+        """The short issue object Jira embeds in parent/subtasks/issuelinks."""
+        issue = self.issues[iid]
+        f = issue["fields"]
+        return {
+            "id": iid,
+            "key": issue["key"],
+            "self": f"{SITE}/rest/api/2/issue/{iid}",
+            "fields": {
+                "summary": f["summary"],
+                "status": copy.deepcopy(f["status"]),
+                "priority": copy.deepcopy(f["priority"]),
+                "issuetype": copy.deepcopy(f["issuetype"]),
+            },
+        }
+
+    def full_fields(self, iid: str) -> dict[str, Any]:
+        """All fields as GET issue returns them, with parent/subtasks/links resolved."""
+        issue = self.issues[iid]
+        f = copy.deepcopy(issue["fields"])
+        parent_id = issue.get("_parent")
+        f["parent"] = self.issue_ref(parent_id) if parent_id and parent_id in self.issues else None
+        if f["parent"] is None:
+            f.pop("parent")
+        f["subtasks"] = [self.issue_ref(s) for s in issue.get("_subtasks", []) if s in self.issues]
+        links = []
+        for link in self.data["links"].values():
+            if link["source"] == iid and link["destination"] in self.issues:
+                links.append({"id": link["id"], "self": f"{SITE}/rest/api/2/issueLink/{link['id']}",
+                              "type": self.link_type(link["type"]), "outwardIssue": self.issue_ref(link["destination"])})
+            elif link["destination"] == iid and link["source"] in self.issues:
+                links.append({"id": link["id"], "self": f"{SITE}/rest/api/2/issueLink/{link['id']}",
+                              "type": self.link_type(link["type"]), "inwardIssue": self.issue_ref(link["source"])})
+        f["issuelinks"] = links
+        comments = self.data["comments"].get(iid, [])
+        f["comment"] = {"comments": copy.deepcopy(comments), "self": f"{SITE}/rest/api/2/issue/{iid}/comment",
+                        "maxResults": len(comments), "total": len(comments), "startAt": 0}
+        worklogs = self.data["worklogs"].get(iid, [])
+        f["worklog"] = {"startAt": 0, "maxResults": 20, "total": len(worklogs), "worklogs": copy.deepcopy(worklogs[:20])}
+        return f
+
+    def link_type(self, tid: str) -> dict[str, Any]:
+        for t in self.data["issueLinkTypes"]:
+            if t["id"] == tid:
+                return copy.deepcopy(t)
+        raise KeyError(tid)
+
+    def metadata(self) -> dict[str, Any]:
+        """The metadata document, exactly as the Forge app and the CLI build it."""
+        d = self.data
+        return {
+            "v": 1, "type": "metadata", "fetchedAt": iso_z(datetime.now(timezone.utc)),
+            "projects": copy.deepcopy(d["projects"]), "statuses": copy.deepcopy(d["statuses"]),
+            "priorities": copy.deepcopy(d["priorities"]), "resolutions": copy.deepcopy(d["resolutions"]),
+            "issueTypes": copy.deepcopy(d["issueTypes"]), "fields": copy.deepcopy(d["fields"]),
+            "issueLinkTypes": copy.deepcopy(d["issueLinkTypes"]),
+            "projectCategories": copy.deepcopy(d["projectCategories"]),
+            "versions": copy.deepcopy(d["versions"]), "components": copy.deepcopy(d["components"]),
+        }
+
+    def snapshot(self, iid: str, fetched_at: datetime | None = None) -> dict[str, Any]:
+        """A complete snapshot record, as the Forge app writes it."""
+        issue = self.issues[iid]
+        fields = self.full_fields(iid)
+        fields.pop("comment", None)
+        fields.pop("worklog", None)
+        return {
+            "v": 1, "type": "issue", "id": iid,
+            "fetchedAt": iso_z(fetched_at or datetime.now(timezone.utc)),
+            "issue": {"id": iid, "key": issue["key"], "self": f"{SITE}/rest/api/2/issue/{iid}", "fields": fields},
+            "changelog": copy.deepcopy(self.data["changelogs"].get(iid, [])),
+            "comments": copy.deepcopy(self.data["comments"].get(iid, [])),
+            "worklogs": copy.deepcopy(self.data["worklogs"].get(iid, [])),
+        }
+
+    def next_id(self, kind: str) -> str:
+        n = self.data["nextIds"][kind]
+        self.data["nextIds"][kind] = n + 1
+        return str(n)
+
+
+# ---------------------------------------------------------------- generation
+def _user(rng: random.Random, i: int) -> dict[str, Any]:
+    first, last = FIRST[i % len(FIRST)], LAST[(i * 7) % len(LAST)]
+    if i % 3 == 0:
+        account_id = "712020:" + str(uuid.UUID(int=rng.getrandbits(128)))
+    else:
+        account_id = "".join(rng.choice("0123456789abcdef") for _ in range(24))
+    user = {
+        "self": f"{SITE}/rest/api/2/user?accountId={account_id}",
+        "accountId": account_id,
+        "avatarUrls": {"48x48": "https://avatar.example/48.png"},
+        "displayName": f"{first} {last}",
+        "active": i % 17 != 5,
+        "timeZone": "Europe/London",
+        "accountType": "atlassian",
+    }
+    if i % 2 == 0:  # many sites hide email addresses
+        user["emailAddress"] = f"{first.lower()}.{last.lower()}@example.com"
+    return user
+
+
+def build_tenant(issues: int = 2000, projects: int = 3, users: int = 40, seed: int = 7,
+                 heavy_every: int = 97) -> Tenant:
+    """Generate a tenant with roughly ``issues`` issues spread over ``projects`` projects.
+
+    Every ``heavy_every``-th issue gets more than 100 changelog entries, 60
+    comments and 30 worklogs, so pagination code paths are exercised.
+    """
+    rng = random.Random(seed)
+    data: dict[str, Any] = {"site": SITE, "nextIds": {}}
+
+    user_list = [_user(rng, i) for i in range(users)]
+    data["users"] = user_list
+    data["usersById"] = {u["accountId"]: u for u in user_list}
+    active_users = [u["accountId"] for u in user_list if u["active"]]
+
+    data["projectCategories"] = [{"self": f"{SITE}/rest/api/2/projectCategory/10000", "id": "10000",
+                                  "name": "Engineering", "description": "Product engineering"},
+                                 {"self": f"{SITE}/rest/api/2/projectCategory/10001", "id": "10001",
+                                  "name": "Operations", "description": "Ops and support"}]
+
+    data["statuses"] = []
+    for s in STATUSES:
+        cid, ckey, color, cname = s["cat"]
+        data["statuses"].append({
+            "self": f"{SITE}/rest/api/2/status/{s['id']}", "description": "", "iconUrl": f"{SITE}/images/icons/statuses/generic.png",
+            "name": s["name"], "untranslatedName": s["name"], "id": s["id"],
+            "statusCategory": {"self": f"{SITE}/rest/api/2/statuscategory/{cid}", "id": cid, "key": ckey,
+                               "colorName": color, "name": cname},
+        })
+    status_by_id = {s["id"]: s for s in data["statuses"]}
+    data["priorities"] = [{"self": f"{SITE}/rest/api/2/priority/{pid}", "statusColor": color, "description": "",
+                           "iconUrl": f"{SITE}/images/icons/priorities/{name.lower()}.svg", "name": name, "id": pid,
+                           "isDefault": pid == "3"} for pid, name, color in PRIORITIES]
+    prio_by_id = {p["id"]: p for p in data["priorities"]}
+    data["resolutions"] = [{"self": f"{SITE}/rest/api/2/resolution/{rid}", "id": rid, "description": "",
+                            "name": name, "isDefault": rid == "10000"} for rid, name in RESOLUTIONS]
+    res_by_id = {r["id"]: r for r in data["resolutions"]}
+    data["issueTypes"] = [{"self": f"{SITE}/rest/api/2/issuetype/{tid}", "id": tid, "description": "",
+                           "iconUrl": f"{SITE}/images/icons/issuetypes/{name.lower()}.svg", "name": name,
+                           "untranslatedName": name, "subtask": sub, "avatarId": 10300 + int(tid) % 100,
+                           "hierarchyLevel": level} for tid, name, sub, level in ISSUE_TYPES]
+    type_by_id = {t["id"]: t for t in data["issueTypes"]}
+    data["issueLinkTypes"] = [{"id": tid, "name": name, "inward": inward, "outward": outward,
+                               "self": f"{SITE}/rest/api/2/issueLinkType/{tid}"}
+                              for tid, name, inward, outward in LINK_TYPES]
+
+    system_fields = ["summary", "description", "environment", "issuetype", "project", "status", "priority",
+                     "resolution", "assignee", "reporter", "creator", "created", "updated", "resolutiondate",
+                     "duedate", "labels", "components", "fixVersions", "versions", "timeoriginalestimate",
+                     "timeestimate", "timespent", "votes", "watches", "security", "parent", "subtasks",
+                     "issuelinks", "attachment", "comment", "worklog"]
+    data["fields"] = [{"id": f, "key": f, "name": f.capitalize(), "custom": False, "orderable": True,
+                       "navigable": True, "searchable": True, "clauseNames": [f], "schema": {"type": "any", "system": f}}
+                      for f in system_fields]
+    for num, name, typekey, stype in CUSTOM_FIELDS:
+        data["fields"].append({"id": f"customfield_{num}", "key": f"customfield_{num}", "name": name, "untranslatedName": name,
+                               "custom": True, "orderable": True, "navigable": True, "searchable": True,
+                               "clauseNames": [f"cf[{num}]", name],
+                               "schema": {"type": stype, "custom": typekey, "customId": num}})
+
+    data["projects"], data["versions"], data["components"] = [], {}, {}
+    project_keys = ["ALPHA", "BETA", "GAMMA", "DELTA", "OMEGA", "SIGMA", "THETA", "KAPPA"]
+    version_id, comp_id = 10000, 10000
+    for p in range(projects):
+        pid = str(10000 + p)
+        key = project_keys[p % len(project_keys)] + ("" if p < len(project_keys) else str(p))
+        lead = data["usersById"][active_users[p % len(active_users)]]
+        cat = data["projectCategories"][p % 2]
+        data["projects"].append({
+            "self": f"{SITE}/rest/api/2/project/{pid}", "id": pid, "key": key, "name": key.capitalize() + " Project",
+            "description": f"The {key.lower()} product", "lead": copy.deepcopy(lead),
+            "projectTypeKey": "software", "simplified": False, "style": "classic", "isPrivate": False,
+            "projectCategory": copy.deepcopy(cat), "avatarUrls": {},
+        })
+        versions = []
+        for v in range(5):
+            released = v < 3
+            start = EPOCH - timedelta(days=360 - v * 90)
+            versions.append({"self": f"{SITE}/rest/api/2/version/{version_id}", "id": str(version_id),
+                             "name": f"{key} {v + 1}.0", "description": f"Release {v + 1}", "archived": v == 0,
+                             "released": released, "startDate": start.strftime("%Y-%m-%d"),
+                             "releaseDate": (start + timedelta(days=85)).strftime("%Y-%m-%d"),
+                             "projectId": int(pid)})
+            version_id += 1
+        data["versions"][pid] = versions
+        comps = []
+        for name in ("Backend", "Frontend", "API", "Infra"):
+            comps.append({"self": f"{SITE}/rest/api/2/component/{comp_id}", "id": str(comp_id), "name": name,
+                          "description": f"{name} work", "lead": copy.deepcopy(data["usersById"][rng.choice(active_users)]),
+                          "assigneeType": "PROJECT_DEFAULT", "project": key, "projectId": int(pid)})
+            comp_id += 1
+        data["components"][pid] = comps
+
+    # Sprints: one board per project, two-week sprints.
+    sprints_by_project: dict[str, list[dict[str, Any]]] = {}
+    sprint_id = 1
+    for p, proj in enumerate(data["projects"]):
+        sprints = []
+        start = EPOCH - timedelta(days=392)
+        n = 0
+        while start < EPOCH + timedelta(days=14):
+            n += 1
+            end = start + timedelta(days=14)
+            if end <= EPOCH:
+                state = "closed"
+            elif start <= EPOCH:
+                state = "active"
+            else:
+                state = "future"
+            s = {"id": sprint_id, "name": f"{proj['key']} Sprint {n}", "state": state, "boardId": p + 1,
+                 "goal": f"Sprint {n} goal" if n % 3 == 0 else "", "_start": start, "_end": end}
+            if state != "future":
+                s["startDate"] = iso_z(start)
+                s["endDate"] = iso_z(end)
+            if state == "closed":
+                s["completeDate"] = iso_z(end - timedelta(hours=2))
+            sprints.append(s)
+            sprint_id += 1
+            start = end
+        sprints_by_project[proj["id"]] = sprints
+    data["sprints"] = {pid: [{k: (iso_z(v) if isinstance(v, datetime) else v) for k, v in s.items()} for s in sl]
+                       for pid, sl in sprints_by_project.items()}
+
+    data["issues"], data["changelogs"], data["comments"], data["worklogs"], data["links"] = {}, {}, {}, {}, {}
+    ids = {"issue": 10000, "history": 20000, "comment": 30000, "worklog": 40000, "attachment": 50000, "link": 60000}
+    counters = {proj["id"]: 0 for proj in data["projects"]}
+    epics: dict[str, list[str]] = {proj["id"]: [] for proj in data["projects"]}
+    parents: dict[str, list[str]] = {proj["id"]: [] for proj in data["projects"]}
+
+    def new_id(kind: str) -> str:
+        ids[kind] += 1
+        return str(ids[kind])
+
+    def sentence(n: int) -> str:
+        return " ".join(rng.choice(WORDS) for _ in range(n)).capitalize()
+
+    def sprint_value(proj_id: str, created: datetime) -> list[dict[str, Any]]:
+        out = []
+        for s in sprints_by_project[proj_id]:
+            if s["_end"] > created and len(out) < 3 and rng.random() < (0.9 if not out else 0.35):
+                out.append({k: v for k, v in data["sprints"][proj_id][sprints_by_project[proj_id].index(s)].items()})
+            if out and rng.random() < 0.5:
+                break
+        return out
+
+    for n in range(issues):
+        proj = data["projects"][n % len(data["projects"])]
+        pid = proj["id"]
+        counters[pid] += 1
+        iid = new_id("issue")
+        key = f"{proj['key']}-{counters[pid]}"
+        created = EPOCH - timedelta(days=rng.uniform(1, 390), minutes=rng.randint(0, 1440))
+        r = rng.random()
+        if r < 0.05 or not epics[pid]:
+            tid = "10000"
+        elif r < 0.10 and parents[pid]:
+            tid = "10004"
+        else:
+            tid = rng.choice(["10001", "10001", "10002", "10003"])
+        itype = type_by_id[tid]
+        heavy = n % heavy_every == heavy_every - 1
+        reporter = rng.choice(active_users)
+        assignee = rng.choice(active_users) if rng.random() < 0.85 else None
+        prio = rng.choice(["2", "3", "3", "3", "4", "1", "5"])
+
+        histories: list[dict[str, Any]] = []
+        t = created
+        status = STATUS_TODO
+        resolution = None
+        resolutiondate = None
+
+        def history(author: str, when: datetime, items: list[dict[str, Any]]) -> None:
+            histories.append({"id": new_id("history"), "author": copy.deepcopy(data["usersById"][author]),
+                              "created": jts(when), "items": items})
+
+        path = [STATUS_PROGRESS, STATUS_REVIEW, STATUS_DONE]
+        if rng.random() < 0.15:
+            path = [STATUS_PROGRESS, STATUS_REVIEW, STATUS_PROGRESS, STATUS_REVIEW, STATUS_DONE]
+        steps = rng.choice([0, 1, 2, len(path), len(path), len(path)])
+        if heavy:
+            steps = len(path)
+        for nxt in path[:steps]:
+            t = t + timedelta(hours=rng.uniform(2, 24 * 6))
+            if t > EPOCH:
+                break
+            items = [{"field": "status", "fieldtype": "jira", "fieldId": "status", "from": status,
+                      "fromString": status_by_id[status]["name"], "to": nxt, "toString": status_by_id[nxt]["name"]}]
+            if nxt == STATUS_DONE:
+                resolution = "10000" if rng.random() < 0.9 else "10001"
+                if resolution == "10001":
+                    nxt = STATUS_WONTDO
+                    items[0]["to"], items[0]["toString"] = nxt, status_by_id[nxt]["name"]
+                items.append({"field": "resolution", "fieldtype": "jira", "fieldId": "resolution", "from": None,
+                              "fromString": None, "to": resolution, "toString": res_by_id[resolution]["name"]})
+                resolutiondate = t
+            history(assignee or reporter, t, items)
+            status = nxt
+        if assignee and rng.random() < 0.3:
+            t2 = created + timedelta(hours=rng.uniform(1, 30))
+            other = rng.choice(active_users)
+            history(reporter, min(t2, EPOCH), [{"field": "assignee", "fieldtype": "jira", "fieldId": "assignee",
+                                                 "from": None, "fromString": data["usersById"][other]["displayName"],
+                                                 "to": None, "toString": data["usersById"][assignee]["displayName"],
+                                                 "tmpFromAccountId": other, "tmpToAccountId": assignee}])
+        if heavy:
+            for k in range(110):
+                when = created + timedelta(minutes=10 * (k + 1))
+                history(reporter, min(when, EPOCH), [{"field": "summary", "fieldtype": "jira", "fieldId": "summary",
+                                                      "from": None, "fromString": f"Draft {k}", "to": None,
+                                                      "toString": f"Draft {k + 1}"}])
+        histories.sort(key=lambda h: h["created"])
+
+        updated = max([created] + [datetime.fromisoformat(h["created"].replace("+0000", "+00:00")) for h in histories])
+
+        fields: dict[str, Any] = {
+            "summary": sentence(rng.randint(3, 8)),
+            "description": (f"h2. Context\n{sentence(12)}.\n\n* {sentence(5)}\n* {sentence(4)}"
+                            if rng.random() < 0.8 else None),
+            "environment": "Production" if rng.random() < 0.1 else None,
+            "issuetype": copy.deepcopy(itype),
+            "project": {"self": proj["self"], "id": pid, "key": proj["key"], "name": proj["name"],
+                        "projectTypeKey": "software", "simplified": False, "avatarUrls": {},
+                        "projectCategory": copy.deepcopy(proj["projectCategory"])},
+            "status": copy.deepcopy(status_by_id[status]),
+            "priority": copy.deepcopy(prio_by_id[prio]),
+            "resolution": copy.deepcopy(res_by_id[resolution]) if resolution else None,
+            "assignee": copy.deepcopy(data["usersById"][assignee]) if assignee else None,
+            "reporter": copy.deepcopy(data["usersById"][reporter]),
+            "creator": copy.deepcopy(data["usersById"][reporter]),
+            "created": jts(created),
+            "updated": jts(updated),
+            "resolutiondate": jts(resolutiondate) if resolutiondate else None,
+            "duedate": (created + timedelta(days=rng.randint(5, 60))).strftime("%Y-%m-%d") if rng.random() < 0.3 else None,
+            "labels": sorted(set(rng.sample(WORDS, rng.randint(0, 3)))),
+            "components": [{"self": c["self"], "id": c["id"], "name": c["name"]}
+                           for c in rng.sample(data["components"][pid], rng.randint(0, 2))],
+            "fixVersions": [],
+            "versions": [],
+            "timeoriginalestimate": rng.choice([None, 3600, 7200, 14400, 28800]),
+            "timeestimate": None,
+            "timespent": None,
+            "votes": {"self": f"{SITE}/rest/api/2/issue/{key}/votes", "votes": rng.randint(0, 3), "hasVoted": False},
+            "watches": {"self": f"{SITE}/rest/api/2/issue/{key}/watchers", "watchCount": rng.randint(1, 5),
+                        "isWatching": False},
+            "security": None,
+            "attachment": [],
+        }
+        released = [v for v in data["versions"][pid] if v["released"]]
+        if resolution and rng.random() < 0.7:
+            v = rng.choice(released)
+            fields["fixVersions"] = [{k: v[k] for k in ("self", "id", "name", "archived", "released", "releaseDate")}]
+            history(assignee or reporter, resolutiondate or created, [{
+                "field": "Fix Version", "fieldtype": "jira", "fieldId": "fixVersions", "from": None, "fromString": None,
+                "to": v["id"], "toString": v["name"]}])
+        if tid == "10003" and rng.random() < 0.6:
+            v = rng.choice(released)
+            fields["versions"] = [{k: v[k] for k in ("self", "id", "name", "archived", "released", "releaseDate")}]
+
+        # Custom fields
+        if tid != "10000":
+            sv = sprint_value(pid, created)
+            fields["customfield_10020"] = [{k: v for k, v in s.items() if not k.startswith("_")} for s in sv] or None
+            if len(sv) > 1:
+                history(reporter, min(created + timedelta(days=14), EPOCH), [{
+                    "field": "Sprint", "fieldtype": "custom", "fieldId": "customfield_10020",
+                    "from": str(sv[0]["id"]), "fromString": sv[0]["name"],
+                    "to": ", ".join(str(s["id"]) for s in sv[:2]),
+                    "toString": ", ".join(s["name"] for s in sv[:2])}])
+        else:
+            fields["customfield_10011"] = sentence(2)
+        fields["customfield_10019"] = "0|i" + "".join(rng.choice(string.ascii_lowercase + string.digits) for _ in range(5)) + ":"
+        if tid in ("10001", "10002", "10003"):
+            sp = rng.choice([None, 1, 2, 3, 5, 8, 13])
+            fields["customfield_10028"] = float(sp) if sp is not None else None
+            if sp is not None and rng.random() < 0.3:
+                history(reporter, created + timedelta(minutes=5), [{
+                    "field": "Story Points", "fieldtype": "custom", "fieldId": "customfield_10028",
+                    "from": None, "fromString": None, "to": None, "toString": str(sp)}])
+        if rng.random() < 0.6:
+            oid, val = rng.choice(SELECT_OPTIONS[10100])
+            fields["customfield_10100"] = {"self": f"{SITE}/rest/api/2/customFieldOption/{oid}", "value": val, "id": oid}
+        if rng.random() < 0.5:
+            fields["customfield_10101"] = [{"self": f"{SITE}/rest/api/2/customFieldOption/{oid}", "value": val, "id": oid}
+                                           for oid, val in rng.sample(SELECT_OPTIONS[10101], rng.randint(1, 3))]
+        if rng.random() < 0.4:
+            fields["customfield_10102"] = rng.choice(["Acme Corp", "Globex", "Initech", "Umbrella", "Hooli"])
+        if rng.random() < 0.4:
+            fields["customfield_10103"] = f"* {sentence(6)}\n* {sentence(5)}"
+        if rng.random() < 0.3:
+            fields["customfield_10104"] = round(rng.uniform(10, 5000), 2)
+        if rng.random() < 0.3:
+            fields["customfield_10105"] = (created + timedelta(days=rng.randint(10, 90))).strftime("%Y-%m-%d")
+        if rng.random() < 0.4:
+            fields["customfield_10106"] = copy.deepcopy(data["usersById"][rng.choice(active_users)])
+        if rng.random() < 0.35:
+            (poid, pval), children = rng.choice(list(REGION_OPTIONS.items()))
+            coid, cval = rng.choice(children)
+            fields["customfield_10107"] = {"self": f"{SITE}/rest/api/2/customFieldOption/{poid}", "value": pval, "id": poid,
+                                           "child": {"self": f"{SITE}/rest/api/2/customFieldOption/{coid}", "value": cval,
+                                                     "id": coid}}
+        if rng.random() < 0.3:
+            fields["customfield_10108"] = sorted(set(rng.sample(["vip", "regression", "customer", "q3", "tech-debt"],
+                                                                rng.randint(1, 2))))
+        if rng.random() < 0.2:
+            fields["customfield_10109"] = jts(created + timedelta(days=rng.randint(10, 90), hours=rng.randint(0, 23)))
+        if rng.random() < 0.3:
+            fields["customfield_10110"] = [copy.deepcopy(data["usersById"][u]) for u in rng.sample(active_users, 2)]
+        if rng.random() < 0.4:
+            fields["customfield_10111"] = copy.deepcopy(rng.choice(TEAMS))
+        if tid == "10003" and rng.random() < 0.8:
+            oid, val = rng.choice(SELECT_OPTIONS[10112])
+            fields["customfield_10112"] = {"self": f"{SITE}/rest/api/2/customFieldOption/{oid}", "value": val, "id": oid}
+
+        # Attachments
+        for _ in range(rng.choice([0, 0, 0, 1, 2])):
+            aid = new_id("attachment")
+            fields["attachment"].append({"self": f"{SITE}/rest/api/2/attachment/{aid}", "id": aid,
+                                         "filename": f"{rng.choice(WORDS)}.png",
+                                         "author": copy.deepcopy(data["usersById"][reporter]),
+                                         "created": jts(created + timedelta(minutes=3)), "size": rng.randint(1000, 900000),
+                                         "mimeType": "image/png", "content": f"{SITE}/secure/attachment/{aid}/x.png",
+                                         "thumbnail": f"{SITE}/secure/thumbnail/{aid}/x.png"})
+
+        # Comments and worklogs
+        comments = []
+        for c in range(60 if heavy else rng.choice([0, 0, 1, 2, 3, 5, 8])):
+            cid = new_id("comment")
+            author = rng.choice(active_users)
+            when = min(created + timedelta(hours=rng.uniform(1, 24 * 20)), EPOCH)
+            comment = {"self": f"{SITE}/rest/api/2/issue/{iid}/comment/{cid}", "id": cid,
+                       "author": copy.deepcopy(data["usersById"][author]), "body": sentence(rng.randint(4, 14)) + ".",
+                       "updateAuthor": copy.deepcopy(data["usersById"][author]), "created": jts(when),
+                       "updated": jts(when), "jsdPublic": True}
+            if rng.random() < 0.05:
+                comment["visibility"] = {"type": "group", "value": "jira-developers", "identifier": "jira-developers"}
+            comments.append(comment)
+        comments.sort(key=lambda c: c["created"])
+        worklogs = []
+        spent = 0
+        for w in range(30 if heavy else (rng.choice([0, 0, 1, 2, 4, 6]) if status != STATUS_TODO else 0)):
+            wid = new_id("worklog")
+            author = assignee or rng.choice(active_users)
+            started = min(created + timedelta(hours=rng.uniform(1, 24 * 20)), EPOCH)
+            secs = rng.choice([900, 1800, 3600, 7200, 14400])
+            spent += secs
+            worklogs.append({"self": f"{SITE}/rest/api/2/issue/{iid}/worklog/{wid}",
+                             "author": copy.deepcopy(data["usersById"][author]),
+                             "updateAuthor": copy.deepcopy(data["usersById"][author]),
+                             "comment": sentence(rng.randint(2, 6)), "created": jts(started), "updated": jts(started),
+                             "started": jts(started), "timeSpent": f"{secs // 60}m", "timeSpentSeconds": secs,
+                             "id": wid, "issueId": iid})
+        worklogs.sort(key=lambda w: w["started"])
+        if spent:
+            fields["timespent"] = spent
+            if fields["timeoriginalestimate"]:
+                fields["timeestimate"] = max(0, fields["timeoriginalestimate"] - spent)
+        all_times = [updated] + [datetime.fromisoformat(c["updated"].replace("+0000", "+00:00")) for c in comments] + \
+                    [datetime.fromisoformat(w["updated"].replace("+0000", "+00:00")) for w in worklogs] + \
+                    [datetime.fromisoformat(h["created"].replace("+0000", "+00:00")) for h in histories]
+        fields["updated"] = jts(max(all_times))
+
+        issue = {"id": iid, "key": key, "fields": fields}
+        if tid == "10004":
+            parent = rng.choice(parents[pid])
+            issue["_parent"] = parent
+            data["issues"][parent].setdefault("_subtasks", []).append(iid)
+        elif tid != "10000" and rng.random() < 0.6 and epics[pid]:
+            issue["_parent"] = rng.choice(epics[pid])
+        if tid == "10000":
+            epics[pid].append(iid)
+        elif tid != "10004":
+            parents[pid].append(iid)
+
+        histories.sort(key=lambda h: (h["created"], int(h["id"])))
+        data["issues"][iid] = issue
+        data["changelogs"][iid] = histories
+        data["comments"][iid] = comments
+        data["worklogs"][iid] = worklogs
+
+    # Issue links between issues of the same project.
+    all_ids = list(data["issues"])
+    for iid in all_ids:
+        if rng.random() < 0.08:
+            other = rng.choice(all_ids)
+            if other == iid:
+                continue
+            lid = new_id("link")
+            data["links"][lid] = {"id": lid, "type": rng.choice(["10000", "10003", "10002"]), "source": iid,
+                                  "destination": other}
+
+    data["nextIds"] = {k: v + 1 for k, v in ids.items()}
+    return Tenant(data)
+
+
+# ------------------------------------------------------------------ mutation
+def mutate(tenant: Tenant, *, edits: int = 20, deletes: int = 3, creates: int = 5, links: int = 4,
+           seed: int = 99, now: datetime | None = None) -> list[dict[str, Any]]:
+    """Change the tenant the way users would, and return the Jira events fired.
+
+    Events use the shapes Forge product triggers deliver (eventType plus the
+    issue / worklog / issueLink objects), trimmed to what the app reads.
+    """
+    rng = random.Random(seed)
+    d = tenant.data
+    # Jira's "updated" only moves forward; keep the synthetic clock monotonic
+    # across successive mutate() calls.
+    now = now or datetime.now(timezone.utc)
+    if d.get("clock"):
+        now = max(now, datetime.fromisoformat(d["clock"]))
+    events: list[dict[str, Any]] = []
+    active_users = [u["accountId"] for u in d["users"] if u["active"]]
+    status_by_id = {s["id"]: s for s in d["statuses"]}
+
+    def tick() -> datetime:
+        nonlocal now
+        now = now + timedelta(seconds=1)
+        return now
+
+    def touch(iid: str, when: datetime) -> None:
+        tenant.issues[iid]["fields"]["updated"] = jts(when)
+
+    def issue_event(event_type: str, iid: str) -> dict[str, Any]:
+        issue = tenant.issues[iid]
+        return {"eventType": event_type, "issue": {"id": iid, "key": issue["key"],
+                                                   "fields": {"project": {"id": issue["fields"]["project"]["id"],
+                                                                          "key": issue["fields"]["project"]["key"]}}}}
+
+    candidates = [i for i in tenant.issues]
+    for _ in range(edits):
+        iid = rng.choice(candidates)
+        if iid not in tenant.issues:
+            continue
+        issue = tenant.issues[iid]
+        f = issue["fields"]
+        when = tick()
+        kind = rng.choice(["status", "summary", "comment", "worklog", "assignee", "labels", "storypoints"])
+        author = rng.choice(active_users)
+        if kind == "status":
+            nxt = STATUS_PROGRESS if f["status"]["id"] == STATUS_TODO else STATUS_TODO
+            d["changelogs"][iid].append({"id": tenant.next_id("history"), "author": tenant.user(author),
+                                         "created": jts(when), "items": [{
+                                             "field": "status", "fieldtype": "jira", "fieldId": "status",
+                                             "from": f["status"]["id"], "fromString": f["status"]["name"], "to": nxt,
+                                             "toString": status_by_id[nxt]["name"]}]})
+            f["status"] = copy.deepcopy(status_by_id[nxt])
+            if nxt == STATUS_TODO and f.get("resolution"):
+                f["resolution"] = None
+                f["resolutiondate"] = None
+            events.append(issue_event("avi:jira:updated:issue", iid))
+        elif kind == "summary":
+            old = f["summary"]
+            f["summary"] = old + " (edited)"
+            d["changelogs"][iid].append({"id": tenant.next_id("history"), "author": tenant.user(author),
+                                         "created": jts(when), "items": [{
+                                             "field": "summary", "fieldtype": "jira", "fieldId": "summary",
+                                             "from": None, "fromString": old, "to": None, "toString": f["summary"]}]})
+            events.append(issue_event("avi:jira:updated:issue", iid))
+        elif kind == "comment":
+            cid = tenant.next_id("comment")
+            d["comments"].setdefault(iid, []).append({
+                "self": f"{SITE}/rest/api/2/issue/{iid}/comment/{cid}", "id": cid, "author": tenant.user(author),
+                "body": "Follow-up comment.", "updateAuthor": tenant.user(author), "created": jts(when),
+                "updated": jts(when), "jsdPublic": True})
+            ev = issue_event("avi:jira:commented:issue", iid)
+            ev["comment"] = {"id": cid}
+            events.append(ev)
+        elif kind == "worklog":
+            wid = tenant.next_id("worklog")
+            d["worklogs"].setdefault(iid, []).append({
+                "self": f"{SITE}/rest/api/2/issue/{iid}/worklog/{wid}", "author": tenant.user(author),
+                "updateAuthor": tenant.user(author), "comment": "Pairing", "created": jts(when), "updated": jts(when),
+                "started": jts(when), "timeSpent": "30m", "timeSpentSeconds": 1800, "id": wid, "issueId": iid})
+            f["timespent"] = (f.get("timespent") or 0) + 1800
+            events.append({"eventType": "avi:jira:created:worklog", "worklog": {"id": wid, "issueId": iid}})
+        elif kind == "assignee":
+            old = (f.get("assignee") or {}).get("accountId")
+            new = rng.choice(active_users)
+            f["assignee"] = tenant.user(new)
+            d["changelogs"][iid].append({"id": tenant.next_id("history"), "author": tenant.user(author),
+                                         "created": jts(when), "items": [{
+                                             "field": "assignee", "fieldtype": "jira", "fieldId": "assignee",
+                                             "from": None, "fromString": None, "to": None,
+                                             "toString": d["usersById"][new]["displayName"],
+                                             "tmpFromAccountId": old, "tmpToAccountId": new}]})
+            events.append(issue_event("avi:jira:updated:issue", iid))
+        elif kind == "labels":
+            f["labels"] = sorted(set(f.get("labels") or []) | {"edited"})
+            events.append(issue_event("avi:jira:updated:issue", iid))
+        else:
+            f["customfield_10028"] = 21.0
+            events.append(issue_event("avi:jira:updated:issue", iid))
+        touch(iid, when)
+
+    for _ in range(links):
+        a, b = rng.sample([i for i in tenant.issues], 2)
+        lid = tenant.next_id("link")
+        d["links"][lid] = {"id": lid, "type": "10003", "source": a, "destination": b}
+        when = tick()
+        touch(a, when)
+        touch(b, when)
+        events.append({"eventType": "avi:jira:created:issuelink",
+                       "issueLink": {"id": lid, "sourceIssueId": a, "destinationIssueId": b}})
+
+    for _ in range(creates):
+        proj = rng.choice(d["projects"])
+        pid = proj["id"]
+        num = max(int(i["key"].rsplit("-", 1)[1]) for i in tenant.issues.values()
+                  if i["fields"]["project"]["id"] == pid) + 1
+        iid = tenant.next_id("issue")
+        when = tick()
+        reporter = rng.choice(active_users)
+        itype = next(t for t in d["issueTypes"] if t["id"] == "10002")
+        tenant.issues[iid] = {"id": iid, "key": f"{proj['key']}-{num}", "fields": {
+            "summary": "New task from mutation", "description": None, "environment": None,
+            "issuetype": copy.deepcopy(itype),
+            "project": {"self": proj["self"], "id": pid, "key": proj["key"], "name": proj["name"],
+                        "projectTypeKey": "software", "simplified": False, "avatarUrls": {}},
+            "status": copy.deepcopy(status_by_id[STATUS_TODO]),
+            "priority": copy.deepcopy(next(p for p in d["priorities"] if p["id"] == "3")),
+            "resolution": None, "assignee": None, "reporter": tenant.user(reporter), "creator": tenant.user(reporter),
+            "created": jts(when), "updated": jts(when), "resolutiondate": None, "duedate": None, "labels": [],
+            "components": [], "fixVersions": [], "versions": [], "timeoriginalestimate": None, "timeestimate": None,
+            "timespent": None, "votes": {"votes": 0, "hasVoted": False}, "watches": {"watchCount": 1, "isWatching": False},
+            "security": None, "attachment": [], "customfield_10019": "0|zzzzz:"}}
+        d["changelogs"][iid], d["comments"][iid], d["worklogs"][iid] = [], [], []
+        events.append(issue_event("avi:jira:created:issue", iid))
+
+    deletable = [i for i, issue in tenant.issues.items() if not issue.get("_subtasks")
+                 and issue["fields"]["issuetype"]["id"] != "10000"]
+    for iid in rng.sample(deletable, min(deletes, len(deletable))):
+        issue = tenant.issues[iid]
+        ev = issue_event("avi:jira:deleted:issue", iid)
+        parent = issue.get("_parent")
+        if parent and parent in tenant.issues and iid in tenant.issues[parent].get("_subtasks", []):
+            tenant.issues[parent]["_subtasks"].remove(iid)
+        for lid in [lid for lid, link in d["links"].items() if iid in (link["source"], link["destination"])]:
+            del d["links"][lid]
+        del tenant.issues[iid]
+        d["changelogs"].pop(iid, None)
+        d["comments"].pop(iid, None)
+        d["worklogs"].pop(iid, None)
+        events.append(ev)
+    d["clock"] = now.isoformat()
+    return events