"""Migrate a vCon from syntax 0.4.0 to 0.5.0 (draft-ietf-vcon-vcon-core-05, Appendix A.1).
The migration is table driven. ``MIGRATION_STEPS`` holds one ``MigrationStep``
per step T1..T15 of the ordered transform table; each step is one function that
mutates a shared ``_Context``. If a later edit of Appendix A.1 changes one step,
only that function (or its table entry) needs to change.
Execution order (the draft gives none; this order is inferred so that every
``dialog`` index stays valid): the steps that read the 0.4.0 ``dialog`` array
run before any array is rewritten, and ``T10`` blanks the removed Dialogs in
place at the end, so the array length and every other index are unchanged.
T13 T15 T1 -> T8 T9 T9b T6 -> T2 T7 T4(+T5) T3 -> T10 T10b T10c -> T11 T12 T14
T4 runs before T3 so that the Sessions T5 creates for a transfer's original,
consultation and target calls are known when T3 builds the party_history
Events: an Event lists every Session of the Dialog it came from (AMB-3).
Nothing is invented silently. Every value the draft does not dictate is listed
in the :class:`MigrationReport` (kind ``inferred``), every field that had to be
filled by a fallback is listed (kind ``fallback``), and every problem the
migration could not resolve is listed (kind ``unresolved``). In strict mode a
fallback raises :class:`MigrationError` instead.
A signed 0.4.0 vCon is migrated as the unsigned payload. The migration never
signs; the report sets ``resign_required``.
"""
from __future__ import annotations
import base64
import copy
import json
import logging
import re
from dataclasses import dataclass, field
from datetime import datetime, timedelta, timezone
from typing import Any, Callable, Dict, List, NamedTuple, Optional, Tuple
from .event import EVENT_PARAMETERS as _EVENT_PARAMS
from .validation import extensions_in_use, validate_vcon_dict
logger = logging.getLogger(__name__)
SOURCE_VERSION = "0.4.0"
TARGET_VERSION = "0.5.0"
#: Top-level parameters that exist only in 0.5.0. Input that has one of them is
#: already 0.5.0 even when it omits the (optional, deprecated) ``vcon`` parameter;
#: migrating it again would overwrite its ``sessions`` and ``events``.
_V050_ONLY_KEYS = ("sessions", "events", "redacted_from", "amended_from", "redacted_strings")
[docs]class MigrationError(ValueError):
"""The vCon cannot be migrated (or, in strict mode, a MUST field has no source)."""
# ---------------------------------------------------------------------------
# Report
# ---------------------------------------------------------------------------
#: A value the draft does not dictate; a documented default was applied.
INFERRED = "inferred"
#: A MUST field with no source was filled with the documented fallback.
FALLBACK = "fallback"
#: A problem left for a person to resolve.
UNRESOLVED = "unresolved"
#: Informational.
INFO = "info"
[docs]@dataclass
class ReportEntry:
step: str
kind: str
message: str
code: Optional[str] = None # AMB-n identifier from the implementation spec
details: Dict[str, Any] = field(default_factory=dict)
[docs] def to_dict(self) -> Dict[str, Any]:
out: Dict[str, Any] = {"step": self.step, "kind": self.kind, "message": self.message}
if self.code:
out["code"] = self.code
if self.details:
out["details"] = self.details
return out
[docs]@dataclass
class MigrationReport:
"""What a migration did that the draft did not dictate."""
source_version: Optional[str] = None
target_version: str = TARGET_VERSION
strict: bool = False
#: True when the input was signed: the signature is dropped and the result is unsigned.
resign_required: bool = False
entries: List[ReportEntry] = field(default_factory=list)
#: Original content of every Dialog replaced by ``{}``, keyed by its (unchanged) index.
removed_dialogs: Dict[int, Dict[str, Any]] = field(default_factory=dict)
#: Steps that ran, in order.
steps_run: List[str] = field(default_factory=list)
[docs] def add(
self,
step: str,
kind: str,
message: str,
code: Optional[str] = None,
**details: Any,
) -> None:
self.entries.append(ReportEntry(step, kind, message, code, details))
def _of(self, kind: str) -> List[ReportEntry]:
return [e for e in self.entries if e.kind == kind]
@property
def inferred(self) -> List[ReportEntry]:
return self._of(INFERRED)
@property
def fallbacks(self) -> List[ReportEntry]:
return self._of(FALLBACK)
@property
def unresolved(self) -> List[ReportEntry]:
return self._of(UNRESOLVED)
@property
def notes(self) -> List[ReportEntry]:
return self._of(INFO)
[docs] def to_dict(self) -> Dict[str, Any]:
return {
"source_version": self.source_version,
"target_version": self.target_version,
"strict": self.strict,
"resign_required": self.resign_required,
"steps_run": list(self.steps_run),
"entries": [e.to_dict() for e in self.entries],
"removed_dialogs": {str(k): v for k, v in self.removed_dialogs.items()},
}
[docs] def summary(self) -> str:
return (
f"{len(self.inferred)} inferred, {len(self.fallbacks)} fallback, "
f"{len(self.unresolved)} unresolved"
+ ("; re-signing required" if self.resign_required else "")
)
[docs]class MigrationResult(NamedTuple):
"""Result of a migration. Unpacks as ``(vcon, report)``."""
vcon: Dict[str, Any]
report: MigrationReport
# ---------------------------------------------------------------------------
# Context and helpers
# ---------------------------------------------------------------------------
def _is_int(v: Any) -> bool:
return isinstance(v, int) and not isinstance(v, bool)
_DATE_RE = re.compile(
r"^(\d{4})-(\d{2})-(\d{2})(?:[Tt ](\d{2}):(\d{2})(?::(\d{2})(\.\d+)?)?\s*(Z|z|[+-]\d{2}(?::?\d{2})?)?)?$"
)
def _parse_dt(value: Any) -> Optional[datetime]:
"""Parse an RFC 3339 / ISO 8601 date-time, or return None.
Free-form strings such as ``"Jan 1 2022 10:00"`` and out-of-range fields
(February 30, hour 24) are rejected, matching the TypeScript port. A value
with no offset is read as UTC. Fractional seconds keep microseconds.
"""
if not isinstance(value, str):
return None
m = _DATE_RE.match(value.strip())
if not m:
return None
ys, mos, ds, hs, mis, ss, frac, tz = m.groups()
try:
offset = timedelta(0)
if tz and tz.upper() != "Z":
digits = tz[1:].replace(":", "")
oh, om = int(digits[:2]), int(digits[2:] or "0")
if oh > 23 or om > 59:
return None
offset = timedelta(hours=oh, minutes=om) * (-1 if tz[0] == "-" else 1)
micro = int(frac[1:7].ljust(6, "0")) if frac else 0
return datetime(
int(ys), int(mos), int(ds), int(hs or 0), int(mis or 0), int(ss or 0), micro,
tzinfo=timezone(offset),
)
except ValueError:
return None
def _num(seconds: float) -> Any:
seconds = round(seconds, 6)
return int(seconds) if float(seconds).is_integer() else seconds
def _plain_parties(value: Any) -> List[int]:
"""Flat list of int party indices of a 0.4.0 Dialog ``parties`` value."""
out: List[int] = []
items = value if isinstance(value, list) else ([] if value is None else [value])
for v in items:
if isinstance(v, list):
out.extend(x for x in v if _is_int(x))
elif _is_int(v):
out.append(v)
return out
def _union(lists: List[List[int]]) -> List[int]:
seen: List[int] = []
for lst in lists:
for v in lst:
if v not in seen:
seen.append(v)
return seen
def _rename_key(d: Dict[str, Any], old: str, new: str) -> Dict[str, Any]:
return {(new if k == old else k): v for k, v in d.items()}
class _Context:
def __init__(self, data: Dict[str, Any], strict: bool, report: MigrationReport) -> None:
self.out: Dict[str, Any] = data
self.src: Dict[str, Any] = copy.deepcopy(data) # refreshed by T13 after unwrapping
self.strict = strict
self.report = report
self.sessions: List[Dict[str, Any]] = []
self.events: List[Dict[str, Any]] = []
#: receivers contributed to the Session by each (kept) Dialog index
self.receivers: Dict[int, List[int]] = {}
#: originator value taken from each (kept) Dialog index
self.originators: Dict[int, int] = {}
#: Session indices each Dialog index belongs to
self.dialog_sessions: Dict[int, List[int]] = {}
#: recording-set Dialog index -> Session index (T7)
self.rs_session: Dict[int, int] = {}
#: transfer Dialog index -> Session index of its original call (T4)
self.transfer_session: Dict[int, int] = {}
self._role_sessions: Dict[int, int] = {}
self._empty_party: Optional[int] = None
self.catch_all: Optional[int] = None
# -- source views ---------------------------------------------------
@property
def dialogs(self) -> List[Any]:
d = self.src.get("dialog")
return d if isinstance(d, list) else []
@property
def removed(self) -> Dict[int, str]:
"""Dialog index -> removed type, for transfer and recording-set Dialogs."""
return {
i: d["type"]
for i, d in enumerate(self.dialogs)
if isinstance(d, dict) and d.get("type") in ("transfer", "recording-set")
}
def kept(self) -> List[int]:
rem = self.removed
return [i for i, d in enumerate(self.dialogs) if i not in rem and isinstance(d, dict) and d]
# -- helpers --------------------------------------------------------
def need_fallback(self, step: str, message: str, code: Optional[str] = None, **details: Any) -> None:
"""Record a fallback for a MUST field, or raise in strict mode."""
if self.strict:
raise MigrationError(f"{step}: {message} (strict mode: no source for a required field)")
self.report.add(step, FALLBACK, message, code, **details)
def new_session(self, session: Dict[str, Any]) -> int:
self.sessions.append(session)
return len(self.sessions) - 1
def empty_party(self, step: str, role: str) -> int:
"""Index of an empty Party Object, appended once (4.3.9: unknown party)."""
if self._empty_party is None:
parties = self.out.get("parties")
if not isinstance(parties, list):
# Absent or null `parties` is treated alike (as the TypeScript port does).
if "parties" in self.out:
self.report.add(
step, INFERRED, "vCon 'parties' was not an array (null); treated as absent.", None,
)
parties = self.out["parties"] = []
parties.append({})
self._empty_party = len(parties) - 1
self.report.add(
step, INFERRED,
f"Appended an empty Party Object at parties[{self._empty_party}] to stand for unknown parties.",
None, party=self._empty_party,
)
return self._empty_party
def dialog_start(self, idx: Any) -> Optional[str]:
"""Start of a Dialog, or of a recording-set's earliest recording."""
if not _is_int(idx) or not 0 <= idx < len(self.dialogs):
return None
d = self.dialogs[idx]
if not isinstance(d, dict):
return None
if _parse_dt(d.get("start")):
return d["start"]
if d.get("type") == "recording-set":
starts = [
(self.dialogs[r].get("start"))
for r in (d.get("recordings") or [])
if _is_int(r) and 0 <= r < len(self.dialogs) and isinstance(self.dialogs[r], dict)
]
starts = [s for s in starts if _parse_dt(s)]
if starts:
return min(starts, key=_parse_dt)
return None
def span(self, idxs: List[int]) -> Tuple[Optional[str], Optional[Any]]:
"""Derived (start, duration) of a group of Dialogs.
start is the earliest Dialog start. duration runs from that start to the
latest Dialog end (start plus duration, or start when no duration is
known), and is only derived when at least one Dialog has a duration.
"""
items = [
(i, _parse_dt(self.dialogs[i].get("start")))
for i in idxs
if isinstance(self.dialogs[i], dict)
]
items = [(i, s) for i, s in items if s is not None]
if not items:
return None, None
first_i, first = min(items, key=lambda t: t[1])
start_str = self.dialogs[first_i]["start"]
ends = []
any_duration = False
for i, s in items:
dur = self.dialogs[i].get("duration")
if isinstance(dur, (int, float)) and not isinstance(dur, bool):
any_duration = True
ends.append(s.timestamp() + dur)
else:
ends.append(s.timestamp())
if not any_duration:
return start_str, None
return start_str, _num(max(ends) - first.timestamp())
def make_session(self, step: str, idxs: List[int], label: str) -> Dict[str, Any]:
"""Build a Session for a group of kept Dialogs from derived values."""
session: Dict[str, Any] = {}
start, duration = self.span(idxs)
if start is not None:
session["start"] = start
if duration is not None:
session["duration"] = duration
parties = _union([self.receivers.get(i, []) for i in idxs])
if parties:
session["parties"] = parties
orig = [self.originators[i] for i in idxs if i in self.originators]
if orig:
chosen = orig[0]
others = sorted({o for o in orig[1:] if o != chosen})
if others:
self.report.add(
step, UNRESOLVED,
f"{label}: Dialogs name different originators; kept {chosen}, "
f"did not record {others}.", None, kept=chosen, dropped=others,
)
if not parties or chosen != parties[0]:
session["originator"] = chosen
session["dialog"] = list(idxs)
# key order: start, duration, parties, originator, dialog
order = ("start", "duration", "parties", "originator", "session_id", "sessions", "dialog")
session = {k: session[k] for k in order if k in session}
if start is not None or duration is not None:
self.report.add(
step, INFERRED,
f"{label}: start/duration derived from its Dialogs (earliest start; "
"duration to the latest end when any Dialog has a duration).",
None, start=start, duration=duration,
)
return session
# ---------------------------------------------------------------------------
# Steps
# ---------------------------------------------------------------------------
def _check_dialog_dates(ctx: _Context) -> None:
"""core-05 Date is RFC 3339: a Dialog start that is not one is never used as a Session start.
Strict mode raises; otherwise the value is reported as unresolved.
"""
for i, d in enumerate(ctx.dialogs):
if not isinstance(d, dict) or d.get("start") is None or _parse_dt(d["start"]):
continue
msg = f"dialog[{i}] start {d['start']!r} is not an RFC 3339 date-time"
if ctx.strict:
raise MigrationError(f"T1: {msg} (strict mode)")
ctx.report.add(
"T1", UNRESOLVED, f"{msg}; not used to derive a Session start.", None, dialog=i, start=d["start"],
)
def _step_t1_version(ctx: _Context) -> None:
"""T1: ``vcon`` "0.4.0" -> "0.5.0"."""
_check_dialog_dates(ctx)
if "vcon" not in ctx.out:
ctx.report.add("T1", INFERRED, "Input had no 'vcon' parameter; set to '0.5.0' (AMB-12: writers emit it).", "AMB-12")
ctx.out["vcon"] = TARGET_VERSION
def _step_t2_sessions(ctx: _Context) -> None:
"""T2: add one Session which references all (kept) Dialog Objects.
The removed transfer and recording-set positions are skipped (they become
``{}``; T10). Receivers (T8, T9, T9b) and the originator (T6) have already
been collected, so the Session is built in one go.
"""
kept = ctx.kept()
if not kept:
return
ctx.catch_all = ctx.new_session(ctx.make_session("T2", kept, "Session 0 (all Dialogs)"))
for i in kept:
ctx.dialog_sessions.setdefault(i, []).append(ctx.catch_all)
ctx.report.add(
"T2", INFO,
f"Added Session {ctx.catch_all} referencing {len(kept)} Dialog Object(s).",
)
def _step_t3_party_history(ctx: _Context) -> None:
"""T3: each Dialog ``party_history`` entry becomes an Event; ``event`` is renamed ``type``.
The Event's ``sessions`` references the Session(s) for the Dialog it came
from and the Event does not reference the Dialog (SHOULD NOT, 4.3.5).
"""
dialogs = ctx.out.get("dialog")
if not isinstance(dialogs, list):
return
for i, src_d in enumerate(ctx.dialogs):
if not isinstance(src_d, dict) or "party_history" not in src_d:
continue
if src_d.get("type") == "transfer":
ctx.report.add(
"T3", UNRESOLVED,
f"dialog[{i}] is a transfer Dialog with party_history; the entries are not migrated "
"(A.1 covers party_history on non-transfer Dialogs). Original kept in removed_dialogs.",
None, dialog=i,
)
continue
if src_d.get("type") == "recording-set":
sess = [ctx.rs_session[i]] if i in ctx.rs_session else []
else:
sess = sorted(ctx.dialog_sessions.get(i, []))
if len(sess) > 1:
ctx.report.add(
"T3", INFERRED,
f"dialog[{i}] belongs to Sessions {sess}; its party_history Events list all of them "
"in 'sessions' (4.3.3: an Event applies only to the Sessions listed).",
"AMB-3", dialog=i, sessions=sess,
)
history = src_d["party_history"]
if not isinstance(history, list):
ctx.report.add("T3", UNRESOLVED, f"dialog[{i}] party_history is not a list; dropped.", None, dialog=i)
else:
for n, entry in enumerate(history):
if not isinstance(entry, dict) or "event" not in entry:
ctx.report.add(
"T3", UNRESOLVED,
f"dialog[{i}].party_history[{n}] has no 'event'; entry not migrated.",
None, dialog=i, entry=entry,
)
continue
ev: Dict[str, Any] = {"type": entry["event"]}
if _parse_dt(entry.get("time")):
ev["time"] = entry["time"]
else:
# MUST field: Dialog start, then the vCon created_at.
fb, src = src_d.get("start"), "Dialog start"
if not _parse_dt(fb):
fb, src = ctx.out.get("created_at"), "vCon created_at"
if not _parse_dt(fb):
raise MigrationError(
f"T3: dialog[{i}].party_history[{n}] has no time, and neither the Dialog start "
"nor the vCon created_at can stand in"
)
ctx.need_fallback(
"T3",
f"dialog[{i}].party_history[{n}] has no usable time ({entry.get('time')!r}); used the "
f"{src} ({fb!r}) as the Event time.", None, dialog=i, entry=n,
original_time=entry.get("time"), source=src, time=fb,
)
ev["time"] = fb
if sess:
ev["sessions"] = sess[0] if len(sess) == 1 else sess
if _is_int(entry.get("party")):
ev["party"] = entry["party"]
else:
ctx.need_fallback(
"T3",
f"dialog[{i}].party_history[{n}] has no party; referenced an empty Party Object.",
None, dialog=i,
)
ev["party"] = ctx.empty_party("T3", "party")
if entry["event"] in ("keydown", "keyup") and "button" in entry:
ev["button"] = entry["button"]
elif "button" in entry:
ctx.report.add(
"T3", UNRESOLVED,
f"dialog[{i}].party_history[{n}] has 'button' on a '{entry['event']}' event "
"(only keydown and keyup carry it); button not migrated.", None, dialog=i, entry=n,
dropped={"button": entry["button"]},
)
# Parameters a 0.4.0 extension added to the entry: carried onto the Event
# unless the name is a core Event parameter (which would change its meaning).
unknown = {k: v for k, v in entry.items() if k not in ("party", "time", "event", "button")}
if unknown:
carried = {k: v for k, v in unknown.items() if k not in _EVENT_PARAMS}
dropped = {k: v for k, v in unknown.items() if k in _EVENT_PARAMS}
ev.update(carried)
ctx.report.add(
"T3", UNRESOLVED,
f"dialog[{i}].party_history[{n}] had non-core parameter(s) {sorted(unknown)}; "
f"carried onto the Event: {sorted(carried)}, dropped (name clashes with a core Event "
f"parameter): {sorted(dropped)}. List the defining extension in 'extensions'.",
None, dialog=i, entry=n, carried=carried, dropped=dropped,
)
ctx.events.append(ev)
if src_d.get("type") != "recording-set" and isinstance(dialogs[i], dict):
dialogs[i].pop("party_history", None)
def _step_t4_transfers(ctx: _Context) -> None:
"""T4 (with T5): each ``transfer`` Dialog becomes one or two transfer Events.
``transferor`` becomes ``party``. ``original``, ``consultation`` and
``target_dialog`` become Session indices (T5): the recording-set's Session,
otherwise a Session that lists that Dialog.
"""
for k, kind in ctx.removed.items():
if kind != "transfer":
continue
tr = ctx.dialogs[k]
step = "T4"
def session_for(ref: Any, role: str, required: bool) -> Optional[int]:
"""T5: Session index for a Dialog reference held by a transfer Dialog."""
if ref is None:
return None
if not _is_int(ref) or not 0 <= ref < len(ctx.dialogs):
ctx.report.add(step, UNRESOLVED, f"transfer dialog[{k}] {role}={ref!r} is not a Dialog index.", None, dialog=k)
return None
if ref in ctx.rs_session:
ctx.report.add(
"T5", INFO,
f"transfer dialog[{k}] {role} -> dialog[{ref}] is a recording-set; using its Session {ctx.rs_session[ref]}.",
)
return ctx.rs_session[ref]
if ref in ctx.removed:
idx = ctx.new_session({})
ctx.report.add(
"T5", UNRESOLVED,
f"transfer dialog[{k}] {role} -> dialog[{ref}] is itself a removed {ctx.removed[ref]} Dialog; "
f"created placeholder Session {idx} with no parameters.", None, dialog=k,
)
return idx
if ref in ctx._role_sessions:
return ctx._role_sessions[ref]
sess = ctx.make_session("T5", [ref], f"Session for transfer {role} (dialog[{ref}])")
idx = ctx.new_session(sess)
ctx._role_sessions[ref] = idx
ctx.dialog_sessions.setdefault(ref, []).append(idx)
ctx.report.add(
"T5", INFERRED,
f"transfer dialog[{k}] {role} -> created Session {idx} listing dialog[{ref}] "
"(A.1: referenced through a Session Object).", None, dialog=k, session=idx,
)
return idx
def placeholder(role: str, why: str, required_fallback: bool) -> int:
idx = ctx.new_session({})
msg = f"transfer dialog[{k}] has no {role} ({why}); created placeholder Session {idx} with no parameters (4.3.1.3)."
if required_fallback:
ctx.need_fallback(step, msg, None, dialog=k, session=idx)
else:
ctx.report.add(step, INFERRED, msg, "AMB-7", dialog=k, session=idx)
return idx
# Session of the original call (sessions: M, single index).
orig_ref = tr.get("original")
sidx = session_for(orig_ref, "original", True)
if sidx is None:
sidx = placeholder("original", "'sessions' is required on every transfer Event", True)
ctx.transfer_session[k] = sidx
def party_ref(key: str, role: str, required: bool) -> Optional[int]:
val = tr.get(key)
if _is_int(val):
return val
if not required:
return None
ctx.need_fallback(
step,
f"transfer dialog[{k}] has no {key} ({role}); referenced an empty Party Object (4.3.9).",
None, dialog=k,
)
return ctx.empty_party(step, role)
transferor = party_ref("transferor", "Transferor, becomes 'party'", True)
transferee = party_ref("transferee", "Transferee", True)
cons_ref = tr.get("consultation")
target_ref = tr.get("target_dialog")
cons_sess = session_for(cons_ref, "consultation", False) if cons_ref is not None else None
if cons_ref is not None and cons_sess is None:
cons_sess = placeholder("usable consultation", "consultation Dialog index could not be resolved", False)
target_sess = session_for(target_ref, "target_dialog", False) if target_ref is not None else None
has_target_party = _is_int(tr.get("transfer_target"))
# Event types (AMB-7).
types: List[str] = []
if cons_ref is not None:
types.append("consultation-start")
if target_ref is not None or has_target_party:
types.append("consultative-transfer" if cons_ref is not None else "blind-transfer")
else:
types.append("transfer-abandoned")
ctx.report.add(
step, INFERRED,
f"transfer dialog[{k}] mapped to Event type(s) {types} "
"(consultation present -> consultation-start + consultative-transfer; otherwise blind-transfer; "
"no target_dialog and no transfer_target -> transfer-abandoned).",
"AMB-7", dialog=k, types=types,
)
if "blind-transfer" in types or "consultative-transfer" in types:
if target_sess is None:
target_sess = placeholder(
"target_dialog",
"the target call was not captured; 4.3.1.3 uses a placeholder Session in that case", False,
)
def event_time(which: str) -> str:
own = tr.get("start")
if _parse_dt(own):
return own
cands: List[Tuple[Optional[str], str]] = []
if which == "consult":
cands.append((ctx.dialog_start(cons_ref), f"start of consultation dialog[{cons_ref}]"))
else:
cands.append((ctx.dialog_start(target_ref), f"start of target dialog[{target_ref}]"))
if cons_ref is not None:
cd = ctx.dialogs[cons_ref] if _is_int(cons_ref) and 0 <= cons_ref < len(ctx.dialogs) else None
cs, dur = _parse_dt(ctx.dialog_start(cons_ref)), (cd or {}).get("duration") if isinstance(cd, dict) else None
if cs is not None and isinstance(dur, (int, float)) and not isinstance(dur, bool):
end = datetime.fromtimestamp(cs.timestamp() + dur, tz=timezone.utc).isoformat()
cands.append((end, f"end of consultation dialog[{cons_ref}] (start + duration)"))
cands.append((ctx.dialog_start(cons_ref), f"start of consultation dialog[{cons_ref}]"))
for value, src in cands:
if value and _parse_dt(value):
ctx.report.add(
step, INFERRED,
f"transfer dialog[{k}] has no start; Event time taken from the {src}, "
"not from the transfer Dialog's own start.", "AMB-7", dialog=k, source=src, time=value,
)
return value
created = ctx.out.get("created_at")
if _parse_dt(created):
ctx.need_fallback(
step,
f"transfer dialog[{k}] has no start and no other time source; used the vCon created_at "
f"({created!r}) as the Event time.", "AMB-7", dialog=k,
)
return created
raise MigrationError(
f"{step}: transfer dialog[{k}] has no start and the vCon has no created_at; no time can be sourced"
)
base: Dict[str, Any] = {}
for t in types:
ev: Dict[str, Any] = {"type": t}
ev["time"] = event_time("consult" if t == "consultation-start" else "transfer")
ev["sessions"] = sidx
ev["party"] = transferor
ev["transferee"] = transferee
need_target = t != "transfer-abandoned"
tt = party_ref("transfer_target", "Transfer Target", need_target)
if tt is not None:
ev["transfer_target"] = tt
if t in ("consultation-start", "consultative-transfer"):
ev["consultation"] = cons_sess
elif t == "transfer-abandoned" and cons_sess is not None:
ev["consultation"] = cons_sess
if t in ("blind-transfer", "consultative-transfer"):
ev["target_session"] = target_sess
ctx.events.append(ev)
extra = sorted(
set(tr)
- {"type", "start", "transferee", "transferor", "transfer_target", "original", "consultation", "target_dialog", "parties", "party_history"}
)
if extra or tr.get("parties"):
ctx.report.add(
step, UNRESOLVED,
f"transfer dialog[{k}] had parameters with no Event equivalent "
f"({extra + (['parties'] if tr.get('parties') else [])}); not migrated. "
"Original kept in report.removed_dialogs.", None, dialog=k,
dropped={f: tr[f] for f in extra + (["parties"] if tr.get("parties") else [])},
)
def _step_t6_originator(ctx: _Context) -> None:
"""T6: ``originator`` moves from the Dialog to the Session (only when not the first party)."""
dialogs = ctx.out.get("dialog")
if not isinstance(dialogs, list):
return
for i in ctx.kept():
d = dialogs[i]
if "originator" in d:
val = d.pop("originator")
if _is_int(val):
ctx.originators[i] = val
else:
ctx.report.add("T6", UNRESOLVED, f"dialog[{i}] originator {val!r} is not a party index; dropped.", None, dialog=i)
def _step_t7_recording_sets(ctx: _Context) -> None:
"""T7: each ``recording-set`` Dialog becomes a Session listing its recordings.
The recording-set's own start, duration, parties, session_id and originator
move to the Session (A.1 is silent: AMB-4). ``recording_set`` is removed from
each recording.
Membership is the union of the set's ``recordings`` list and the recordings
whose ``recording_set`` points at it (core-04 made ``recordings`` MUST and
``recording_set`` SHOULD, so stored data can carry either side only). A
recording-set listed in another recording-set's ``recordings`` becomes a
``child`` Session_Reference of that set's Session. Every Session index is
allocated before any is filled, so a nested set can point forward.
"""
dialogs = ctx.out.get("dialog")
rs_ids = [k for k, kind in ctx.removed.items() if kind == "recording-set"]
for k in rs_ids:
ctx.rs_session[k] = ctx.new_session({})
# recording_set back-references from kept Dialogs.
back: Dict[int, List[int]] = {}
for i in ctx.kept():
ref = ctx.dialogs[i].get("recording_set")
if ref is None:
continue
if _is_int(ref) and ref in ctx.rs_session:
back.setdefault(ref, []).append(i)
else:
ctx.report.add(
"T7", UNRESOLVED,
f"dialog[{i}] recording_set={ref!r} does not reference a recording-set Dialog; "
"parameter removed, no Session membership derived from it.", None, dialog=i, recording_set=ref,
)
for k in rs_ids:
rs = ctx.dialogs[k]
sidx = ctx.rs_session[k]
recs_raw = rs.get("recordings")
recs: List[int] = []
children: List[int] = []
if isinstance(recs_raw, list):
for r in recs_raw:
if _is_int(r) and r in ctx.rs_session and r != k:
if ctx.rs_session[r] not in children:
children.append(ctx.rs_session[r])
elif _is_int(r) and 0 <= r < len(ctx.dialogs) and r not in ctx.removed and isinstance(ctx.dialogs[r], dict) and ctx.dialogs[r]:
if r not in recs:
recs.append(r)
else:
ctx.report.add("T7", UNRESOLVED, f"recording-set dialog[{k}] lists recordings entry {r!r}, which is not a kept Dialog or another recording-set; left out of the Session.", None, dialog=k, entry=r)
else:
ctx.report.add("T7", UNRESOLVED, f"recording-set dialog[{k}] has no recordings list.", None, dialog=k)
added_back = [i for i in back.get(k, []) if i not in recs]
if added_back:
recs.extend(added_back)
ctx.report.add(
"T7", INFERRED,
f"dialog(s) {added_back} name recording-set dialog[{k}] in recording_set but are not in its "
f"recordings list; added to Session {sidx}.", None, dialog=k, added=added_back, session=sidx,
)
sess: Dict[str, Any] = {}
d_start, d_dur = ctx.span(recs) if recs else (None, None)
if _parse_dt(rs.get("start")):
sess["start"] = rs["start"]
elif d_start is not None:
sess["start"] = d_start
if isinstance(rs.get("duration"), (int, float)) and not isinstance(rs.get("duration"), bool):
sess["duration"] = rs["duration"]
elif d_dur is not None:
sess["duration"] = d_dur
rs_parties = _plain_parties(rs.get("parties"))
parties = rs_parties or _union([ctx.receivers.get(r, []) for r in recs])
if parties:
sess["parties"] = parties
orig = rs.get("originator")
if _is_int(orig) and (not parties or orig != parties[0]):
sess["originator"] = orig
elif orig is not None and not _is_int(orig):
ctx.report.add("T7", UNRESOLVED, f"recording-set dialog[{k}] originator {orig!r} is not a party index; dropped.", None, dialog=k)
sid = rs.get("session_id")
if isinstance(sid, dict):
sess["session_id"] = sid
elif isinstance(sid, list) and len(sid) == 1 and isinstance(sid[0], dict):
sess["session_id"] = sid[0]
elif sid is not None:
ctx.report.add(
"T7", UNRESOLVED,
f"recording-set dialog[{k}] session_id is not a single SessionId Object; Session.session_id not set.",
"AMB-4", dialog=k, session_id=sid,
)
if children:
sess["sessions"] = [{"session": c, "type": "child"} for c in children]
ctx.report.add(
"T7", INFERRED,
f"recording-set dialog[{k}] lists other recording-set(s); Session {sidx} references their "
f"Session(s) {children} as 'child'.", "AMB-1", dialog=k, session=sidx, children=children,
)
if recs:
sess["dialog"] = recs
order = ("start", "duration", "parties", "originator", "session_id", "sessions", "dialog")
ctx.sessions[sidx] = {key: sess[key] for key in order if key in sess}
for r in recs:
ctx.dialog_sessions.setdefault(r, []).append(sidx)
fields_moved = [f for f in ("start", "duration", "parties", "session_id", "originator") if f in rs]
ctx.report.add(
"T7", INFERRED,
f"recording-set dialog[{k}] -> Session {sidx}; its {fields_moved} moved to the Session "
"(A.1 silent about them); Session start/duration/parties fall back to values derived from the recordings when absent.",
"AMB-4", dialog=k, session=sidx,
)
extra = sorted(
set(rs) - {"type", "recordings", "start", "duration", "parties", "session_id", "originator", "party_history"}
)
if extra:
ctx.report.add(
"T7", UNRESOLVED,
f"recording-set dialog[{k}] had parameter(s) {extra} with no Session equivalent; not migrated. "
"Original kept in report.removed_dialogs.", None, dialog=k, dropped={f: rs[f] for f in extra},
)
if ctx.catch_all is not None and recs:
ctx.report.add(
"T7", UNRESOLVED,
f"Session {sidx} (recording-set dialog[{k}]) overlaps Session {ctx.catch_all}, which also lists its "
"recordings; A.1 does not say whether to relate them, so no Session_Reference was added.",
"AMB-1", session=sidx, catch_all=ctx.catch_all,
)
# recording_set has been consumed above; recordings is only legal on recording-sets.
if isinstance(dialogs, list):
for i in ctx.kept():
dialogs[i].pop("recording_set", None)
if "recordings" in dialogs[i]:
ctx.report.add(
"T7", UNRESOLVED,
f"dialog[{i}] ({ctx.dialogs[i].get('type')!r}) had a recordings parameter, which only a "
"recording-set may carry; removed.", None, dialog=i, recordings=dialogs[i].pop("recordings"),
)
def _first_slot_is_null(parties: Any) -> bool:
return isinstance(parties, list) and len(parties) > 0 and parties[0] is None
def _unknown_first_party(ctx: _Context, step: str, i: int, kind: str, role: str) -> int:
"""The first party slot of a text/incomplete Dialog is null: its sender is unknown.
The next party in the list is a receiver, so promoting it would invent a
sender. An empty Party Object stands in (4.2.4: "If the originator is not
known, an empty Party Object ... may be used"), and it becomes the Session
originator so the first receiver is not implied to be the originator.
"""
e = ctx.empty_party(step, role)
ctx.originators[i] = e
ctx.report.add(
step, UNRESOLVED,
f"{kind} dialog[{i}] has null as its first party, so its {role} is unknown; an empty Party "
f"Object (parties[{e}]) stands in rather than promoting a receiver.", None, dialog=i, party=e,
)
return e
def _step_t8_text_parties(ctx: _Context) -> None:
"""T8: a ``text`` Dialog's ``parties`` reduce to the sender; all parties go to the Session."""
dialogs = ctx.out.get("dialog")
if not isinstance(dialogs, list):
return
for i in ctx.kept():
if ctx.dialogs[i].get("type") != "text":
continue
p = _plain_parties(ctx.dialogs[i].get("parties"))
if not p:
ctx.report.add("T8", UNRESOLVED, f"text dialog[{i}] has no parties; sender and receivers unknown.", None, dialog=i)
continue
orig = ctx.dialogs[i].get("originator")
if _is_int(orig):
sender = orig
elif _first_slot_is_null(ctx.dialogs[i].get("parties")):
sender = _unknown_first_party(ctx, "T8", i, "text", "sender")
else:
sender = p[0]
dialogs[i]["parties"] = [sender]
ctx.receivers[i] = p if sender in p else [sender] + p
def _step_t9_incomplete_parties(ctx: _Context) -> None:
"""T9: an ``incomplete`` Dialog's ``parties`` reduce to the originator (or first party)."""
dialogs = ctx.out.get("dialog")
if not isinstance(dialogs, list):
return
for i in ctx.kept():
if ctx.dialogs[i].get("type") != "incomplete":
continue
p = _plain_parties(ctx.dialogs[i].get("parties"))
if not p:
continue
orig = ctx.dialogs[i].get("originator")
if _is_int(orig):
who = orig
elif _first_slot_is_null(ctx.dialogs[i].get("parties")):
who = _unknown_first_party(ctx, "T9", i, "incomplete", "originator")
else:
who = p[0]
dialogs[i]["parties"] = [who]
ctx.receivers[i] = p if who in p else [who] + p
def _step_t9b_recording_parties(ctx: _Context) -> None:
"""T9b: other Dialogs keep ``parties`` (contributors); the Session gets the union (AMB-6)."""
idxs = []
for i in ctx.kept():
if ctx.dialogs[i].get("type") in ("text", "incomplete"):
continue
p = _plain_parties(ctx.dialogs[i].get("parties"))
if p:
ctx.receivers[i] = p
idxs.append(i)
if idxs:
ctx.report.add(
"T9b", INFERRED,
f"Dialog(s) {idxs} (recording or other type): parties left as the contributors; "
"the Session parties are the union of the contributors across its Dialogs (A.1 gives no rule).",
"AMB-6", dialogs=idxs,
)
texts = [i for i in ctx.kept() if ctx.dialogs[i].get("type") == "text"]
if texts:
sets = {tuple(sorted(ctx.receivers.get(i, []))) for i in texts}
if len(sets) > 1:
ctx.report.add(
"T8", UNRESOLVED,
f"text Dialogs {texts} have different receiver sets; they were put in one Session whose parties "
"are the union. 4.5.4 prescribes a parent Session with a child Session per receiver set; that "
"split was not made.", "AMB-5", dialogs=texts,
)
if any(len(s) > 2 for s in sets):
ctx.report.add(
"T8", UNRESOLVED,
"0.4.0 parties do not distinguish To, Cc and Bcc, so Bcc recipients cannot be identified or "
"excluded.", "AMB-5", dialogs=texts,
)
def _step_t10_blank_removed(ctx: _Context) -> None:
"""T10: each removed Dialog is replaced in place by ``{}`` so no index moves."""
dialogs = ctx.out.get("dialog")
if not isinstance(dialogs, list):
return
for k, kind in ctx.removed.items():
ctx.report.removed_dialogs[k] = copy.deepcopy(ctx.dialogs[k])
dialogs[k] = {}
ctx.report.add("T10", INFO, f"dialog[{k}] ({kind}) replaced by an empty Dialog Object; index {k} unchanged.", None, dialog=k)
if len(dialogs) != len(ctx.dialogs): # pragma: no cover - internal guard
raise MigrationError("T10: dialog array length changed; indices would break")
def _merge_index(existing: Any, new: List[int]) -> Any:
cur = [] if existing is None else (existing if isinstance(existing, list) else [existing])
merged = list(cur)
for n in new:
if n not in merged:
merged.append(n)
return merged[0] if len(merged) == 1 else merged
def _step_t10b_retarget(ctx: _Context) -> None:
"""AMB-2: re-point analysis and attachment references to removed Dialogs.
Recording-set: Analysis.dialog is expanded to the recordings and ``sessions``
gets the recording-set's Session; an Attachment (single ``dialog`` index)
gets ``session`` instead. Transfer: the reference moves to the Session of the
transfer's original call. Nothing is left pointing at a ``{}`` Dialog.
"""
removed = ctx.removed
if not removed:
return
def targets(e: int) -> Tuple[List[int], Optional[int]]:
"""(replacement dialog indices, session index) for a removed Dialog."""
if removed[e] == "recording-set":
sidx = ctx.rs_session.get(e)
recs = ctx.sessions[sidx].get("dialog", []) if sidx is not None else []
return list(recs), sidx
return [], ctx.transfer_session.get(e)
for n, an in enumerate(ctx.out.get("analysis") or []):
if not isinstance(an, dict) or "dialog" not in an:
continue
old = an["dialog"]
items = old if isinstance(old, list) else [old]
if not any(_is_int(x) and x in removed for x in items):
continue
new_dialogs: List[int] = []
sess_add: List[int] = []
for x in items:
if _is_int(x) and x in removed:
reps, sidx = targets(x)
new_dialogs.extend(r for r in reps if r not in new_dialogs)
if sidx is not None:
sess_add.append(sidx)
elif x not in new_dialogs:
new_dialogs.append(x)
if new_dialogs:
an["dialog"] = new_dialogs[0] if (len(new_dialogs) == 1 and not isinstance(old, list)) else new_dialogs
else:
del an["dialog"]
if sess_add:
an["sessions"] = _merge_index(an.get("sessions"), sess_add)
ctx.report.add(
"T10b", INFERRED,
f"analysis[{n}].dialog {old!r} pointed at a removed Dialog; now dialog={an.get('dialog')!r}, "
f"sessions={an.get('sessions')!r}.", "AMB-2", analysis=n,
)
for n, att in enumerate(ctx.out.get("attachments") or []):
if not isinstance(att, dict) or not (_is_int(att.get("dialog")) and att["dialog"] in removed):
continue
e = att["dialog"]
_, sidx = targets(e)
del att["dialog"]
if sidx is not None:
att["session"] = _merge_index(att.get("session"), [sidx])
ctx.report.add(
"T10b", INFERRED,
f"attachments[{n}].dialog={e} pointed at a removed Dialog; replaced by session={att['session']!r}.",
"AMB-2", attachment=n,
)
else:
ctx.report.add(
"T10b", UNRESOLVED,
f"attachments[{n}].dialog={e} pointed at a removed Dialog with no Session to re-point to; "
"the attachment now has neither dialog nor session.", "AMB-2", attachment=n,
)
def _step_t10c_unscoped_attachments(ctx: _Context) -> None:
"""Scope an attachment that has neither ``dialog`` nor ``session``.
Core-04 required ``dialog``, but older writers omitted it, so stored data
has such attachments. Core-05 needs one of ``dialog`` or ``session``
(4.6.4). Only when the result has exactly one Session is the scope
unambiguous (that Session is the whole conversation); it is then set and
reported. Otherwise nothing is invented and the gap is reported.
"""
for n, att in enumerate(ctx.out.get("attachments") or []):
if not isinstance(att, dict) or "dialog" in att or "session" in att:
continue
if len(ctx.sessions) == 1:
att["session"] = 0
ctx.report.add(
"T10c", INFERRED,
f"attachments[{n}] had neither dialog nor session; scoped to the only Session (session=0).",
None, attachment=n, purpose=att.get("purpose"),
)
else:
ctx.report.add(
"T10c", UNRESOLVED,
f"attachments[{n}] has neither dialog nor session and the vCon has {len(ctx.sessions)} "
"Sessions, so its scope cannot be chosen; set dialog or session by hand.",
None, attachment=n, purpose=att.get("purpose"),
)
def _step_t13_unwrap_signed(ctx: _Context) -> None:
"""T13: a signed vCon is migrated as its unsigned payload; it must be signed again.
``alg: "none"`` is no longer permitted, so such a vCon is flagged explicitly.
The migration never signs.
"""
out = ctx.out
if "ciphertext" in out and ("recipients" in out or "protected" in out):
raise MigrationError("T13: the input is an encrypted (JWE) vCon; decrypt it before migrating")
if "payload" in out and "signatures" in out:
try:
raw = out["payload"]
payload = json.loads(base64.urlsafe_b64decode(raw + "=" * (-len(raw) % 4)))
except Exception as e:
raise MigrationError(f"T13: could not decode the signed vCon payload: {e}") from e
if not isinstance(payload, dict):
raise MigrationError("T13: the signed vCon payload is not a JSON object")
algs = []
for sig in out.get("signatures") or []:
try:
hdr = sig.get("protected")
if hdr:
algs.append(json.loads(base64.urlsafe_b64decode(hdr + "=" * (-len(hdr) % 4))).get("alg"))
if isinstance(sig.get("header"), dict) and "alg" in sig["header"]:
algs.append(sig["header"]["alg"])
except Exception:
continue
ctx.out = payload
ctx.report.resign_required = True
ctx.report.add(
"T13", UNRESOLVED,
"The input was signed. It was migrated as the unsigned payload; the signature was dropped. "
"Re-signing is required, and signing changes updated_at (4.1.6).", None,
)
if any(isinstance(a, str) and a.lower() == "none" for a in algs):
ctx.report.add(
"T13", UNRESOLVED,
"A signature used alg 'none', which 0.5.0 forbids; sign again with a permitted algorithm.", None,
)
ctx.src = copy.deepcopy(ctx.out)
ctx.report.source_version = ctx.out.get("vcon")
def _step_t14_extensions(ctx: _Context) -> None:
"""T14: ``extensions`` must list every extension in use (MUST, was SHOULD)."""
names, unnamed = extensions_in_use(ctx.out)
listed = ctx.out.get("extensions")
listed = list(listed) if isinstance(listed, list) else []
added = []
for name in sorted(names):
if name not in listed:
listed.append(name)
added.append(name)
for name in ctx.out.get("critical") or []:
if isinstance(name, str) and name not in listed:
listed.append(name)
added.append(name)
if added:
ctx.out["extensions"] = listed
ctx.report.add("T14", INFERRED, f"Added extension name(s) {added} to extensions.", None, added=added)
if unnamed and not listed:
ctx.report.add(
"T14", UNRESOLVED,
"Values outside the core vocabulary are in use but their defining extension cannot be identified: "
+ "; ".join(unnamed) + ". extensions was not changed.", None, uses=unnamed,
)
def _step_t15_duplicate_headers(ctx: _Context) -> None:
"""T15: duplicate header parameters in signed or encrypted forms are tolerated on read."""
if ctx.report.resign_required:
ctx.report.add(
"T15", INFO,
"Header parameters repeated across JWS headers are not checked or rejected on read; "
"writers must not emit duplicates in 0.5.0.",
)
# T11 and T12 are renames at the top level; implemented with an order-preserving helper.
def _rename_top(ctx: _Context, old: str, new: str, step: str) -> None:
if old in ctx.out:
ctx.out = _rename_key(ctx.out, old, new)
ctx.report.add(step, INFO, f"Renamed '{old}' to '{new}'.")
def _step_t11(ctx: _Context) -> None:
"""T11: ``redacted`` -> ``redacted_from`` (same fields)."""
_rename_top(ctx, "redacted", "redacted_from", "T11")
def _step_t12(ctx: _Context) -> None:
"""T12: ``amended`` -> ``amended_from`` (same fields)."""
_rename_top(ctx, "amended", "amended_from", "T12")
[docs]@dataclass(frozen=True)
class MigrationStep:
id: str
title: str
source: str # where the draft says it
func: Callable[[_Context], None]
#: One entry per step of the ordered transform table (Appendix A.1), in execution order.
MIGRATION_STEPS: List[MigrationStep] = [
MigrationStep("T13", "Signed input: migrate the payload, require re-signing", "A.1 bullet 11; 6.2.2", _step_t13_unwrap_signed),
MigrationStep("T15", "Duplicate header parameters tolerated on read", "A.1 bullet 13", _step_t15_duplicate_headers),
MigrationStep("T1", "vcon 0.4.0 -> 0.5.0", "A.1 bullet 1", _step_t1_version),
MigrationStep("T8", "text Dialog parties -> sender; all parties to Session", "A.1 bullet 6", _step_t8_text_parties),
MigrationStep("T9", "incomplete Dialog parties -> originator/first", "A.1 bullet 6", _step_t9_incomplete_parties),
MigrationStep("T9b", "other Dialog parties kept; union to Session", "4.5.4 (A.1 silent)", _step_t9b_recording_parties),
MigrationStep("T6", "Dialog originator -> Session originator", "A.1 bullet 5", _step_t6_originator),
MigrationStep("T2", "Add a Session referencing all Dialogs", "A.1 bullet 2", _step_t2_sessions),
MigrationStep("T7", "recording-set Dialog -> Session", "A.1 bullet 9", _step_t7_recording_sets),
MigrationStep("T4", "transfer Dialog -> transfer Events (with T5 Session references)", "A.1 bullet 4", _step_t4_transfers),
MigrationStep("T3", "party_history -> Events", "A.1 bullet 3", _step_t3_party_history),
MigrationStep("T10", "Removed Dialogs -> {} in place", "A.1 bullet 10; 4.5.1", _step_t10_blank_removed),
MigrationStep("T10b", "Re-point analysis/attachment references to removed Dialogs", "AMB-2", _step_t10b_retarget),
MigrationStep("T10c", "Scope unscoped attachments to the only Session", "4.6.4 (A.1 silent)", _step_t10c_unscoped_attachments),
MigrationStep("T11", "redacted -> redacted_from", "A.1 bullet 7", _step_t11),
MigrationStep("T12", "amended -> amended_from", "A.1 bullet 8", _step_t12),
MigrationStep("T14", "extensions lists every extension in use", "A.1 bullet 12; 4.1.3", _step_t14_extensions),
]
[docs]def migrate_0_4_0_to_0_5_0(vcon: Any, *, strict: bool = False) -> MigrationResult:
"""Migrate a 0.4.0 vCon dict (or JSON string) to 0.5.0.
Args:
vcon: The 0.4.0 vCon as a dict or JSON string. A signed vCon (JWS general
form) is migrated as its unsigned payload. The input is not modified.
strict: When True, raise :class:`MigrationError` instead of using a
fallback for a MUST field that cannot be sourced from the input.
Returns:
``MigrationResult(vcon, report)``: the 0.5.0 dict and the
:class:`MigrationReport` listing every inferred value, fallback and
unresolved item.
Raises:
MigrationError: the input is not a 0.4.0 vCon, is encrypted, or (strict)
a required field has no source.
"""
if isinstance(vcon, (str, bytes)):
try:
vcon = json.loads(vcon)
except json.JSONDecodeError as e:
raise MigrationError(f"input is not valid JSON: {e}") from e
if not isinstance(vcon, dict):
raise MigrationError("input must be a vCon dict or JSON string")
data = copy.deepcopy(vcon)
report = MigrationReport(strict=strict)
ctx = _Context(data, strict, report)
version = data.get("vcon")
if version is not None and version != SOURCE_VERSION and not ("payload" in data and "signatures" in data):
raise MigrationError(
f"cannot migrate: input vcon is {version!r}, expected {SOURCE_VERSION!r}"
)
for step in MIGRATION_STEPS:
report.steps_run.append(step.id)
step.func(ctx)
if step.id == "T13":
v = ctx.out.get("vcon")
if v is not None and v != SOURCE_VERSION:
raise MigrationError(f"cannot migrate: input vcon is {v!r}, expected {SOURCE_VERSION!r}")
if v is None:
markers = sorted(k for k in _V050_ONLY_KEYS if k in ctx.out)
if markers:
raise MigrationError(
f"cannot migrate: input has no 'vcon' parameter but has 0.5.0-only "
f"parameter(s) {markers}; it is already 0.5.0 (vcon is optional there)"
)
report.add("T13", INFO, "Input has no 'vcon' parameter; treated as 0.4.0.")
out = ctx.out
if ctx.sessions:
out["sessions"] = ctx.sessions
if ctx.events:
out["events"] = ctx.events
# Lawful basis attachments keep their 0.4.0 scope (dialog). 0.5.0 scopes them with
# session plus party; adding a Session reference would be inventing a scope.
for n, att in enumerate(out.get("attachments") or []):
if isinstance(att, dict) and att.get("purpose") == "lawful_basis" and "session" not in att:
report.add(
"post", INFO,
f"attachments[{n}] is a lawful_basis attachment scoped by dialog only; it was left as is. "
"0.5.0 scopes a lawful basis to Sessions with 'session' (plus 'party'); add it if it covers the Session.",
None, attachment=n,
)
# Post-check: the result must satisfy the core-05 rules; anything left is reported.
from .dialog import Dialog
errors, _ = validate_vcon_dict(out, Dialog.MIME_TYPES)
for err in errors:
report.add("post", UNRESOLVED, f"Result does not validate: {err}")
logger.info("Migrated vCon %s to 0.5.0: %s", out.get("uuid"), report.summary())
return MigrationResult(out, report)