Skip to content

docs(adr): add ADR-0029, structured statement edits for raw Workshop - #784

Merged
Teakowa merged 3 commits into
mainfrom
docs/adr-structured-statement-edits
Oct 19, 2026
Merged

Teakowa merged 3 commits into
mainfrom
docs/adr-structured-statement-edits

Conversation

@e54-bot

@e54-bot e54-bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Proposes ADR-0029: structured statement edits for raw Workshop. It decides the write direction that ADR-0024 left open ("a typed authoring API").

  • Input: a condition or action written as a rule-content-v1 list item. No second authoring format.
  • Owner split: workshop-rs converts the statement to its public model and returns the checked SourceEdit (canonical text in the file's locale, indentation relative to the surrounding source). Wright composes no Workshop text.
  • Surface: new editStatements operation in wright-agent/v1 (serve + MCP).
    • Addressing: rule + conditions/actions + index + insert/replace/delete.
    • Atomic: every address refers to the pre-edit program; insert takes a statements array.
    • Freshness: guarded by inputIdentity.
    • Validated through the existing validateEditTransaction path. Nothing is written by the operation.
  • Scope: raw Workshop only; OverPy/OSTW input is refused with the owning implementation named.
  • Edge rules:
    • replace keeps a statement's leading comment and delete removes it with the statement.
    • Inserting into an absent section creates it.
    • Optional sources works for unsaved buffers, as in validateEditTransaction.
    • Emission uses the session's resolved locale.
    • A replaced statement is visibly respelled in canonical form.
  • Round-trip contract: content(parse(emit(from_content(c)))) == c, checked by workshop-rs over its corpora.

Out of scope: rule-level edits, declarations, a CLI command, source-language authoring, and the form factor of an editing view.

Why now

A read-only structured editing prototype (rule tree plus in-game-style create condition/action forms built from lookup signatures) produces correct rule-content-v1 nodes, but no operation turns a node into source text. Without this decision every client would carry its own copy of Workshop emission.

Related catalog gaps found by the same prototype are tracked separately: #781, #782, #783, wrightkit/workshop-rs#495, wrightkit/workshop-rs#496, wrightkit/workshop-rs#497, wrightkit/workshop-rs#498.

Review

Accepted by the owner after review of the open points: raw-Workshop-only scope, comment preservation on replace, visible canonical respelling, and the caller-writes edit path. The review also changed insert to take a statements array so an If, its body, and its End share one address. Documentation only; no code or behavior changes.

ADR-0029 decides the write direction that ADR-0024 left open: clients submit rule-content-v1 statements, workshop-rs converts and emits them as checked source edits, and Wright exposes editStatements over serve and MCP, validated through the existing edit-transaction path.
Statement comments survive replace and go with delete, inserting into an absent section creates it, editStatements takes the same optional sources as validateEditTransaction, and emission uses the session's resolved locale. The ADR also states that a replaced statement is visibly respelled in canonical form.
An insert now takes a statements array, so an If, its body, and its End land at one address without tripping the same-address conflict rule. The ADR defines statement, statement address, and structured view, and leaves the view's form factor and its operation boundary to the decision that introduces it. Accepted after the owner confirmed raw-Workshop-only scope, comment preservation on replace, visible canonical respelling, and the caller-writes edit path.
@e54-bot e54-bot changed the title docs(adr): propose structured statement edits for raw Workshop (ADR-0029) docs(adr): add ADR-0029, structured statement edits for raw Workshop Oct 19, 2026
@Teakowa
Teakowa merged commit d4c0f66 into main Oct 19, 2026
16 checks passed
@Teakowa
Teakowa deleted the docs/adr-structured-statement-edits branch October 19, 2026 11:36
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Make Workshop Great Again Oct 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Development

Successfully merging this pull request may close these issues.

2 participants