# BF34 / TX7.2 Collaborative Review implementation state

Date: 2026-08-22
Release: R14.28.15 Build Fix 34

## Objective

Restore live collaborative Comments and Track Changes for Source collaboration without changing the TX7.1 text collaboration engine. `Y.Text` remains the only collaborative manuscript authority; review state is metadata beside it and never appears in `.tex`.

## Final architecture

```text
CodeMirror
  ↕
y-codemirror.next
  ↕
Y.Text
  ↕
y-websocket

Project Y.Doc
├── files → Y.Map<Y.Text>
├── review-comments → Y.Map<Y.Map>
│   └── replies → Y.Array
├── review-changes → Y.Map<Y.Map>
└── review-events → Y.Array
```

Review anchors are encoded `Y.RelativePosition` values. Range-start association follows the first selected character and range-end association stays with the last selected character, so boundary insertions do not incorrectly expand a selected review range. Remote collaborator cursors continue to be owned exclusively by `y-codemirror.next` Awareness.

## Local versus live review

Normal projects retain the pre-BF34 projection-based Review backend and IndexedDB persistence. During a live room, ReviewService switches to the shared Y.Doc backend. Live tracked edits are applied to Y.Text immediately and accompanied by shared review metadata. Pre-existing local review records stay private. When collaboration ends, the synchronized shared ReviewService snapshot is merged into local review storage.

## Track Changes

- per collaborator, not project-global;
- insert/delete/replace are first-class changes;
- Accept marks metadata accepted without changing Y.Text;
- Reject reverses the current proposal only after anchor/content/context validation;
- ambiguous overlaps become `conflicted`;
- explicit conflict actions keep current text, restore original text or dismiss the change;
- direct typing is derived from local Y.Text deltas; remote transactions are not re-recorded;
- programmatic edits carry explicit review-source origins; rollback/maintenance origins are excluded;
- selected-text replacement typing and contiguous insert/delete typing coalesce into meaningful review units;
- Yjs UndoManager capture and review metadata are reconciled for Undo/Redo.

## Comments

Comments use relative range/point anchors, preserve quoted text when an anchor is deleted, synchronize create/reply/resolve/reopen immediately, and use nested `Y.Array` replies so simultaneous replies do not overwrite each other. Shared review events feed the existing Review History UI.

## UX and scope

Visual remains disabled during live collaboration. The persistent editor sentence was removed and the disabled Visual control uses the compact tooltip `Unavailable during live collaboration`. The existing link + QR joining model remains. Projects empty-state spacing/min-height is scoped to Projects-specific classes.

## Validation

Dependency-free results from the final source tree before packaging:

- BF34 source guard PASS; pristine BF33 is rejected.
- BF34 regression 14/14 PASS.
- Historical R14 regression 22/22 PASS.
- Runtime hardening 101/101 PASS.
- Release static audit 351/351 PASS.
- SaaS/product/security audit 43/43 PASS.
- Server Node tests 70/70 PASS.
- Deployment/script Node tests 18/18 PASS.
- Template/compiler requirements 13/13 PASS.
- Frozen lock: 69 importers and 1171 reachable snapshots PASS.
- Dependency consistency: 68 packages PASS.
- Public barrels: 67 entries PASS.
- 20 modified TS/TSX files parse/transpile; modified JS/MJS and shell syntax PASS.

Dependency-backed `tsgo`, Biome, Vitest, Vite/build, Playwright, the formal collaboration/review soak and deployed relay checks are NOT RUN here because this extracted source tree has no installed dependency tree and package-registry access is unavailable. The BF34 Vitest/Playwright test sources are included and wired into release source guards so staging/CI can execute them.