@a3s-lab/office 0.7.2 → 0.8.0

package/COLLABORATION_ROADMAP.md

@@ -22,8 +22,9 @@ which tracks editor capability parity with WPS.
   the local binding origin, so one participant cannot undo another
   participant's operation.
 - `view`, `comment`, `suggest`, and `edit` are explicit session modes. A format
-  enables a mode only after its durable model exists; until then, unsupported
-  non-edit modes remain read-only.
+  enables a mode only after its durable model exists. Document enables durable
+  review-only `comment` plus actor-attributed `suggest`; unsupported
+  mode/format pairs remain read-only.
 - Editors never collaborate by repeatedly replacing one serialized OOXML file
   or one universal JSON blob. Each format gets a typed, conflict-local model.
 
@@ -43,6 +44,7 @@ Protocol v1 reserves the `a3s.office` namespace.
 | `document.content` | `Y.XmlFragment` | ProseMirror document, including section layout, comment anchors, and tracked-change marks. |
 | `document.options` | `Y.Map` | Document-level editable options such as page color and tracking mode. |
 | `document.comments` / `document.comment-order` | `Y.Map` / `Y.Array` | ID-keyed durable comment/reply records and deterministic presentation order. |
+| `document.change-decisions` / `document.change-decision-order` | `Y.Map` / `Y.Array` | Immutable accept/reject audit records and deterministic decision order. |
 | `document.bibliography*` | Typed maps/arrays | Bibliography settings and ID-keyed citation sources. |
 | `spreadsheet.*` | Typed maps/arrays | Sheet order, field-addressed sparse cells, formulas, styles, objects, names, and print state. |
 | `presentation.*` | Typed maps/arrays | Slide/master/layout order, ID-keyed scene objects, notes, transitions, and comments. |
@@ -90,8 +92,12 @@ Status: implemented in the browser library.
 - A runnable A3S Boot reference backend now provides signed room tickets,
   Origin validation, permission enforcement, WebSocket rooms, durable Yrs
   persistence, ephemeral Awareness relay, reconnect repair, and service-owned
-  durable update polling. Its browser adapter converts bounded base64 wire
-  payloads back to the package's typed `Uint8Array` transport envelope.
+  durable update polling. Version-2 tickets bind actor display name and the
+  durable store semantically authorizes Document comment- and suggestion-mode
+  updates under the room lock before persistence or broadcast. Its browser
+  adapter converts bounded base64 wire payloads back to the package's typed
+  `Uint8Array` transport envelope and verifies the ready identity against the
+  local session.
 - Convergence, offline/reconnect, transport-boundary, presence, permission,
   StrictMode, framework-parity, ownership, backend persistence, room broadcast,
   ticket tamper, and read-only authorization tests.
@@ -103,9 +109,10 @@ Redis/NATS fan-out plus a distributed writer/lock policy.
 ### Phase 2: Document
 
 Status: browser collaboration foundation, participant roster, remote
-selection/caret projection, participant navigation, and native
-text/options/bounded structural paragraph mutations implemented; rich native
-parity and the remaining review authorization matrix are pending.
+selection/caret projection, participant navigation, durable review-only
+comment and suggestion modes, immutable suggestion-decision audit, and native
+text/options/bounded structural paragraph/comment mutations implemented; rich
+native mutation parity remains pending.
 
 - TipTap is bound to `document.content` through
   `@tiptap/extension-collaboration`; StarterKit undo/redo is disabled and the
@@ -139,11 +146,47 @@ parity and the remaining review authorization matrix are pending.
   after durable restart and replay, including concurrent native and browser
   paragraph insertion across nested lists and nested tables. Real CLI and MCP
   subprocess tests exercise the same bounded structural mutations.
