[M14] Validated source edits and semantic refactoring across Wright frontends

[Teakowa]

Goal

Make validated source-oriented mutation a first-class Wright tooling capability across supported source frontends, using semantic identity and project/source provenance rather than whole-source regeneration or mutable IR APIs.

The governing workflow is:

semantic understanding -> validated source edits -> original source

M14 should turn the existing OPY-focused safe-edit/rename work into a shared, agent-usable source mutation platform without coupling it to LSP, a specific agent harness, or reconstruction emitters.

Context

M13 completed the declared Workshop-centered interoperability matrix and established native OSTW semantic/tooling support. The next high-value gap is no longer conversion breadth.

Current repository evidence shows the source-edit layer has not caught up with the shared compiler/session architecture:

• crates/wright-driver/src/edit.rs still validates edited source by forcing SourceKind::Opy and a temporary edit.opy path;
• the original M9 SourceEdit contract is primarily single-source, while M10 later implemented project-wide semantic rename through language-service/workspace machinery;
• OSTW tooling was intentionally accepted in [M13] Integrate the accepted OSTW semantic surface with Wright tooling services #120 without source-edit/refactoring support;
• ToolService exposes read-only semantic/query operations but no validated mutation/preview operation;
• [M13 reverse] Reconstruct the declared Workshop surface as valid OPY source #124/[M13 reverse] Reconstruct the declared Workshop surface as valid OSTW source #125 reconstruction is interoperability output and must not become the default edit mechanism for original OPY/OSTW source.

M14 should reconcile these layers around one source-aware mutation contract.

Scope

• Reassess the existing M9 safe-edit contract and M10 project-wide semantic rename against the current OPY/OSTW/session/source-registry architecture.
• Define a frontend-neutral, source-aware edit transaction model with:
  • source/file identity;
  • version/content preconditions;
  • exact source ranges;
  • multiple edits across multiple files where required;
  • deterministic overlap/conflict handling;
  • preview and validation results;
  • structured refusal diagnostics.
• Validate edits through the same native project/session semantics as the original source kind instead of forcing OPY or regenerating source from WIR.
• Preserve project roots, imports/includes, overlays, source provenance, and cross-file semantics while validating candidate edits.
• Reuse and consolidate the proven M10 semantic-rename machinery rather than maintaining separate textual/LSP-only rename semantics.
• Add semantics-backed rename for the declared OSTW source surface where symbol identity and source spans are sufficient to prove correctness.
• Expose validated edit/refactoring preview through Wright-owned embedding/tool-service APIs so agents can request semantic edits without depending on LSP or a specific harness.
• Keep transport adapters thin and map the same editor-neutral edit results to LSP/agent consumers where applicable.
• Add real-project/cross-language regression evidence for stale versions, collisions, cross-file edits, overlays, unsupported constructs, and validation failures.

Non-goals

• Whole-source OPY/OSTW regeneration as the normal mutation model.
• Using Workshop -> OPY/OSTW reconstruction to edit an existing higher-level source project.
• A generic arbitrary AST/HIR/WIR mutation API.
• Automatically writing files from semantic core without an explicit caller/application boundary.
• Extract-method, inline-function, formatter, code-action breadth, or other refactorings without concrete evidence.
• Expanding OPY/OSTW language compatibility merely to make a refactoring possible.
• Editor-specific UX or coupling core contracts to LSP types.
• A plugin ABI or content registry.

Initial sequencing

1. Reconcile/generalize the edit transaction + validation contract against current project/session semantics.
2. Reuse that contract for semantic rename across the accepted OPY/OSTW source surfaces.
3. Expose mutation preview/validation through the shared tool/embedding surface.
4. Independently verify source correctness, stale/conflict refusal, provenance, agent/LSP reuse, and CI before adding broader refactorings.

Detailed later refactoring scope should be driven by actual agent/editor consumers rather than symmetry.

Acceptance criteria

• The shared edit-validation path no longer hard-codes OPY or a synthetic edit.opy workflow and validates through the correct native frontend/project semantics.
• A proposed multi-source edit carries sufficient source identity/version preconditions to reject stale or conflicting application safely.
• Semantic rename for the declared supported source surfaces edits only occurrences belonging to the resolved semantic identity, including project-wide references where supported.
• OSTW source edits operate against original OSTW source and project provenance; no reconstruction round-trip is used as the edit mechanism.
• Edit preview/validation is available through a transport-neutral Wright-owned API suitable for agents and embedding.
• LSP/editor adapters reuse the same underlying mutation contract rather than owning separate refactoring semantics.
• Unsupported or unsafe edits fail explicitly with structured source-located diagnostics and no partial mutation.
• Current compile/check/lint/analyze/inspect/convert behavior and compatibility gates remain green.
• No public mutation contract freezes internal HIR/WIR layout.
• PM performs a post-M14 reassessment before adding broader refactoring features.

Relationships

• Follows the tooling-first architecture contract in ADR-0008/[Architecture] Rebaseline Wright as a tooling-first semantic platform #88.
• Builds on M9 [M9] Define safe source edit and refactoring contracts #59 safe source-edit contracts and M10 [M10 correctness] Implement project-wide semantic rename #73 semantic project-wide rename.
• Follows M13 [M13] Integrate the accepted OSTW semantic surface with Wright tooling services #120 native OSTW tooling integration.
• Reconstruction from [M13 reverse] Reconstruct the declared Workshop surface as valid OPY source #124/[M13 reverse] Reconstruct the declared Workshop surface as valid OSTW source #125 remains an interoperability capability, not the mutation architecture.
• [v0.2 workshop-rs] Define Workshop catalog, locale, extension, and version boundaries #96 remains deferred and is not required for this milestone.

[Teakowa]

M14 execution decomposition

Current execution order after the M13 rebaseline:

1. [M14 foundation] Make source-edit transactions project- and frontend-aware #128 — shared project/frontend-aware edit transaction foundation.
2. [M14 refactoring] Unify semantic rename across OPY and OSTW on validated edit transactions #129 — semantic rename over the shared transaction contract.
3. After [M14 refactoring] Unify semantic rename across OPY and OSTW on validated edit transactions #129 is stable, run in parallel:
   • [M14 agent tooling] Expose validated source-edit preview and semantic rename through the shared tool API #130 — agent/tool/embedding mutation preview API;
   • [M14 language services] Converge LSP rename on the shared semantic refactoring contract #131 — language-service/LSP rename convergence.
4. [M14 acceptance] Verify validated mutation, refactoring reuse, and agent-facing contracts #132 — independent M14 acceptance + roadmap reassessment.

Night/side-load agents may use separate worktrees/branches for #130 and #131, but neither lane should bypass #128/#129 or duplicate semantic/edit ownership. Do not expand into additional refactoring kinds, compatibility breadth, reconstruction-based editing, plugin architecture, or #96 without new evidence.

[Teakowa]

Completed by merged PR #133. This issue is now historical; current roadmap/version planning is tracked by #134 and #135.