feat(review): add bounded review contract surface

.github/workflows/ci.yml

@@ -90,7 +90,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ${{ github.event_name == 'pull_request' && fromJSON('["3.14"]') || fromJSON('["3.11", "3.12", "3.13", "3.14"]') }}
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
     defaults:
       run:
         working-directory: office

README.md

@@ -70,6 +70,8 @@ runtime.
 | Envelope identity | `@contextualwisdomlab/cwl-editor/envelope-identity` | Framework-independent bounded schema identity for host-owned migration routing |
 | Revision evidence | `@contextualwisdomlab/cwl-editor/revision-evidence` | Framework-independent canonical envelope, strong revision, and transition evidence |
 | Text-position selector | `@contextualwisdomlab/cwl-editor/text-position-selector` | React-free deterministic W3C `TextPositionSelector` projection core |
+| Review target core | `@contextualwisdomlab/cwl-editor/review` | `implemented_on_active_pr` — React-free deterministic exact-revision review targets; durable review records and policy remain host-owned |
+| Review React adapter | `@contextualwisdomlab/cwl-editor/review-react` | `implemented_on_active_pr` — controlled accessible thread and suggestion-decision presentation over the React-free review contract; hosts own actions, authorization, bodies, and persistence |
 | Autosave | `@contextualwisdomlab/cwl-editor/autosave` | Provider-neutral bounded single-flight persistence coordination |
 | Headless Markdown | `@contextualwisdomlab/cwl-editor/markdown` | React-free deterministic Markdown/HTML/email/plain-text conversion |
 | Styles | `@contextualwisdomlab/cwl-editor/styles.css` | Editor layout and theming |
@@ -179,6 +181,12 @@ editorRef.current?.focus();
 `insertValue` is mode-aware, inserts at the current selection, and triggers the
 normal `onChange` path without wiping the document.
 
+The Active PR / Proposed review surface also exposes
+`applyReviewSuggestionDecision()`. After host authorization, `accept` applies
+one exact-revision insert/delete transaction that participates in editor
+undo/redo; `reject` preserves the document. A concurrent edit or repeated
+accept fails stale instead of re-anchoring the proposal.
+
 ### Atomic revision-envelope capture
 
 Autosave, AI, template, and review operations should capture their document and
@@ -746,4 +754,4 @@ capabilities they require.
 - **Fonts:** Noto Sans families are SIL Open Font License 1.1.
 
 See [`LICENSE`](LICENSE), [`src/fonts/OFL.txt`](src/fonts/OFL.txt), and
-[`src/fonts/NOTICE`](src/fonts/NOTICE).
+[`src/fonts/NOTICE`](src/fonts/NOTICE).

docs/CONTRACTS.md

@@ -47,6 +47,16 @@ Local evidence records describe narrowly scoped facts such as revision identity,
 
 No single status collapses those authorities. Ordinary evidence must avoid embedding complete document bodies, selected quote text, credentials, tenant identifiers, prompts, model outputs, or private exception causes unless a separate authorized contract explicitly requires them.
 
+## Review contract (Active PR / Proposed)
+
+The proposed `./review` subpath accepts only versioned, bounded, provider-neutral review targets, thread presentation records, and insert/delete suggestions. Targets use `inkspan-prosemirror-text` projection offsets and one exact canonical document revision. The surface validates and detaches untrusted metadata, rejects stale direct reuse, and can classify host-supplied before/after envelopes as accepted, rejected, or stale without retaining proposal text or document bodies in the result.
+
+Classification is evidence, not authorization. After host authorization, `CwlEditorHandle.applyReviewSuggestionDecision()` may apply an insert/delete acceptance as one exact-revision editor transaction; rejection preserves the document and creates no history entry. The adapter captures one `EditorState`, verifies its canonical revision asynchronously, and refuses the operation if the live state changed before dispatch. Acceptance must produce a changed revision; rejection must preserve the revision; a stale target paired with any document change fails closed. The host owns reviewer/thread identity, permissions, transport, durable persistence, resolution, notifications, audit, retention, and cross-revision re-anchoring.
+
+The proposed `./review-react` subpath renders controlled native-button target markers, thread lists, and one-suggestion decision controls from the validated review contract. It exposes selection, reply, resolve, accept, and reject intents only. Host-controlled selection remains authoritative, unavailable actions remain disabled, keyboard focus traversal does not commit selection, and host callbacks cannot turn presentation state into authorization or durable success. Review presentation defaults to `printMode="exclude"`; explicit `include` prints bounded labels and status/comment summaries while suppressing interactive controls.
+
+The print option is not a general export switch. Review metadata is excluded from non-print exports, and deterministic Markdown, HTML, email, plain-text, and Office conversion serializes canonical document content only. A host that includes review records in another artifact owns that separately governed export and its authorization, disclosure, provenance, retention, accessibility, and publication policy.
+
 ## W3C text-position selector evidence contract
 
 Protected `main` exposes `getTextPositionSelectorEvidence()` through the root package as a revision-scoped annotation-interoperability primitive. It does **not** reinterpret `CwlEditorSelectionSnapshot` or ProseMirror structural positions as W3C positions. It derives a separate W3C `TextPositionSelector` from the same captured immutable editor state that is used for revision derivation.