+- Document `comment` sessions now create selection-anchored threads, append
+  replies, resolve or reopen threads, and delete only their actor's own comment
+  or reply records while canonical text, structure, options, bibliography, and
+  non-comment formatting stay read-only. Records persist by stable ID and
+  immutable creation claim; removing an anchor through an authorized content
+  edit retains a detached thread. Remote review changes do not enter local undo
+  history.
+- Authenticated Document `suggest` sessions create attributed insertion,
+  deletion, and replacement proposals as `documentChange` marks. Their
+  canonical projection is unchanged until an `edit` participant decides the
+  proposal. Suggesters may withdraw their own insertion proposals, but cannot
+  change canonical text, structure, non-suggestion formatting, options,
+  comments, bibliography, another actor's proposal, or a deletion proposal's
+  targeted canonical text.
+- Accepting or rejecting a suggestion applies the tracked change and appends
+  one immutable actor-attributed record to `document.change-decisions` plus its
+  deterministic order root in the same transaction. Identical offline retries
+  converge, a second conflicting final decision fails closed, old Documents
+  without the additive roots remain readable, and a final decision clears
+  local history that could otherwise resurrect the decided mark.
+- Rust, CLI, MCP, and A3S Code expose `document-comment-create`,
+  `document-comment-reply`, `document-comment-set-resolved`, and
+  `document-comment-delete`. Projection schema v2 returns attributable threads,
+  replies, anchor text, paragraph/text identities, browser-compatible UTF-16
+  offsets, resolution, and detached state. Native and browser fixtures cover
+  restart, reordered delivery, stale anchor guards, idempotent retries,
+  ownership failures, and cross-language convergence.
+- The A3S Boot backend permits `edit` content/review updates, semantically
+  validated Document `comment` review-only updates, and semantically validated
+  Document `suggest` proposal updates. Signed actor identity and display name
+  must match every new comment, reply, or suggestion. Forged roots, canonical
+  content, structure, options, non-suggestion formatting, authorship, order,
+  claims, anchors, foreign deletion, or foreign suggestion changes fail before
+  the durable store changes.
 
 Remaining:
 
-- Add suggestion-only authorization and durable accept/reject decision audit
-  records; `comment` and `suggest` remain read-only until those models exist.
+- Add closed typed native projection and mutation variants for creating
+  Document suggestions and deciding them through CLI/MCP/A3S Code. The current
+  typed native mutation set can synchronize the resulting Yjs state but does
+  not originate these two workflows.
 - Prove concurrent full-table, list-restructure, section, comment, and revision
   workflows, plus DOCX import/export after merged edits.
 - Expand native convergence from bounded paragraph edits to complete table,
@@ -344,11 +387,12 @@ destructive actions remain attributable, reviewable, and non-retryable.
 ### Phase 6: CLI, MCP, and coding agents
 
 Status: native Yrs replica store, resumable CLI/MCP event streams, `a3s code`
-projection, a host-injected live CLI transport session, and typed Markdown,
-Document, Spreadsheet cell, Presentation scene-element, PDF
-annotation/form-value, and PDF redaction/page-operation review mutation
-surfaces are implemented; the remaining format mutations and native presence
-projection are pending.
+projection, a host-injected live CLI transport session, authenticated browser
+suggestion-update authorization, and typed Markdown, Document content/comment,
+Spreadsheet cell, Presentation scene-element, PDF annotation/form-value, and
+PDF redaction/page-operation review mutation surfaces are implemented; typed
+native Document suggestion/decision mutations, the remaining format mutations,
+and native presence projection are pending.
 
 - Yrs `0.27.3` now uses 53-bit Yjs-compatible client IDs and exchanges standard
   Yjs v1 updates, state vectors, and y-sync `SyncStep1`/`Update` messages with
@@ -390,16 +434,27 @@ projection are pending.
   if the declared match count is stale. Bounded section/list/table/blockquote
   paragraph insert/delete uses explicit stable identities and exact deletion
   guards, while table-contained edits rotate all ancestor row text identities;
-  page color and track-changes write their typed option fields. All emit minimal
-  incremental updates through the same durable
-  receipt/checkpoint path. Canonical typed mutations require `edit`; raw remote
-  updates remain receivable in every mode so read-only peers still converge.
+  page color and track-changes write their typed option fields. Document comment
+  create/reply/resolve/delete writes attributable browser-compatible review
+  records and exact selection marks. All emit minimal incremental updates
+  through the same durable receipt/checkpoint path. Canonical content mutations
+  require `edit`; Document review mutations accept `edit` or `comment`, with
+  ownership-restricted deletion in `comment`. Raw remote updates remain
+  receivable in every mode so read-only peers still converge.
+- Host-authenticated Document `suggest` transport updates are semantically
+  checked in Yrs before commit: only attributed insertion/deletion/replacement
+  proposals owned by the authenticated actor may be added or withdrawn, while
+  canonical state and every non-suggestion root remain protected. This is a
+  transport authorization path, not a `NativeOfficeCollaborationMutation`;
+  `collab mutate`, `office_collaboration_mutate`, and projection v2 do not yet
+  expose native typed suggestion creation or final-decision operations.
 - Rust `project`, `collab read`, and `office_collaboration_read` interpret the
   Office-owned browser schema inside Office rather than in a product host.
   Markdown returns its exact canonical source. Document returns bounded
   traversal-order paragraph records, stable `paragraphId`/`textId` pairs,
