@a3s-lab/office 0.8.0 → 0.8.1

package/COLLABORATION_ROADMAP.md

@@ -111,8 +111,8 @@ 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 and suggestion modes, immutable suggestion-decision audit, and native
-text/options/bounded structural paragraph/comment mutations implemented; rich
-native mutation parity remains pending.
+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
@@ -167,12 +167,15 @@ native mutation parity remains pending.
   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.
+  `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
@@ -183,10 +186,6 @@ native mutation parity remains pending.
 
 Remaining:
 
-- 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,
@@ -388,11 +387,11 @@ destructive actions remain attributable, reviewable, and non-retryable.
 
 Status: native Yrs replica store, resumable CLI/MCP event streams, `a3s code`
 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.
+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
@@ -444,16 +443,18 @@ and native presence projection are pending.
 - 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.
+  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
@@ -509,9 +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 add typed suggestion creation,
-  suggestion projection, and tracked final-decision operations for native
-  clients.
+  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.
 

package/README.md

@@ -146,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
 
@@ -1075,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 \
@@ -1148,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
@@ -1206,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/).
@@ -1269,6 +1309,7 @@ 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/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a3s-lab/office",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Open-source collaborative browser editors for documents, Markdown, spreadsheets, presentations, and PDFs.",
   "keywords": [
     "office",