@@ -149,6 +159,7 @@ Rollback must preserve readable canonical documents and must not require silentl
 | Markdown/HTML editing | deterministic editor state and supported import/export semantics | application workflow, document ownership, authorization |
 | document envelope/revision | schema validation, identity routing, canonical bytes, local equality evidence | migration orchestration, durable storage, signatures, tenant binding |
 | selection / W3C annotation evidence | exact-revision structural coordinates and versioned text-position projection | annotation identity/body, source IRI, authorization, persistence, audit, publication, re-anchoring |
+| review targets and suggestions (Active PR / Proposed) | bounded exact-revision metadata, accessible controlled presentation, revision-only operation classification | editor mutation, reviewer/thread identity, authorization, persistence, resolution, notifications, audit, re-anchoring |
 | autosave | local ordering/state, callback contract, validator validation | transport, durable CAS, retry/offline policy, persistence |
 | collaboration | provider-neutral editor/Yjs binding | provider lifecycle, rooms, identity, authorization, persistence, awareness privacy |
 | Office rendering | deterministic bounded JSON→artifact conversion | file destination policy, downstream distribution, tenant authorization |

docs/DATA_MODEL.md

@@ -86,6 +86,8 @@ These values may remain ephemeral or release-artifact metadata. Their presence i
 | `document_transition` | none required; host may store | change evidence | no | content-lineage evidence only |
 | `selection_evidence` | none required | review/selection capture | no | exact-revision ProseMirror coordinates only |
 | `text_position_selector_evidence` | none required; `implemented_on_protected_main` | interoperable review/annotation capture | no | exact-revision W3C text positions satisfying `0 <= start <= end <= projectedCodePointLength` under one versioned projection only |
+| `review_suggestion` | host if persisted; Active PR / Proposed | one insert/delete proposal | insert text only for insertion proposals | exact-revision untrusted proposal, not authorization or durable state |
+| `review_operation` | none required; host may persist its own decision | one accept/reject attempt | no | revision-only local result; acceptance is one undoable editor transaction and rejection is document-preserving |
 | `autosave_revision` | none required | queued local save evidence | envelope-bearing evidence may be retained boundedly by queue | local save ordering only |
 | `autosave_snapshot` | none required | lifecycle observation/coordination | no | local machine state only; validator fields remain confidential metadata |
 | `durable_validator` | host | durable version | no | host concurrency evidence, not authorization |

docs/PRD.md

@@ -31,6 +31,7 @@ The product promise is: **author, convert, collaborate, and prove document chang
 11. Produce reviewable package, security, compatibility, accessibility, SBOM/provenance, and release evidence tied to one exact protected source head.
 12. Give security researchers a discoverable private vulnerability-reporting and coordinated-disclosure path without promising unsupported SLAs, bounties, certification, or legal safe harbor.
 13. Identify a complete unsupported document-envelope generation safely enough for the host to select its own migration without accepting that generation as current Inkspan document semantics.
+14. Review a revision-scoped comment or insert/delete proposal through an accessible controlled surface without moving reviewer identity, authorization, durable thread state, or document mutation authority into Inkspan.
 
 ## Required outcomes
 
@@ -61,6 +62,7 @@ The product promise is: **author, convert, collaborate, and prove document chang
 - Autosave remains single-flight with bounded active/pending work and explicit conflict/failure recovery.
 - Durable saves use a host/server-selected strong validator; conflict or ambiguous failure never silently advances it.
 - Lifecycle observation emits only distinct externally visible document-free state transitions; construction and no-op operations do not manufacture notifications.
+- Proposed review targets and insert/delete suggestions bind to one exact document revision and the named text projection. Stale targets fail closed; accepting must change the revision, rejecting must preserve it, and neither result may claim authorization or durable review state.
 
 ### SSR and native forms
 
