feat(review): add bounded review contract surface

[seonghobae]

Scope

Refs #374. This Draft is the canonical single-writer lane for Inkspan's provider-neutral review contract and controlled presentation surface. It currently includes deterministic target/suggestion validation, revision-bound operation evidence, bounded host-supplied thread presentation metadata, a controlled accessible React adapter with suggestion accept/reject intents, deterministic thread-list keyboard traversal, fail-closed collection ingress, public typed-error normalization for untrusted host presentation/intent failures, a controlled accessible inline target marker, and a fail-closed exact-revision admission guard for suggestion mutations.

It does not claim the full #374 product slice is complete or shipped. Protected main remains the only shipped implementation authority.

Lifecycle truth

Do not treat any PR-body SHA, workflow result, merge base, or review inventory as durable lifecycle truth. Before every source write, protected-main reconciliation, review transition, or merge decision, independently refetch the submitted head, protected main, ancestry/mergeability, active writers, formal reviews/threads, live rulesets, and all applicable exact-head repository/central workflows. The PR API's embedded base.sha may be historical and is not a substitute for resolving the live protected-main tip.

Current active-PR surface

The Draft exports a React-free @contextualwisdomlab/cwl-editor/review package subpath plus optional @contextualwisdomlab/cwl-editor/review-react presentation. Review evidence uses Inkspan's canonical document revision and W3C TextPositionSelector projection instead of DOM offsets. Inputs are bounded and validated; snapshots are detached/frozen where applicable. Inkspan does not acquire host identity, authorization, persistence, tenancy, transport, durable audit, retention, collaboration admission, credential, network, or model-policy authority.

CwlReviewThreadList validates collection shape before item inspection, rejects oversized/sparse/non-enumerable/accessor-backed slots fail-closed, validates host labels/action callbacks, supplies accessible thread/action names, and maintains one deterministic roving thread target. Arrow Up/Down/Home/End move DOM focus only and do not commit host selection. Private exceptions from validated host label/intent callbacks are normalized to the public CwlReviewPresentationError contract rather than exposing private host details.

CwlReviewTargetMarker exposes the active review target as a bounded accessible button with deterministic selected-state semantics and controlled host intent callbacks; invalid labels/callbacks fail closed through the same public presentation-error boundary rather than acquiring editor-selection authority.

assertReviewSuggestionCurrentRevision is the mutation-boundary admission guard for provider-neutral insert/delete proposals. It validates the untrusted suggestion, computes the exact current document revision through the canonical revision implementation, and fails closed with the stable redacted stale_operation contract when the target revision differs. It returns only the detached validated suggestion and does not copy the current document body into review evidence. Hosts retain authorization, persistence, conflict policy, and durable audit authority.\n\nCwlEditorHandle.applyReviewSuggestionDecision now applies an admitted insertion or deletion as one normal history transaction and returns revision-bound operation evidence. Rejection preserves the document, asynchronous revision hashing is guarded against editor-state races, and stale retries fail closed without mutation.\n

TDD lineage

The callback-failure work established that React/JSDOM error-report cardinality is not a product contract. The durable invariants are that the host callback executes once, externally observed failures use the stable public CwlReviewPresentationError contract, and private host exception details are not exposed.

The stale-revision mutation guard was developed test-first on this existing branch: a RED contract first required suggestions targeting another document revision to be rejected before mutation, followed by the narrow implementation that computes the canonical current revision and returns stale_operation on mismatch. Repository CI for lifecycle decisions must always be re-fetched at the exact current head rather than inherited from this lineage.

The inline target marker was likewise developed test-first on this branch: a test-only parent commit required accessible target intent before the narrow presentation implementation landed. Exact-current-head repository CI is the only GREEN evidence for lifecycle decisions.

Shared control-plane evidence

Central workflow evidence is owned by the organization .github boundary. Known aggregate-green false-evidence classes include dependency-review jobs that skip the actual review action and scanners that analyze a synthetic merge rather than the submitted head. Existing owner paths are ContextualWisdomLab/.github#810 for dependency-review fail-closed behavior and ContextualWisdomLab/.github#1222 for exact-source scanner binding. Do not add Inkspan-local competing workflow writers or transfer predecessor/synthetic-source evidence.

Pending, queued, skipped, cancelled, absent, neutral, failed, stale, predecessor, status-only, model-only, wrong-checkout, or synthetic-source-only evidence is non-passing.

Completed packed-artifact acceptance\n\nThe exact current branch verifies both review and review-react from the packed npm artifact through ESM, CommonJS, and strict TypeScript consumers. The React-free core additionally enforces its bounded runtime-authority import contract. This is branch evidence only until protected integration; it does not imply registry publication.\n\n## Remaining #374 work

This PR does not close #374. Remaining product work includes:

• physical screen-reader acceptance beyond the current Chromium/Firefox/WebKit keyboard, print, responsive, and forced-colors journeys;
• executable canonical contract/ADR/UML/data-model/threat-model/traceability updates as semantics settle;
• visual-regression acceptance beyond the current Storybook workflow-state inventory;
• packed-artifact consumer acceptance for each newly exposed review API.

Integration boundary

