feat: reconstruct revision groups at parse time (ISSUES.md #46) (#61)

* feat: reconstruct revision groups at parse time — inferred groups for pre-existing revisions (ISSUES.md #46)

Revisions already in the file (previous sessions, foreign reviewers, Word
round-trips) now get inferred groups at RevisionManager construction:
maximal runs of contiguous same-paragraph revisions sharing identical raw
w:author + w:date become one group, so whole logical edits resolve as a
unit after reopen too. New Revision.group_source ("recorded" | "inferred")
reports provenance; split-off tails of own pre-session insertions are
adopted into their origin's inferred group; ungroupable revisions (missing
author/date, outside any paragraph, nonconforming ids) stay group_id=None
and break contiguity runs. Known imprecisions (same-paragraph same-second
over-merge, nested-paragraph over-split, rump groups) are documented and
pinned by tests.

* fix: review round 1 — freeze one w:date per edit, safe nonconforming-id listing, snapshot dataclass

- frozen_timestamp(): one logical operation now stamps all its revisions
  with a single w:date (previously each injection call read the clock, so
  a multi-hunk edit crossing a second boundary would reconstruct as
  several inferred groups after reopen); adversarial ticking-clock test.
- list_revisions() no longer crashes on a non-numeric w:id (omitted:
  unrepresentable by int-keyed operations); a duplicated w:id is now
  wholly ungrouped — every occurrence — since id-keyed lookup cannot
  tell occurrences apart. Docs aligned.
- _RegistrySnapshot is a named dataclass (CLAUDE.md: named objects over
  3+-tuples); Revision.group_source reuses the _GroupSource alias.

* fix: review round 2 — duplicate-id pre-scan, doc parity for foreign split halves, public GroupSource alias

- _reconstruct_groups now pre-scans for duplicated w:ids independent of
  groupability: an ungroupable occurrence (e.g. missing date) no longer
  lets its groupable twin win a group that id-keyed lookup would report
  for both elements; replaces the round-1 demotion surgery with a
  simpler never-group-duplicates rule.
- docs/api.md and SKILL.md now list the fourth group_id=None case
  (mid-session split half of a foreign insertion), matching the
  Revision docstring.
- _GroupSource renamed to GroupSource: it types the public
  Revision.group_source field (same convention as session.ExecStatus).

Author: pablospe

docs/api.md

@@ -626,23 +626,38 @@ revision. Accepting the group applies the whole edit — the safe alternative to
 resolving a multi-revision edit (especially a rewrite) revision by revision,
 which garbles the text if only some are applied.
 
-Groups are **in-memory and per-open-Document**: after `close()`/reopen,
-revisions report `group_id=None` and old group ids raise
-[`RevisionError`](#revisionerror). `save()` does not invalidate groups (the
-Document stays open and revision ids are preserved). Revisions authored
-outside the current session (foreign reviewers, previous sessions) have no
-group — accept/reject them by id or author as before. If groups ever need to
-survive across sessions, the workspace `meta.json` (which never enters the
-`.docx`) is the natural extension point; that persistence is intentionally not
-implemented today.
+Group ids are **in-memory and per-open-Document**, renumbered on each open.
+Edits made through the open Document **record** their group
+(`Revision.group_source == "recorded"`). For revisions already in the file —
+previous sessions, foreign reviewers, Word round-trips — nothing is persisted
+in the `.docx` (Word has no grouping concept and strips unknown markup), so
+groups are **inferred** at parse time instead
+(`Revision.group_source == "inferred"`): contiguous revisions in the same
+paragraph sharing identical `w:author` + `w:date` reconstruct as one group.
+That heuristic almost always matches the original logical edits — one caveat:
+`w:date` has second precision, so two edits to the *same paragraph* within the
+same second merge into one inferred group. When Word already resolved part of
+a former edit, the remainder reconstructs as a smaller (rump) group, and
+`accept_group()`/`reject_group()` handle it fine. Revisions missing an author
+or date, sitting outside any paragraph (e.g. table-row markers), or sharing a
+duplicated id stay ungrouped (`group_id=None`), as does the trailing half
+created when an edit splits a *foreign* author's pending insertion mid-session
+(foreign grouping is best-effort); revisions with non-numeric ids are omitted
+from `list_revisions()` entirely (no id-keyed operation could target them).
+
+Never carry a `group_id` across sessions: reopening renumbers groups from 1,
+so a stale id from a previous session may silently resolve to a *different*
+group rather than raise. Always take group ids from the current session's
+`EditResult` or `list_revisions()`. `save()` does not invalidate groups (the
+Document stays open and revision ids are preserved).
 
 **Parameters:**
 
 - `group_id` (int): Group id from an `EditResult` (or a `Revision.group_id`)
 
 **Returns:** Number of revisions accepted (int). Members already resolved individually are skipped (and not counted).
 
-**Raises:** [`RevisionError`](#revisionerror) if the group id is unknown (never allocated, or allocated by a previous session on this document).
+**Raises:** [`RevisionError`](#revisionerror) if the group id is unknown to this open Document.
 
 **Example:**
 
@@ -656,7 +671,8 @@ doc.accept_group(result.group_id)  # apply the whole rewrite
 Reject every revision created by one logical edit operation — the counterpart
 of [`accept_group()`](#accept_groupgroup_id). Rejecting the group undoes the
 whole edit, restoring the exact pre-edit text (deletions restored, insertions
-removed). Same group semantics and lifetime as `accept_group()`.
+removed). Same group semantics and lifetime as `accept_group()` — including
+recorded vs inferred groups and per-open renumbering.
 
 **Parameters:**
 
@@ -806,7 +822,8 @@ from docx_editor import Revision
 | `author` | str | The revision author |
 | `date` | datetime or None | When the revision was made |
 | `text` | str | The inserted or deleted text |
-| `group_id` | int or None | Revision group of the edit that created it in this session (see [`accept_group()`](#accept_groupgroup_id)); None for foreign or pre-session revisions |
+| `group_id` | int or None | Revision group this revision belongs to (see [`accept_group()`](#accept_groupgroup_id)): recorded for this session's edits, inferred by reconstruction for revisions already in the file; None only for ungroupable revisions (missing author/date, outside any paragraph, duplicated id, or a mid-session split half of a foreign insertion) |
+| `group_source` | str or None | Provenance of `group_id`: `"recorded"` (created through this open Document) or `"inferred"` (reconstructed at parse time from same-paragraph contiguity + identical author and date); None iff `group_id` is None |
 
 ### Example
 
@@ -890,7 +907,7 @@ from docx_editor import EditResult
 
 | Attribute | Type | Description |
 |-----------|------|-------------|
-| `group_id` | int or None | Revision group holding every revision this edit created, for [`accept_group()`](#accept_groupgroup_id) / [`reject_group()`](#reject_groupgroup_id). None when the edit created no new revisions (e.g. text spliced into one of your own pending insertions, a no-change rewrite, or a rewrite whose changes all merged into your own pending insertions). Valid only while this Document stays open. |
+| `group_id` | int or None | Revision group holding every revision this edit created, for [`accept_group()`](#accept_groupgroup_id) / [`reject_group()`](#reject_groupgroup_id). None when the edit created no new revisions (e.g. text spliced into one of your own pending insertions, a no-change rewrite, or a rewrite whose changes all merged into your own pending insertions). Valid only while this Document stays open — after reopen the same revisions belong to a freshly inferred group with a new id. |
 | `revision_ids` | tuple[int, ...] | The `w:id`s of the group's member revisions, in creation order; `()` when `group_id` is None |
 
 ### Example
@@ -1085,7 +1102,7 @@ except CommentError as e:
 
 ### `RevisionError`
 
-Raised when a revision operation fails — most commonly an unknown group id passed to `accept_group()` / `reject_group()`. Revision groups are in-memory and per-open-`Document`, so ids from a previous session are unknown; resolve those revisions by id or author instead. Structured fields: `revision_id` and `group_id` — set when the error is about that specific id (`group_id` for unknown-group errors), `None` otherwise.
+Raised when a revision operation fails — most commonly an unknown group id passed to `accept_group()` / `reject_group()`. Group ids are per-open-`Document` and renumbered on each open (recorded for this session's edits, inferred by reconstruction for revisions already in the file), so always use a group id from the current session's `EditResult` or `list_revisions()` — a stale id from a previous session may raise this, or worse, silently resolve to a different group. Structured fields: `revision_id` and `group_id` — set when the error is about that specific id (`group_id` for unknown-group errors), `None` otherwise.
 
 ```python
 from docx_editor.exceptions import RevisionError

docx_editor/document.py

@@ -69,8 +69,10 @@ class Document:
         result = doc.replace("30 days", "60 days", paragraph=ref)
         doc.add_comment("Section 5", "Please review")
 
-        # Every edit's revisions form a group — accept/reject them as a unit
-        # (group ids live only while this Document is open):
+        # Every edit's revisions form a group — accept/reject them as a unit.
+        # Group ids are per-open-Document (renumbered on each open; revisions
+        # already in the file get inferred groups reconstructed at parse
+        # time), so always use ids from this session:
         result = doc.rewrite_paragraph(result, "The board shall approve.")
         doc.reject_group(result.group_id)  # undo the whole rewrite
 
@@ -1276,9 +1278,11 @@ def list_revisions(self, author: str | None = None, paragraph: str | None = None
             locatable, e.g. nested revisions), plus ``nested_under`` and
             ``contains_ids`` describing revision nesting (e.g. a foreign
             deletion inside another author's pending insertion), and
-            ``group_id`` linking revisions created by the same edit
-            operation in this session (None for foreign or pre-session
-            revisions).
+            ``group_id``/``group_source`` linking revisions from the same
+            logical edit — recorded for this session's edits, inferred by
+            parse-time reconstruction for revisions already in the file
+            (``group_id`` is None only for ungroupable revisions, e.g.
+            missing author/date).
 
         Raises:
             ValueError: If ``paragraph`` is malformed
@@ -1343,9 +1347,15 @@ def accept_group(self, group_id: int) -> int:
         resolving a multi-revision edit (especially a rewrite) revision by
         revision can leave the text garbled if only some are applied.
 
-        Groups are in-memory and live only while this Document is open:
-        after close()/reopen, revisions report ``group_id=None`` and old
-        group ids raise. save() does not invalidate groups.
+        Group ids are in-memory and per-open-Document, renumbered on each
+        open. Revisions already in the file (previous sessions, foreign
+        reviewers) get inferred groups reconstructed at parse time —
+        contiguous same-paragraph revisions sharing identical author and
+        date — so whole logical edits resolve as a unit after reopen too
+        (see ``Revision.group_source``). Always use a group id from this
+        session's EditResult or list_revisions(); a stale id from a
+        previous session may resolve to a different group. save() does not
+        invalidate groups.
 
         Args:
             group_id: Group id from an EditResult (or a Revision's
@@ -1356,8 +1366,7 @@ def accept_group(self, group_id: int) -> int:
             individually are skipped (and not counted).
 
         Raises:
-            RevisionError: If the group id is unknown (never allocated, or
-                allocated by a previous session on this document).
+            RevisionError: If the group id is unknown to this open Document.
 
         Example:
             result = doc.rewrite_paragraph(ref, "New text.")
@@ -1371,7 +1380,8 @@ def reject_group(self, group_id: int) -> int:
 
         The counterpart of :meth:`accept_group` — rejecting the group undoes
         the whole edit, restoring the exact pre-edit text (deletions are
-        restored, insertions removed).
+        restored, insertions removed). Same group semantics and lifetime as
+        accept_group(), including inferred groups after reopen.
 
         Args:
             group_id: Group id from an EditResult (or a Revision's
@@ -1382,8 +1392,7 @@ def reject_group(self, group_id: int) -> int:
             individually are skipped (and not counted).
 
         Raises:
-            RevisionError: If the group id is unknown (never allocated, or
-                allocated by a previous session on this document).
+            RevisionError: If the group id is unknown to this open Document.
 
         Example:
             result = doc.rewrite_paragraph(ref, "New text.")