@@ -94,6 +96,7 @@ The product promise is: **author, convert, collaborate, and prove document chang
 - Toolbar shortcut metadata must reflect repository-level shipped behavior, including host/editor bindings such as link editing, rather than only extension-local defaults.
 - Application-visible saving/conflict/recovery messages must be derivable from programmatic state without Inkspan prescribing untranslated user-facing copy.
 - Export/print surfaces must not rely on color alone or inaccessible interaction-only state where the corresponding product surface exists.
+- By default, review metadata is excluded from non-print exports: deterministic Markdown, HTML, email, plain-text, and Office conversion receives canonical document content only. A host that needs comments or review status in an artifact must build a separately governed export with its own authorization, disclosure, retention, and accessibility policy.
 
 ### Security disclosure and vulnerability handling
 
@@ -148,3 +151,5 @@ Protected `main` is the sole implemented baseline. Open PRs may describe Propose
 SafeClipboard, real Chromium/Firefox/WebKit release assurance, lifecycle observation, the root security disclosure lifecycle, toolbar shortcut accessibility metadata, SSR/native-form serialization, revision-scoped selection evidence, W3C text-position selector evidence, document-transition evidence, and envelope identity migration routing are implemented on protected `main`.
 
 A named editor-chrome theme-token catalog, DTCG 2025.10 interchange snapshot, and Storybook inventory for repeating toolbar/editor objects are Active PR / Proposed and are not shipped claims until protected integration. Hosts must check inventoried active-chrome contrast (`--cwl-accent` on `--cwl-accent-soft`) in addition to body text.
+
+The provider-neutral review contract and controlled accessible review-thread/target-marker surfaces are also Active PR / Proposed. They validate bounded host data, emit only detached intent snapshots, and apply an authorized insert/delete acceptance as one exact-revision undoable editor transaction while rejection preserves the document. They do not own reviewer identity, authorization, thread persistence, audit, notifications, or cross-revision re-anchoring.

docs/TEST_STRATEGY.md

@@ -55,12 +55,13 @@ At minimum, maintain regressions for:
 - SSR client-controlled form values, escaping, hydration continuity, reset behavior, and absence of server editor construction;
 - autosave stale validators, conflict/failure recovery, ambiguous transport outcomes, duplicate/no-op lifecycle transitions, callback exceptions, queue bounds, flush/close behavior, and durable-validator coherence;
 - selection/revision races and document movement during asynchronous hashing;
+- review suggestion decisions covering insert, delete, reject, repeated accept, Unicode projection boundaries, out-of-range selectors, undo/redo, and document movement during asynchronous hashing;
 - Office formula prefixes, invalid XML characters, malicious strings, path/publication races, invalid worksheet names, invalid freeze panes, cyclic input, pathological nesting, excessive container size, and partial write failure;
 - package/release stale draft assets, unexpected or non-regular local entries, exact four-file inventory violations, incomplete remote uploads, GitHub-vs-local digest mismatch, stale exact-head evidence, mutable provenance inputs, and isolated packed-consumer behavior.
 
 ## Concurrency and failure testing
 
-Use deterministic barriers/fakes for local concurrency and real process/file boundaries where required. Prove that an observer exception cannot alter queue ordering; a stale digest cannot bind to a later editor state; an ambiguous durable save does not advance a validator; close/recovery does not leak waiters; and file publication either completes under the documented contract or fails without silently replacing unrelated content.
+Use deterministic barriers/fakes for local concurrency and real process/file boundaries where required. Prove that an observer exception cannot alter queue ordering; a stale digest cannot bind to a later editor state or review transaction; an ambiguous durable save does not advance a validator; close/recovery does not leak waiters; and file publication either completes under the documented contract or fails without silently replacing unrelated content.
 
 Host persistence transactions, tenant isolation, distributed collaboration authorization, durable audit storage, and production network retry policy are host-owned and must be tested by the embedding product. Inkspan tests verify only the explicit adapter contract at those boundaries.
 

docs/THREAT_MODEL.md

@@ -53,6 +53,10 @@ Local SHA-256 revisions identify deterministic content equality only. Selection
 
 Concurrent editors, delayed digests, stale selections, ambiguous transport failure, or stale durable validators can cause lost updates or false success. Inkspan must bind asynchronous evidence to one immutable local state, keep autosave single-flight with bounded pending work, fail closed on ambiguous durable outcomes, and require explicit recovery from blocked conflict/failure states. Hosts own atomic persistence transactions and durable conflict resolution.
 