Keep this PR Draft while #118 owns stable-release publication/provenance/digest acceptance and until the branch is reconciled with live protected main through a safe, non-destructive, source-owner-aware path. Do not force-push/destructively rebase, self-approve, weaken gates, transfer predecessor evidence, fabricate release identity, or represent Draft behavior as protected-main shipped truth.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Reconciled this Draft non-destructively with protected main at new submitted head 38921509c8d6788643b1c0779c3cf3bf9e29473f after #401 merged. The branch also temporarily carries the exact #402 regression fix so its current-head Office check does not fail on #401’s static-matrix contract mismatch and still tests Python 3.11/3.14 boundaries before merge.

Combined-tree local evidence:

• pnpm run coverage: 171 files / 947 tests passed; 100% statements, branches, functions, and lines
• pnpm run typecheck: passed
• actionlint .github/workflows/*.yml: passed
• all four Python support-contract checks executed with local Python 3.14: passed
• git diff --check: passed

The product behavior remains the exact-revision review surface described earlier. #402 owns the protected-main workflow correction; this Draft does not claim that correction as shipped until #402 is independently reviewed, checked, and merged.

[seonghobae]

Corrected the transient Python boundary-matrix carry-forward at new head 277bcf3. Following the exact #402 Codex finding and canonical Office doctoring, this Draft again requires Python 3.11, 3.12, 3.13, and 3.14 independently on every PR. Focused workflow contracts (13), actionlint, Python support contracts, and diff checks passed before push; predecessor queued checks are superseded.

[seonghobae]

Exact-head package acceptance at 277bcf377eb728e247cb1735dc1a8e603e1a6b4b completed successfully. pnpm build and the full pnpm verify:package chain passed, including authority-bounded packed ESM/CommonJS/strict-TypeScript consumers for both review and review-react. The PR description now records this branch evidence as completed and no longer lists it as remaining. Hosted checks are still independently required.

[seonghobae]

Exact-head local browser evidence for 277bcf377eb728e247cb1735dc1a8e603e1a6b4b: all 12 review journeys passed across Playwright 1.62.0 Chromium, Firefox, and WebKit, covering deterministic keyboard focus/intent, explicit print inclusion, 360px reflow, and forced-colors focus/selection cues. This does not substitute for hosted exact-head checks or physical screen-reader acceptance.

@codex review

[seonghobae]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-04T15:00:25.974003Z	277bcf3	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 277bcf377e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[seonghobae]

@codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[seonghobae]

Added exact-head accessible suggestion decision controls in 0bcd4ae. CwlReviewSuggestionDecision validates and detaches one insert/delete suggestion through the React-free contract, bounds host-visible labels, disables missing capabilities, and emits accept/reject intents without claiming authorization, mutation, or persistence. Print output remains excluded by default.

Exact-head local evidence: 172 test files / 952 tests passed; typecheck and production build passed; packed review-react ESM/CommonJS/TypeScript consumer verification passed; 15 review browser tests passed across Chromium, Firefox, and WebKit; git diff --check passed.

[seonghobae]

@codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[seonghobae]

Exact-head verification for d153e92e92215d989ddee2a9b778519520926e63:

• pnpm test: 172 files / 952 tests passed
• pnpm typecheck: passed
• pnpm --dir tests/browser exec playwright test specs/review.browser.spec.ts --config=playwright.config.ts --project=chromium --project=firefox --project=webkit: 15 passed
• git diff --check: passed

This follow-up adds explicit cross-engine proof that suggestion summaries print only after opt-in while Accept/Reject controls remain excluded.

[seonghobae]

@codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[seonghobae]

Exact-head verification for 306055b7e5e7d5d91f2933cbb6c7f10649c3044f:

• pnpm test: 172 files / 952 tests passed
• pnpm typecheck: passed
• pnpm --dir tests/browser exec playwright test specs/review.browser.spec.ts --config=playwright.config.ts --project=chromium --project=firefox --project=webkit: 15 passed
• git diff --check: passed

Each suggestion decision now uses native fieldset/legend grouping instead of creating another named region landmark. This preserves its accessible name, button grouping, keyboard behavior, print behavior, and visual layout while avoiding landmark proliferation when many suggestions are rendered. The repository has no axe runtime dependency, so no new package was added.

[seonghobae]

@codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[seonghobae]

Revalidated exact head 6bb054d0d437b3553dc73fee17373cb898738127 after reviewing the accepted-suggestion mutation boundary.

• Added regression coverage for an editor change that occurs while accepted-operation evidence is being created; the pending transaction now remains undispatched and fails closed as stale_operation.
• Removed unrelated event-specific Python-matrix test commits from this branch before push; feat(review): add bounded review contract surface #378 remains scoped to the review contract.
• pnpm typecheck && pnpm coverage && pnpm build && pnpm verify:package: PASS (172 files, 953 tests, 100% statements/branches/functions/lines; build and packed consumer verification passed).
• pnpm exec playwright test specs/review.browser.spec.ts: PASS (15/15 across Chromium, Firefox, and WebKit).
• uv run --project office --extra test coverage run -m pytest && uv run --project office --extra test coverage report: PASS (173 tests, 100% coverage).
• git diff --check: PASS.

The PR remains Draft because the parent review gap is not yet fully integrated. @codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.