feat(diagnostics): bind diagnostics to exact editor revisions

[seonghobae]

Stacks on #256 (feat/writing-diagnostics-decorations) at exact live base 56d3da78c7330636f635699eec302b5ab7d0c2ae.

Product slice

Implements Task 4 of the committed writing-diagnostics plan: the revision-bound controller for host-supplied diagnostics. Inkspan validates hostile diagnostic input before reading editor state, captures one immutable ProseMirror document snapshot, derives the strong document revision from that exact snapshot, resolves every selector atomically against it, and installs structural decorations only for the unchanged verified generation.

The controller performs no semantic language judgment, model/provider call, network access, persistence, tenant/auth logic, or stale-text repair. Every document-changing transaction invalidates the active generation. Asynchronous digest and selector work is fenced by monotonic generation and editor identity. Host callback exceptions are contained, and action events contain no authored source, explanation, replacement, prompt, or model output.

Test-first and defect evidence

The implementation retains an observable RED → GREEN history:

1. Hosted RED is preserved at test-only head 3d7f51c81e4bd6308a89ebd2b912b394fc37068d: workflow 31560671280, job 94002103814, failed because the controller implementation did not exist.
2. Initial implementation exercised the intended controller lifecycle and exposed strict TypeScript fixture errors, which were corrected without weakening production validation.
3. An inline array passed by a normal React consumer caused repeated revalidation and runner exhaustion because input identity was treated as semantic change. The controller was changed to compare detached validated content plus editor/digest identities instead.
4. Exact coverage then exposed two unproved paths: an impossible validation-error fallback and the post-projection editor teardown path.
5. A teardown regression test was committed first at 01673b4497a2e9b51c9d799e6a684bb3c9c40580; workflow 31588082298, job 94086455633, failed as expected because a destroyed editor remained in verifying rather than publishing stale.
6. A separate generation-invalidation test proved that a transaction occurring immediately after selector resolution must discard that resolved generation.
7. One-shot repair workflow 31588737188, job 94088522761, applied the bounded source correction, passed focused behavior, exact coverage, and TypeScript, committed 4609f4be433581832ab0529cb8c7bc36ccad5bf0, and removed itself.

Implemented behavior

• strict hostile-input validation before editor access;
• immutable document-envelope capture and SHA-256 revision derivation from the same snapshot;
• exact revision and projection matching without normalization or compatibility guessing;
• atomic all-or-nothing selector resolution against the captured document;
• monotonic generations for overlapping verification requests;
• stale invalidation on every local or collaborative document-changing transaction;
• editor replacement/destruction fencing, including destruction after selector resolution;
• no mapping or nearest-text fallback across a changed document;
• latest callback identity without editor/controller recreation;
• privacy-minimized focus, ignore, dismiss, and explanation-request events;
• contained host callbacks and redacted stable error codes;
• no model, provider, network, storage, authentication, or tenant authority.

Exact-head acceptance

Exact final head: c2f6df89cb193f6e3b9abcbf1fba078c79385784.

Workflow 31588901010, job 94089036234, completed successfully on that exact head:

• 4 controller test files and 34 tests passed;
• useWritingDiagnosticsController.ts: 436/436 statements, 11/11 functions, 150/150 branches;
• strict TypeScript checking passed;
• every package entrypoint built successfully;
• packed-package ESM, CommonJS, SSR, subpath, and strict TypeScript consumers passed;
• the demonstration application built successfully.

No inline review thread is unresolved on the current PR snapshot.

Remaining gates

This PR intentionally remains Draft and stacked. Protected main remains frozen for the 0.6.0 release candidate while release issue #118 is open. The branch-specific TDD workflow is retained only as exact implementation evidence and must be removed before eventual integration. Current-head required checks, independent approval, security evidence, parent-stack integration, and release-only publication remain mandatory.

This PR does not claim Task 5 diagnostic UI, Task 6 standalone/imperative application integration, Task 7 collaborative parity, a merged release, or an npm publication.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ef28700c-450a-4d05-b040-3043dd548a8e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}