Upload _dataset_schema.py

_dataset_schema.py

@@ -1,10 +1,10 @@
-# scikitplot/_externals/_sphinx_ext/_sphinx_ai_assistant/_hf_spaces_proxy/dataset_schema.py
+# scikitplot/_externals/_sphinx_ext/_sphinx_ai_assistant/_hf_spaces_proxy/_dataset_schema.py
 #
 # Authors: The scikit-plots developers
 # SPDX-License-Identifier: BSD-3-Clause
 #
 # Canonical schema and record-normalization for the AI-assistant dataset.
-# Version: 1.0.0
+# Version: 2.0.0  (see "Schema version history" in the module docstring)
 
 """
 Canonical schema, normalization, and pandas loading for the AI-assistant dataset.
@@ -36,8 +36,8 @@ Canonical key order (identical in every row)
     schemaVersion
     _source           _ts            _dedup_key
     conversationId    feedbackId
-    answerIndex       action         prevFeedbackId    status
-    ratingValue       ratingSlug     ratingTitle       ratingMode    message
+    answerIndex       action         prevFeedbackId    editCount    status
+    ratingValue       ratingSlug     ratingTitle       ratingMode   message
     query             answer
     model
     page              consentVersion
@@ -48,7 +48,7 @@ Notes
 User note
     Load the full dataset in one line::
 
-        from dataset_schema import load_dataset
+        from _dataset_schema import load_dataset
         df = load_dataset("feedback/", "contributions/")
 
 Developer note — Rating vocabulary
@@ -59,21 +59,80 @@ Developer note — Rating vocabulary
     derived to populate ``ratingSlug`` / ``ratingLabel``.
 
 Developer note — Model shape
-    Feedback records used ``model: {id, provider, model}`` (3 keys).
-    Contribution records used ``_model: {default, id, label, provider, model,
-    endpoint, info_url, description}`` (8 keys).  Both are now written as
-    ``model`` with all 8 keys present; missing keys are ``None``.
-
-Developer note — Retraction records
+    Both feedback and contribution payloads now build the model object via the
+    shared client-side ``_buildModelInfo(cfg)`` helper, so every record that
+    carries model attribution has the **same 8-key shape** (see
+    :data:`MODEL_KEYS`): ``id, provider, model, label, endpoint, info_url,
+    description, default``.  :func:`normalize_model` still projects *any*
+    input dict (including pre-v2 3-key ``{id, provider, model}`` records) onto
+    this 8-key shape for backward compatibility — missing keys become
+    ``None``.
+
+Developer note — Retraction records (``action="retract"``)
     A retraction payload has ``action="retract"`` and ``prevSessionId`` pointing
     to the ``sessionId`` (= ``feedbackId``) of the record being invalidated.
     The normalised form uses ``prevFeedbackId`` for clarity and fills all rating /
     content / model fields with ``None``.
 
+Developer note — Supersession chains (``action="rate"`` + ``prevFeedbackId``)
+    When a user edits a previously submitted rating, the **new** ``rate``
+    record now also carries ``prevFeedbackId`` = the ``feedbackId`` of the
+    rating it replaces (in addition to the separate ``retract`` tombstone for
+    the old record).  This gives downstream tooling a direct, walkable edit
+    history per ``(conversationId, answerIndex)`` without having to infer
+    chains purely from ``_ts`` ordering.  ``editCount`` is a monotonically
+    increasing counter (``0`` for the first rating, ``+1`` per edit) carried
+    alongside ``prevFeedbackId`` for quick "rating churn" analysis without
+    walking the chain.
+
+Developer note — ``feedbackId`` cross-source linkage
+    Contribution records now carry ``feedbackId`` = the ``feedbackId`` of the
+    per-answer feedback event that was active when the user clicked
+    "Contribute" (``None`` when the user never rated that answer
+    individually).  This is a **direct foreign key** between a
+    ``contributions/`` row and a ``feedback/`` row — in addition to the
+    coarser ``_dedup_key`` (``"{conversationId}:{answerIndex}"``) — and is the
+    preferred join key for ``deduplicate_dataset.py`` going forward.
+
+Developer note — ``consentVersion`` (reserved)
+    Consent-version tracking is **not currently enforced**.
+    :data:`CONSENT_VERSION_ENABLED` is ``False``, so :func:`normalize_record`,
+    :func:`normalize_feedback_record`, and :func:`normalize_contribution_record`
+    all write ``consentVersion: null`` regardless of what the client sends —
+    including historical records that stored ``"v1.0"``.  This keeps every row
+    in the combined DataFrame consistent.  See :data:`RESERVED_CONSENT_VERSION`
+    for the value to adopt when this feature is implemented.
+
+Schema version history
+-----------------------
+``schemaVersion: 1`` (initial canonical schema)
+    ``feedbackId`` / ``prevFeedbackId`` always ``None`` for contribution
+    records; ``prevFeedbackId`` only set on ``action="retract"`` feedback
+    records; ``model`` may be a 3-key ``{id, provider, model}`` dict (quick
+    feedback) or 8-key dict (panel/contribution); ``consentVersion`` may be
+    ``"v1.0"`` on contribution records; no ``editCount`` column.
+
+``schemaVersion: 2`` (this version) — additive, backward compatible
+    * ``feedbackId`` populated on contribution records when the answer was
+      individually rated before contributing (see "feedbackId cross-source
+      linkage" above).
+    * ``prevFeedbackId`` populated on ``action="rate"`` records (both sources)
+      when the rating supersedes a prior one (see "Supersession chains" above).
+    * New ``editCount`` column (``int``, default ``0``).
+    * ``model`` is always the full 8-key shape when present (see "Model shape"
+      above); old 3-key records are still readable via :func:`normalize_model`.
+    * ``consentVersion`` is always ``None`` (see "consentVersion (reserved)"
+      above); old ``"v1.0"`` values are normalised away on read.
+
+    :func:`normalize_record` reads ``schemaVersion: 1`` rows transparently —
+    all v2-only fields default via ``setdefault`` (``feedbackId=None``,
+    ``prevFeedbackId=None``, ``editCount=0``).
+
 References
 ----------
-See ``DATASET_COLLECTION_GUIDANCE.md`` for the deduplication contract and
-the training-pipeline usage of ``_source``, ``_dedup_key``, and ``status``.
+See ``DATASET_COLLECTION_GUIDANCE.md`` for the deduplication contract, the
+``feedbackId`` / ``prevFeedbackId`` supersession-chain resolution algorithm,
+and the training-pipeline usage of ``_source``, ``_dedup_key``, and ``status``.
 """
 
 from __future__ import annotations