+### Review suggestions and transaction admission
+
+An untrusted review suggestion can target a stale revision, an unsupported projection boundary, or a range that no longer denotes the intended content. The Active PR / Proposed editor adapter validates the bounded proposal, hashes the captured document, verifies that the live `EditorState` did not change during hashing, and maps only an exact version-1 text boundary before dispatching one insert/delete transaction. Any mismatch fails closed without mutation. Hosts still authorize the actor and own durable exact-once decisions, audit, persistence, and re-anchoring; undoing a local transaction does not erase or rewrite host review history.
+
 ### Collaboration and Yjs
 
 Inkspan may bind to Yjs-compatible document/awareness surfaces but does not own provider creation, room authorization, tenant identity, persistence, retention, or durable audit. Yjs updates and awareness metadata can contain sensitive tenant information. Host providers must authenticate rooms, authorize membership, bound awareness disclosure, and apply retention/encryption policy. Inkspan must not silently create a network provider or elevate an awareness update into authorization.

docs/TRACEABILITY.md

@@ -15,6 +15,7 @@ This record maps durable Inkspan product decisions to authoritative standards, p
 | Envelope version routing | A bounded identity-only inspector identifies `schemaId`/`schemaVersion` for dispatch while the current parser stays strict and the host owns migration execution | RFC 8259; RFC 7493; RFC 8785 for canonical current-schema bytes | ADR 0015, protected-main `documentEnvelopeIdentity` implementation/tests, envelope guide/doctoring and framework-independent packed consumers | Protected-main evidence proves only bounded routing metadata; identifying a schema generation does not validate that generation's document semantics, authorize migration, or prove durable persistence |
 | Canonical document bytes | Deterministic revision evidence is derived from canonicalized validated document content | RFC 8785, JSON Canonicalization Scheme | revision-evidence, transition-evidence, restore tests | A content digest proves equality only, not actor/time/authorization/durable write |
 | W3C text-position selector | Revision-scoped annotation interoperability uses a distinct versioned logical-text projection satisfying `0 <= start <= end <= projectedCodePointLength`, with inclusive `start`, exclusive `end`, Unicode-code-point offsets, grapheme-boundary validation, and same-state revision binding instead of relabeling ProseMirror coordinates | W3C Web Annotation Data Model; ProseMirror reference manual; ECMA-402 13th edition | ADR 0018, protected-main text-position selector implementation/tests, packed consumer verifier, selection lifecycle and doctoring | Protected-main evidence proves positions only for the named projection and exact revision; it does not prove actor, authorization, durable annotation acceptance, source IRI policy, or cross-revision re-anchoring |
+| Exact-revision review mutation | Authorized insert/delete acceptance maps the versioned selector into the same captured editor state and dispatches one undoable transaction; rejection preserves the document | W3C Web Annotation Data Model; ProseMirror state, transaction, and history contracts | Active PR ADR 0005, review handle integration/concurrency/undo tests, packed root consumer | Local mutation evidence is not actor authorization, durable exact-once decision state, audit, persistence, or cross-revision re-anchoring |
 | Headless deterministic Markdown conversion | One serializer implementation and one framework-neutral safe-link/inline-raster policy are exposed through a self-contained ESM/CommonJS/TypeScript `./markdown` subpath | CommonMark 0.31.2; Node.js package `exports` documentation | protected-main #114 implementation, packed Node consumers, package-distribution contract, `docs/doctoring/headless-markdown-package.md` | `implemented_on_protected_main`; deterministic conversion does not grant MIME delivery, recipient, auth, tenant, persistence, network, credential, or model authority |
 | Provenance semantics | Local transition/release evidence keeps content lineage separate from actor/authorization/durable claims | W3C PROV family | transition evidence, release evidence, canonical data model | Inkspan does not claim complete PROV conformance or host audit provenance |
 | Accessibility | Native controls, keyboard semantics, shortcut metadata, semantic placeholder guidance, and host-facing status state support accessible embedding | W3C WCAG 2.2; WAI-ARIA 1.2 where used | protected toolbar/accessibility tests, SSR tests, autosave lifecycle data, protected #131 placeholder tests/packed consumer and `docs/doctoring/editor-placeholder-accessibility.md` | Component evidence alone is not a full host WCAG conformance claim; `aria-placeholder` supplements but never replaces the accessible name |