-  structural ancestry, option fields, and subordinate plain text together
-  with the exact state vector. `document-replace-paragraph` uses those stable
+  structural ancestry, option fields, subordinate plain text, and projection-v2
+  comment/reply/anchor/detached records together with the exact state vector.
+  `document-replace-paragraph` uses those stable
   identities plus complete expected text to reject a stale same-paragraph
   browser/agent edit before writing, while unrelated changes can proceed
   without replacing the full document.
@@ -441,7 +496,7 @@ projection are pending.
   source browser operation, and source attribution is audit data rather than
   an authorization token.
 - Cross-language tests apply deterministic native UTF-16 Markdown, ProseMirror
-  Document text/options/paragraph, Spreadsheet cell, Presentation
+  Document text/options/paragraph/comment, Spreadsheet cell, Presentation
   scene-element content/z-order, and PDF annotation/form-value updates in browser Yjs,
   including concurrent browser/native paragraph, cell-leaf, element-field,
   annotation-leaf, and PDF form edits, in addition to importing browser Yjs
@@ -454,9 +509,9 @@ Remaining:
 
 - Extend typed format-model mutations to Spreadsheet and remaining Presentation
   structural/rich-text operations plus PDF signatures; deepen Document
-  mutations to additional nested structures and review operations, and add
-  durable comment/suggest operations before enabling those modes for local
-  mutation.
+  mutations to additional nested structures and add typed suggestion creation,
+  suggestion projection, and tracked final-decision operations for native
+  clients.
 - Project editor-visible presence and selection state while keeping Awareness
   ephemeral and outside native replica persistence.
 
@@ -478,5 +533,5 @@ valid update delivery orders.
 - Shipping a hosted collaboration backend inside the component package.
 - Treating awareness as authorization or durable audit history.
 - Hiding provider synchronization behind editor mount.
-- Claiming comments or suggestions are supported by a format until its durable
-  review schema and accept/reject semantics are implemented.
+- Claiming comments or suggestions are supported by a format that lacks a
+  durable review schema and, for suggestions, explicit accept/reject semantics.

package/README.md

@@ -46,6 +46,9 @@ workflows, and a separate Rust automation plane.
   permissions, collaboration, and model providers.
 - **Collaborate across every editor** with shared Yjs/Yrs content, Awareness
   participants and remote locations, plus browser, CLI, MCP, and A3S Code peers.
+  Document reviewers can submit attributed insertions, deletions, and
+  replacements without directly changing canonical text; editors accept or
+  reject each proposal with an immutable shared decision record.
 - **Automate deterministically** through the native CLI, standard MCP server,
   or packaged Office Skill.
 
@@ -143,8 +146,9 @@ The images below are committed visual-regression baselines from the real
   also keep a durable Yrs replica, exchange standard Yjs v1 updates and state
   vectors, perform authorized typed Markdown, Document, Spreadsheet cell,
   Presentation scene-element and z-order, and PDF annotation, form-value, and
-  review changes, retain browser/native actor attribution, and checkpoint
-  without replacing a whole Office file.
+  review changes, including attributable Document selection comments and
+  replies, retain browser/native actor attribution, and checkpoint without
+  replacing a whole Office file.
 
 ## Real-time collaboration
 
@@ -158,6 +162,18 @@ through the CLI, standard MCP server, or A3S Code.
 The host owns rooms, authentication, authorization, network delivery, offline
 buffering, persistence, and the `Y.Doc`; A3S Office owns format-specific
 bindings, local undo, validated presence, and conflict-local typed mutations.
