@a3s-lab/office 0.7.3 → 0.8.1

package/COLLABORATION_ROADMAP.md

@@ -22,9 +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. Document now enables
-  durable review-only `comment`; unsupported mode/format pairs 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.
 
@@ -44,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. |
@@ -92,11 +93,11 @@ Status: implemented in the browser library.
   Origin validation, permission enforcement, WebSocket rooms, durable Yrs
   persistence, ephemeral Awareness relay, reconnect repair, and service-owned
   durable update polling. Version-2 tickets bind actor display name and the
-  durable store semantically authorizes Document comment-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.
+  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.
@@ -109,9 +110,9 @@ Redis/NATS fan-out plus a distributed writer/lock policy.
 
 Status: browser collaboration foundation, participant roster, remote
 selection/caret projection, participant navigation, durable review-only
-comment mode, and native text/options/bounded structural paragraph/comment
-mutations implemented; rich native parity and suggestion authorization are
-pending.
+comment and suggestion modes, immutable suggestion-decision audit, and native
+text/options/bounded structural paragraph/comment/suggestion 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
@@ -152,23 +153,39 @@ pending.
   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 and semantically
-  validated Document `comment` review-only updates. Signed actor display name
-  must match the session actor and every new record author. Forged roots,
-  content, structure, options, authorship, order, claims, anchors, or foreign
-  deletion fail before the durable store changes.
+  `document-comment-reply`, `document-comment-set-resolved`,
+  `document-comment-delete`, `document-suggestion-create`, and
+  `document-suggestion-decide`. Projection schema v3 returns attributable
+  comment threads, replies, anchor text, live suggestion identities and exact
+  placements, immutable final decisions, paragraph/text identities,
+  browser-compatible UTF-16 offsets, resolution, and detached state. Native and
+  browser fixtures cover restart, reordered delivery, stale guards, idempotent
+  retries, ownership/mode failures, atomic replacement decisions, 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; `suggest` remains read-only until that model exists.
 - 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,
@@ -369,11 +386,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 content/comment, 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/suggestion, 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.
 
 - 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
@@ -422,12 +440,21 @@ projection are pending.
   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.
+  `document-suggestion-create` exposes the same closed proposal contract to an
+  actor-scoped native `suggest` replica; `document-suggestion-decide` lets an
+  `edit` replica match and accept or reject one or more complete projected
+  identities atomically, then appends immutable browser-compatible decisions.
 - 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, subordinate plain text, and projection-v2
-  comment/reply/anchor/detached records together with the exact state vector.
+  structural ancestry, option fields, subordinate plain text, and projection-v3
+  comment/reply/anchor/detached records, live suggestions with exact placements,
+  and immutable final decisions 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
@@ -483,8 +510,8 @@ 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 tracked suggestion decisions
-  before enabling `suggest` for local mutation.
+  mutations to additional nested structures and complete table/list/section
+  revision workflows.
 - Project editor-visible presence and selection state while keeping Awareness
   ephemeral and outside native replica persistence.
 
@@ -506,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,9 +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, including attributable Document selection comments and
-  replies, retain browser/native actor attribution, and checkpoint without
-  replacing a whole Office file.
+  review changes, including attributable Document selection comments, replies,
+  text suggestions, and atomic final decisions, retain browser/native actor
+  attribution, and checkpoint without replacing a whole Office file.
 
 ## Real-time collaboration
 
@@ -162,7 +165,15 @@ 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.
+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
@@ -1064,6 +1075,33 @@ cargo run -p a3s-office-cli -- collab mutate .a3s/report-review.replica \
   --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
 
+# Propose an atomic replacement from an actor-scoped suggest replica. Read
+# projection v3 immediately before writing and copy its exact paragraph/text
+# identity, UTF-16 selection, and selected text.
+cargo run -p a3s-office-cli -- collab join .a3s/report-suggest.replica \
+  --artifact-id report --kind document --actor-id agent-7 \
+  --actor-kind agent --mode suggest --operation-id suggestion-join-1 \
+  --input browser.update --json
+cargo run -p a3s-office-cli -- collab read .a3s/report-suggest.replica --json
+cargo run -p a3s-office-cli -- collab mutate .a3s/report-suggest.replica \
+  --artifact-id report --kind document --actor-id agent-7 --mode suggest \
+  --operation-id suggestion-create-1 \
+  --mutation '{"type":"document-suggestion-create","paragraphId":"00000001","expectedTextId":"00000002","startUtf16":6,"endUtf16":8,"expectedText":"😀","replacement":"reviewed","insertionId":"agent-7-insertion-1","deletionId":"agent-7-deletion-1","author":"A3S Agent","createdAt":"2026-08-17T11:00:00.000Z"}' --json
+cargo run -p a3s-office-cli -- collab diff .a3s/report-suggest.replica \
+  --output agent-suggestion.update --json
+
+# An edit replica accepts or rejects one or more complete projected suggestion
+# identities atomically and appends immutable actor-attributed decisions.
+cargo run -p a3s-office-cli -- collab join .a3s/report-editor.replica \
+  --artifact-id report --kind document --actor-id editor-1 \
+  --actor-kind human --mode edit --operation-id editor-join-1 \
+  --input agent-suggestion.update --json
+cargo run -p a3s-office-cli -- collab read .a3s/report-editor.replica --json
+cargo run -p a3s-office-cli -- collab mutate .a3s/report-editor.replica \
+  --artifact-id report --kind document --actor-id editor-1 --mode edit \
+  --operation-id suggestion-accept-1 \
+  --mutation '{"type":"document-suggestion-decide","suggestions":[{"id":"agent-7-deletion-1","kind":"deletion","expectedActorId":"agent-7","expectedAuthor":"A3S Agent","expectedCreatedAt":"2026-08-17T11:00:00.000Z","expectedText":"😀"},{"id":"agent-7-insertion-1","kind":"insertion","expectedActorId":"agent-7","expectedAuthor":"A3S Agent","expectedCreatedAt":"2026-08-17T11:00:00.000Z","expectedText":"reviewed"}],"decision":"accept","decidedBy":"Grace Editor","decidedAt":"2026-08-17T11:01:00.000Z"}' --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 \
@@ -1137,8 +1175,9 @@ suppression, without opening its own network provider. Native Rust `project`,
 Markdown source or an Office-owned bounded Document projection with stable
 paragraph/text identities, structural ancestry, option fields, subordinate
 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
+paragraph-local UTF-16 anchors, live suggestions with exact placements,
+immutable final decisions, and the current state vector. Projection schema
+version 3 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
@@ -1195,6 +1234,18 @@ the thread as a detached review record. Browser and native comment changes
 share immutable claims and remain isolated from another participant's undo
 history.
 
+Document suggestion mutations use `document-suggestion-create` in an
+actor-scoped `suggest` replica and `document-suggestion-decide` in an `edit`
+replica. Creation matches a stable plain paragraph, its current text identity,
+an exact UTF-16 range, and selected text before writing an insertion, deletion,
+or atomic replacement proposal. Decisions match every projected suggestion
+identity and text in the batch, then accept or reject all of them in one
+transaction and append immutable browser-compatible audit records. Actor IDs
+come from replica manifests; authors and decision names must match the
+authenticated display names. Stable-ID retries are idempotent, while stale
+identities, overlapping proposals, incomplete replacement IDs, forged
+attribution, or conflicting final decisions fail without a durable update.
+
 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/).
@@ -1258,6 +1309,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.1 documentation](https://a3s-lab.github.io/Office/docs/0.8.1/)
+- [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/)