@@ -89,8 +148,11 @@ from typing import Any
 # ─────────────────────────────────────────────────────────────────────────────
 
 #: Current schema version for records written by this module.
-#: Increment when a breaking field-name change is introduced.
-SCHEMA_VERSION: int = 1
+#: Increment when a breaking field-name change is introduced; additive
+#: changes (new optional columns, wider population of existing columns) bump
+#: this too so consumers can branch on ``schemaVersion`` to know which fields
+#: to expect.  See "Schema version history" above for what changed in v2.
+SCHEMA_VERSION: int = 2
 
 #: Ordered list of canonical column names.  Every stored JSONL row and every
 #: row in the pandas DataFrame will have these columns in exactly this order.
@@ -103,11 +165,20 @@ CANONICAL_COLUMNS: list[str] = [
     "_dedup_key",       # "{conversationId}:{answerIndex}"
     # ── Session identity ──────────────────────────────────────────────────────
     "conversationId",   # stable per-page-load chat session UUID
-    "feedbackId",       # per-feedback-event idempotency key (None for contributions)
+    "feedbackId",       # per-feedback-event id. For contributions: the feedbackId
+                        # of the matching per-answer feedback event, or None if
+                        # the user never rated this answer individually.
     # ── Record descriptor ─────────────────────────────────────────────────────
     "answerIndex",      # 0-based position of answer in the conversation
     "action",           # "rate" | "retract"
-    "prevFeedbackId",   # for retracts: feedbackId of the record being invalidated
+    "prevFeedbackId",   # feedbackId of the record this one supersedes/invalidates.
+                        # action="rate":    set when this rating replaces an earlier
+                        #                   one for the same answerIndex (an edit).
+                        # action="retract": set to the feedbackId being retracted.
+                        # None for a first-time rating.
+    "editCount",        # int: 0 for the first rating; +1 each time the user
+                        # edits/re-rates the same answer (mirrors prevFeedbackId
+                        # chain length without walking it). None for retracts.
     "status",           # "active" | "retracted"  (dedup pipeline manages)
     # ── Rating ────────────────────────────────────────────────────────────────
     "ratingValue",      # int | None: numeric score (-5..+5 for panel; -1|+1 for quick)
@@ -122,7 +193,8 @@ CANONICAL_COLUMNS: list[str] = [
     "model",            # dict | None: normalised 8-key model object (see MODEL_KEYS)
     # ── Context ───────────────────────────────────────────────────────────────
     "page",             # str: documentation page URL
-    "consentVersion",   # str | None: "v1.0" for contributions; None for feedback
+    "consentVersion",   # str | None: reserved for future use — always None while
+                        # CONSENT_VERSION_ENABLED is False (see below)
     # ── Timestamps ────────────��──────────────────────────────────────────────
     "ts",               # int: client-side event time, ms since epoch
 ]
@@ -141,6 +213,161 @@ MODEL_KEYS: list[str] = [
     "default",      # bool | None: True when this is the default model in the config
 ]
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Consent-version handling (reserved for future use)
+# ─────────────────────────────────────────────────────────────────────────────
+
+#: Master switch for consent-version tracking.  While ``False`` (current
+#: state), every normaliser writes ``consentVersion: null`` regardless of what
+#: the client sent — including historical contribution records that stored
+#: ``"v1.0"`` — so the column is uniformly ``None`` across the whole dataset.
+#:
+#: To activate consent-version tracking in the future:
+#:   1. Set this to ``True``.
+#:   2. Set :data:`RESERVED_CONSENT_VERSION` to the real version string
+#:      (e.g. keep ``"1.0.0"``, or bump it).
+#:   3. In ``ai-assistant.js``, uncomment the ``CONSENT_VERSION`` constant and
+#'      change ``consentVersion: null`` back to ``consentVersion: CONSENT_VERSION``
+#:      in the ``/v1/contribute`` payload (see the matching comment there).
+CONSENT_VERSION_ENABLED: bool = False
+
+#: Semantic version string reserved for the consent-banner copy/flow, for use
+#: once :data:`CONSENT_VERSION_ENABLED` is flipped to ``True``.  Bump this
+#: whenever consent terms change materially.  Currently unused.
+RESERVED_CONSENT_VERSION: str = "1.0.0"
+
+
+def _resolve_consent_version(raw: Any) -> str | None:
+    """Resolve the ``consentVersion`` field for a normalised record.
+
+    Parameters
+    ----------
+    raw : Any
+        The raw ``consentVersion``-like value from the payload or a
+        previously stored record (feedback payloads never had one;
+        contribution envelopes/records may carry ``"v1.0"`` or ``null``).
+
+    Returns
+    -------
+    str or None
+        ``None`` while :data:`CONSENT_VERSION_ENABLED` is ``False`` (current
+        behaviour) — *regardless* of ``raw``, so historical ``"v1.0"`` values
+        are normalised away too.  Once enabled, ``raw`` is passed through
+        unchanged if it is a non-empty string, else ``None`` (this function
+        never *invents* a consent version for a record that did not declare
+        one — :data:`RESERVED_CONSENT_VERSION` is purely documentation for
+        what the JS widget should send once re-enabled).
+
+    Notes
+    -----
+    Developer note
+        Centralising this here means flipping :data:`CONSENT_VERSION_ENABLED`
+        is the *only* code change needed in this module; both normalisers and
+        :func:`normalize_record` already call this function.
+
+    Examples
+    --------
+    >>> _resolve_consent_version("v1.0")   # CONSENT_VERSION_ENABLED=False
+    >>> _resolve_consent_version(None)
+    """
+    if not CONSENT_VERSION_ENABLED:
+        return None
+    return raw if isinstance(raw, str) and raw else None
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Defensive ID coercion
+# ─────────────────────────────────────────────────────────────────────────────
+
+#: Hard upper bound on stored identifier strings (``feedbackId``,
+#: ``prevFeedbackId``, ``conversationId``).  Generated values (UUIDs, or the
+#: ``"{uuid}-quick-{idx}-{ts}"`` composite) are well under 100 chars; 256
+#: leaves generous headroom while bounding worst-case row size if a malformed
+#: or malicious client sends an oversized string.
+_MAX_ID_LEN: int = 256
+
+
+def _safe_id(value: Any) -> str | None:
+    """Coerce a client-supplied identifier to a bounded ``str`` or ``None``.
+
+    Parameters
+    ----------
+    value : Any
+        Raw value from the client payload (expected: ``str`` or ``None``/
+        absent).  Any non-string (e.g. an accidental ``int``, ``list``, or
+        ``dict`` from a malformed client) is treated as absent.
+
+    Returns
+    -------
+    str or None
+        ``None`` for falsy/non-string input.  Otherwise the string,
+        truncated to :data:`_MAX_ID_LEN` characters.
+
+    Notes
+    -----
+    Developer note — Security
+        Applied to every ``*FeedbackId`` / ``conversationId`` field written by
+        the normalisers.  Prevents a malformed or adversarial payload (wrong
+        type, or a multi-MB string) from being written verbatim into the
+        dataset.  Truncation is preferred over rejection so a single bad field
+        does not fail an otherwise-valid submission — see Principle 2 (no
+        silent failures): truncation is itself loud in the sense that a
+        truncated UUID will simply never match anything in
+        ``deduplicate_dataset.py``'s join logic, which is the correct,
+        self-healing outcome for a corrupted ID.
+
+    Examples
+    --------
+    >>> _safe_id("57b73883-ba14-4a0c-ac38-79bc76a2c0ee")
+    '57b73883-ba14-4a0c-ac38-79bc76a2c0ee'
+    >>> _safe_id(None)
+    >>> _safe_id(12345)
+    >>> _safe_id("x" * 300)[-1] == "x" and len(_safe_id("x" * 300)) == 256
+    True
+    """
+    if not isinstance(value, str) or not value:
+        return None
+    return value[:_MAX_ID_LEN]
+
+
+def _safe_int(value: Any, default: int = 0) -> int:
+    """Coerce a client-supplied count to a non-negative ``int``.
+
+    Parameters
+    ----------
+    value : Any
+        Raw value (expected: small non-negative ``int``).  ``bool`` is
+        rejected even though ``bool`` is a subclass of ``int`` in Python,
+        since a stray ``True``/``False`` here indicates a client bug, not a
+        real edit count.
+    default : int, optional
+        Value returned for missing/invalid input.  Default ``0``.
+
+    Returns
+    -------
+    int
+        ``max(0, int(value))`` when ``value`` is a non-bool ``int``/``float``
+        representing a whole number; otherwise ``default``.
+
+    Examples
+    --------
+    >>> _safe_int(3)
+    3
+    >>> _safe_int(-1)
+    0
+    >>> _safe_int(None)
+    0
+    >>> _safe_int(True)
+    0
+    """
+    if isinstance(value, bool):
+        return default
+    if isinstance(value, int):
+        return max(0, value)
+    if isinstance(value, float) and value.is_integer():
+        return max(0, int(value))
+    return default
+
 # ── Rating vocabulary ─────────────────────────────────────────────────────────
 # The panel feedback 11-point scale.  ``value`` here is the slug stored as
 # ``ratingLabel`` in the JS source (_FEEDBACK_DEFAULTS[idx].value).
@@ -425,12 +652,23 @@ def normalize_feedback_record(
         arbitrary client-supplied fields directly into the dataset.  This
         implementation whitelists only the known fields from the JS schema,
         discarding unexpected keys.  The legacy ``rating`` alias is dropped
-        (its value was always identical to ``ratingLabel``).
-
-    Developer note — Retract records
-        When ``payload["action"] == "retract"`` the rating / content / model
-        fields are filled with ``None``; ``prevFeedbackId`` is set from
-        ``payload["prevSessionId"]``.
+        (its value was always identical to ``ratingLabel``).  All identifier
+        fields (``conversationId``, ``feedbackId``, ``prevFeedbackId``) are
+        passed through :func:`_safe_id` and ``editCount`` through
+        :func:`_safe_int` to bound type/size regardless of client input.
+
+    Developer note — Retract records (``action="retract"``)
+        ``prevFeedbackId`` is set from ``payload["prevSessionId"]`` —
+        the ``feedbackId`` of the record being invalidated.  ``editCount`` is
+        ``None`` (not applicable to a tombstone).
+
+    Developer note — Rate records with ``prevFeedbackId`` (edits)
+        When the new JS sends ``payload["prevFeedbackId"]`` on an
+        ``action="rate"`` record, it means this rating *replaces* an earlier
+        one for the same ``(conversationId, answerIndex)`` — the value is the
+        ``feedbackId`` of that earlier rating (a separate ``retract``
+        tombstone for it is sent too).  ``editCount`` is
+        ``payload["editCount"]`` (``0`` for a first-time rating).
 
     Developer note — ratingLabel normalization
         Old quick-feedback records set ``ratingLabel = opt.title`` (Title Case:
@@ -447,18 +685,24 @@ def normalize_feedback_record(
     is_retract: bool = payload.get("action") == "retract"
 
     # ── Identity ──────────────────────────────────────────────────────────────
-    conversation_id: str = payload.get("conversationId") or ""
+    conversation_id: str | None = _safe_id(payload.get("conversationId"))
     # Feedback sessionId is the per-submission idempotency key, renamed to
     # feedbackId to distinguish it from the chat-session conversationId.
-    feedback_id: str | None = payload.get("sessionId") or None
+    feedback_id: str | None = _safe_id(payload.get("sessionId"))
     answer_index: int | None = payload.get("answerIndex")
 
-    # ── Retract-specific fields ───────────────────────────────────────────────
-    # prevSessionId in the retract payload points to the sessionId (= feedbackId)
-    # of the original record being invalidated.
-    prev_feedback_id: str | None = (
-        payload.get("prevSessionId") or None if is_retract else None
-    )
+    # ── Supersession / edit-chain fields ──────────────────────────────────────
+    if is_retract:
+        # prevSessionId in the retract payload points to the sessionId
+        # (= feedbackId) of the original record being invalidated.
+        prev_feedback_id: str | None = _safe_id(payload.get("prevSessionId"))
+        edit_count: int | None = None  # not applicable to a tombstone
+    else:
+        # New JS sends prevFeedbackId on a "rate" record when this rating
+        # replaces an earlier one (an edit) — see "Rate records with
+        # prevFeedbackId" above.  None for a first-time rating.
+        prev_feedback_id = _safe_id(payload.get("prevFeedbackId"))
+        edit_count = _safe_int(payload.get("editCount"), default=0)
 
     # ── Rating (None for retracts) ────────────────────────────────────────────
     if is_retract:
@@ -476,7 +720,8 @@ def normalize_feedback_record(
             feedback_id=feedback_id,
         )
 
-    # ── Model (None for quick feedback and retracts) ──────────────────────────
+    # ── Model (None for retracts; populated for both quick and panel feedback
+    # since _buildModelInfo(cfg) is now used uniformly on the client) ─────────
     raw_model: dict | None = payload.get("model")
     if isinstance(raw_model, str):
         # Guard: old or malformed payloads sometimes send model as a bare string.
@@ -487,12 +732,13 @@ def normalize_feedback_record(
         "schemaVersion":  int(payload.get("schemaVersion") or SCHEMA_VERSION),
         "_source":        "feedback",
         "_ts":            server_ts_ms,
-        "_dedup_key":     f"{conversation_id}:{answer_index}",
-        "conversationId": conversation_id or None,
+        "_dedup_key":     f"{conversation_id or ''}:{answer_index}",
+        "conversationId": conversation_id,
         "feedbackId":     feedback_id,
         "answerIndex":    int(answer_index) if answer_index is not None else None,
         "action":         "retract" if is_retract else "rate",
         "prevFeedbackId": prev_feedback_id,
+        "editCount":      edit_count,
         "status":         "active",
         "ratingValue":    None if is_retract else payload.get("ratingValue"),
         "ratingSlug":     rating_fields["ratingSlug"],
@@ -503,7 +749,7 @@ def normalize_feedback_record(
         "answer":         "" if is_retract else (payload.get("answer") or ""),
         "model":          None if is_retract else normalize_model(raw_model),
         "page":           "" if is_retract else (payload.get("page") or ""),
-        "consentVersion": None,   # feedback is implicit consent; no version stored
+        "consentVersion": _resolve_consent_version(None),  # feedback never declares consent
         "ts":             payload.get("ts"),
     })
 
@@ -544,6 +790,15 @@ def normalize_contribution_record(
         because they are universal provenance fields managed exclusively by
         the server.
 
+    Developer note — ``feedbackId`` / ``prevFeedbackId`` / ``editCount``
+        ``tRecords`` (built client-side from ``_feedbackStore``) now forward
+        ``feedbackId`` (the per-answer feedback event's own ``sessionId``,
+        if the user rated this answer individually before contributing),
+        ``prevFeedbackId`` (set when that feedback event was itself an edit
+        of an earlier one), and ``editCount``.  All three pass through
+        :func:`_safe_id` / :func:`_safe_int`.  ``feedbackId`` is ``None`` when
+        the user contributed without ever rating that specific answer.
+
     Developer note — ``_ts`` consistency
         All rows in a single contribute batch share the same ``server_ts_ms``
         value.  The previous inline ``int(_time.time() * 1000)`` inside a
@@ -558,7 +813,7 @@ def normalize_contribution_record(
     """
     # conversation_id is the JS _sessionId (stable per-page-load chat session UUID).
     # The envelope calls it "sessionId" (without underscore); we rename to conversationId.
-    conversation_id: str = envelope.get("sessionId") or ""
+    conversation_id: str | None = _safe_id(envelope.get("sessionId"))
     answer_index: int | None = rec.get("answerIndex")
 
     rating_fields = normalize_rating(
@@ -566,19 +821,25 @@ def normalize_contribution_record(
         rec.get("ratingLabel"),
         rating_mode=rec.get("ratingMode"),     # from _feedbackStore.ratingMode (new JS)
         rating_title=rec.get("ratingTitle"),   # from _feedbackStore.ratingTitle (new JS)
-        feedback_id=None,                      # no per-event session ID for contributions
+        feedback_id=rec.get("feedbackId"),     # now forwarded — see docstring above
     )
 
     return _ordered({
         "schemaVersion":  int(envelope.get("schemaVersion") or SCHEMA_VERSION),
         "_source":        "contribution",
         "_ts":            server_ts_ms,
-        "_dedup_key":     f"{conversation_id}:{answer_index}",
-        "conversationId": conversation_id or None,
-        "feedbackId":     None,   # contributions are batch-level; no per-event ID
+        "_dedup_key":     f"{conversation_id or ''}:{answer_index}",
+        "conversationId": conversation_id,
+        # feedbackId: the per-answer feedback event's own id (sessionId), when
+        # the user rated this answer individually before contributing.  None
+        # when they contributed without rating this specific answer.
+        "feedbackId":     _safe_id(rec.get("feedbackId")),
         "answerIndex":    int(answer_index) if answer_index is not None else None,
         "action":         "rate",
-        "prevFeedbackId": None,
+        # prevFeedbackId: forwarded from the matching feedback event when that
+        # event was itself an edit of an earlier rating (edit chain).
+        "prevFeedbackId": _safe_id(rec.get("prevFeedbackId")),
+        "editCount":      _safe_int(rec.get("editCount"), default=0),
         "status":         "active",
         "ratingValue":    rec.get("ratingValue"),
         "ratingSlug":     rating_fields["ratingSlug"],
@@ -589,7 +850,7 @@ def normalize_contribution_record(
         "answer":         rec.get("answer") or "",
         "model":          normalize_model(envelope.get("model")),
         "page":           envelope.get("page") or "",
-        "consentVersion": envelope.get("consentVersion"),
+        "consentVersion": _resolve_consent_version(envelope.get("consentVersion")),
         "ts":             rec.get("ts"),
     })
 
@@ -675,18 +936,34 @@ def normalize_record(raw: dict[str, Any]) -> dict[str, Any]:
     # ``rating`` was always == ``ratingLabel``; it provides no additional info.
     out.pop("rating", None)
 
-    # ── Back-fill missing canonical fields ────────────────────────────────────
+    # ── Back-fill missing canonical fields (schemaVersion: 1 → 2) ─────────────
     out.setdefault("schemaVersion",  SCHEMA_VERSION)
     out.setdefault("feedbackId",     None)
     out.setdefault("action",         "rate")
     out.setdefault("prevFeedbackId", None)
+    # editCount: None for retraction tombstones (not applicable), 0 for any
+    # pre-v2 "rate" record that predates this column.
+    out.setdefault("editCount", None if out.get("action") == "retract" else 0)
     out.setdefault("status",         "active")
-    out.setdefault("consentVersion", None)
     out.setdefault("message",        "")
     out.setdefault("query",          "")
     out.setdefault("answer",         "")
     out.setdefault("page",           "")
 
+    # ── consentVersion: always resolved through _resolve_consent_version so
+    # historical "v1.0" values and new None values are consistent across the
+    # whole dataset while CONSENT_VERSION_ENABLED is False. ───────────────────
+    out["consentVersion"] = _resolve_consent_version(out.get("consentVersion"))
+
+    # ── Defensive re-coercion of identifier/count fields on legacy rows ───────
+    # Idempotent for already-canonical rows; guards against malformed legacy
+    # data (e.g. non-string IDs) reaching the DataFrame.
+    out["conversationId"] = _safe_id(out.get("conversationId"))
+    out["feedbackId"]     = _safe_id(out.get("feedbackId"))
+    out["prevFeedbackId"] = _safe_id(out.get("prevFeedbackId"))
+    if out.get("action") != "retract":
+        out["editCount"] = _safe_int(out.get("editCount"), default=0)
+
     # ── Normalise model shape ─────────────────────────────────────────────────
     raw_model = out.get("model")
     if isinstance(raw_model, dict):