+An authenticated Document `comment` session can select text, create a durable
+thread, reply, resolve or reopen it, and delete only review records owned by
+its actor while canonical content remains read-only. The server independently
+validates that review-only boundary before persistence and broadcast. An
+authenticated Document `suggest` session can submit attributed insertions,
+deletions, and replacements while canonical text, structure, formatting,
+options, comments, and other actors' suggestions remain protected. An `edit`
+participant accepts or rejects a proposal and appends the final actor-attributed
+decision to the immutable `document.change-decisions` audit trail. The A3S Boot
+service validates both comment and suggestion semantics under the durable room
+lock before it persists or broadcasts caller-supplied Yjs bytes. `suggest` on
+non-Document formats remains receive-only.
 See the bilingual [real-time collaboration guide](https://a3s-lab.github.io/Office/docs/components/collaboration.html)
 for React, Vue, Web Component, reconnect, security, and native-agent setup.
 The repository also ships a runnable
@@ -1046,6 +1062,19 @@ cargo run -p a3s-office-cli -- collab mutate .a3s/report.replica \
   --operation-id edit-44 \
   --mutation '{"type":"document-insert-paragraph","anchorParagraphId":"00000001","position":"after","paragraphId":"00000012","textId":"00000013","text":"Native paragraph"}' --json
 
+# Add a durable selection comment from a comment-mode native replica. Read the
+# projection first and use its exact paragraph/text IDs, anchor text, and UTF-16
+# offsets. The author must match the authenticated actor display name.
+cargo run -p a3s-office-cli -- collab join .a3s/report-review.replica \
+  --artifact-id report --kind document --actor-id agent-7 \
+  --actor-kind agent --mode comment --operation-id comment-join-1 \
+  --input browser.update --json
+cargo run -p a3s-office-cli -- collab read .a3s/report-review.replica --json
+cargo run -p a3s-office-cli -- collab mutate .a3s/report-review.replica \
+  --artifact-id report --kind document --actor-id agent-7 --mode comment \
+  --operation-id comment-45 \
+  --mutation '{"type":"document-comment-create","commentId":"comment-1","paragraphId":"00000001","expectedTextId":"00000002","startUtf16":6,"endUtf16":12,"expectedText":"review","author":"Ada Reviewer","createdAt":"2026-08-17T00:00:00.000Z","text":"Clarify this review point."}' --json
+
 # Recursively patch one Spreadsheet cell after matching the observed value.
 # Zero-based row/column coordinates follow the browser collaboration model.
 cargo run -p a3s-office-cli -- collab mutate .a3s/plan.replica \
@@ -1118,8 +1147,10 @@ suppression, without opening its own network provider. Native Rust `project`,
 `collab read`, and `office_collaboration_read` return the exact canonical
 Markdown source or an Office-owned bounded Document projection with stable
 paragraph/text identities, structural ancestry, option fields, subordinate
-plain text, and the current state vector. Product hosts therefore do not need
-to interpret Office's private Yjs schema. Typed Markdown
+plain text, durable comments, replies, resolution and detached state, exact
+paragraph-local UTF-16 anchors, and the current state vector. Projection schema
+version 2 is the contract for these review fields. Product hosts therefore do
+not need to interpret Office's private Yjs schema. Typed Markdown
 replace/splice operations use browser UTF-16 offsets. Document mutations edit
 ProseMirror `Y.XmlText` in place, rotate the affected Word `textId`, replace one
 stable plain paragraph only after its `paragraphId`, `textId`, and complete
@@ -1164,6 +1195,17 @@ targets, or a second final decision. None of these paths puts source or
 signature bytes in Yjs. Validated browser source origins survive native
 persistence and are re-emitted separately from host delivery IDs.
 
+Document review mutations use `document-comment-create`,
+`document-comment-reply`, `document-comment-set-resolved`, and
+`document-comment-delete`. Create validates an exact paragraph/text identity,
+UTF-16 range, and selected text before writing both the thread and its
+`documentComment` mark. Replies append to the stable thread; resolution can be
+set or cleared; and `comment` mode can delete only records attributed to its
+own actor. Removing selected text through a separately authorized edit keeps
+the thread as a detached review record. Browser and native comment changes
+share immutable claims and remain isolated from another participant's undo
+history.
+
 Read the [native engine design](docs/latest/en/native-office-engine.md), the
 complete [CLI reference](docs/latest/en/cli-reference.md), or the published
 [CLI and Skill guide](https://a3s-lab.github.io/Office/docs/automation/).
@@ -1227,6 +1269,8 @@ without hard-coded return URLs.
 
 - [Live Playground](https://a3s-lab.github.io/Office/)
 - [Documentation center](https://a3s-lab.github.io/Office/docs/)
+- [A3S Office 0.8.0 documentation](https://a3s-lab.github.io/Office/docs/0.8.0/)
+- [A3S Office 0.7.3 documentation](https://a3s-lab.github.io/Office/docs/0.7.3/)
 - [A3S Office 0.7.2 documentation](https://a3s-lab.github.io/Office/docs/0.7.2/)
 - [A3S Office 0.7.1 documentation](https://a3s-lab.github.io/Office/docs/0.7.1/)
 - [A3S Office 0.7.0 documentation](https://a3s-lab.github.io/Office/docs/0.7.0/)