Define the canonical Workshop comment and source-preservation contract

[Teakowa]

Parent: #108

Goal

Define the remaining canonical workshop-rs source-preservation contract for authored Workshop comments/trivia and mixed-source consumers without introducing a second opaque representation for Workshop semantics that the current WIR already models canonically.

Current status

Rebaselined from the original workshop-rs 0.1.1 premise.

The current raw Workshop parser/WIR/validation/emitter surface now represents ordinary supported Workshop semantics canonically. A source-language consumer embedding vanilla Workshop should therefore parse/use that canonical representation rather than require a DEL-local or workshop-rs opaque/raw rule model merely because the source originated inside another language.

The durable remaining owner-side question is source preservation: authored comments/trivia and any source-level attachment/provenance needed for safe mixed-source tooling and reconstruction.

Context

del-rs Issue #32 and historical Draft PR #42 provide consumer evidence for source files that mix DEL/OSTW constructs with vanilla Workshop blocks and comments. workshop-rs owns the Workshop-language representation and preservation semantics; del-rs owns how its source grammar embeds/resolves those regions.

Scope

• Define which Workshop comments/trivia are preserved as part of the public source/WIR contract and which are presentation-only/non-semantic.
• Define stable attachment/provenance semantics for authored rule/action/condition/settings comments where preservation is supported.
• Preserve enough source structure for diagnostics, source-aware editing, and useful reconstruction without requiring exact whole-file formatting reproduction.
• Ensure embedded supported vanilla Workshop content uses the same canonical parser/WIR/validation/emitter path as standalone raw Workshop.
• Define explicit failure/incompleteness behavior for malformed, genuinely unsupported, legacy, or evidence-insufficient embedded Workshop content.
• Add focused parse/preserve/edit/emit/reparse evidence for comments and mixed-source Workshop regions where the owner-side contract applies.
• Keep the contract suitable for consumers other than DEL/OSTW.

Non-goals

• A second opaque/raw WIR representation for ordinary supported Workshop semantics.
• DEL/OSTW grammar, project loading, source embedding syntax, or runtime lowering.
• Exact formatting/trivia identity for untouched whole files unless separately required by a source-edit contract.
• Full pretty-printer regeneration as the default edit model.
• Workshop-to-DEL decompilation.
• A provider-local catalog or emitter.

Acceptance criteria

• Ordinary embedded Workshop constructs use the same canonical Workshop semantic representation as standalone raw Workshop.
• A reviewed public contract defines supported comment/trivia preservation and attachment/provenance behavior.
• Supported source-aware edits can preserve unrelated comments/trivia and structure rather than requiring full regeneration.
• Malformed/unsupported embedded content fails or remains explicitly incomplete without guessed semantics.
• Parser/WIR/emitter/source APIs provide enough stable provenance for consumers to explain and preserve authored Workshop content.
• del-rs and future consumers can integrate through public Workshop source/semantic APIs without copying parser/catalog/emitter logic or inventing a parallel raw Workshop model.

Relationships

• Parent pre-1.0 API track: Establish typed Workshop settings as a stable core API before 1.0 #108.
• Harden the Workshop-facing Rust API for the 1.0 candidate #112 should not freeze the 1.0 WIR/source API until this contract has a reviewed disposition.
• Consumer integration remains owned by del-rs Define the canonical Workshop comment and source-preservation contract #32 and equivalent future source-language repositories.

[Teakowa]

Reviewed disposition (2026-08-28)

Keep this issue open as a hard dependency of #112; do not treat the current Span fields or semantic unknown preservation as a completed comment/trivia contract.

Current evidence:

• workshop-rs lexer skips // comments, and its public WIR currently carries semantic node spans but no public authored-comment/trivia representation or attachment contract.
• The source-preserving settings carrier preserves typed/unknown settings structure, but does not establish comment/trivia preservation or source-aware edit behavior for mixed Workshop regions.
• deltin-rs retains source tokens/trivia on its DEL side, but its vanilla Workshop settings/rule regions remain opaque and its current released dependency is workshop-rs = 0.1.11; it is not evidence that the owner-side Workshop contract is available.
• The Expose typed settings query, validation, and source-preserving edit APIs #111 external consumer dogfood proves the typed settings API crosses a crate boundary, but it does not discharge this source-preservation dependency.

Minimum exit evidence for this issue is a reviewed public contract for supported Workshop comments/trivia and attachment/provenance semantics, focused parse/preserve/edit/emit/reparse tests for the supported slice, and an explicit incomplete/fail-closed result for unsupported or malformed mixed-source content. Until then, #112 must remain unstarted.

[Teakowa]

Progress update after #110/#111 re-review

#110 has now been independently re-QA'd and remediated in PR #120, with baseline failure, treatment success, and a disposable duplicate-projection mutation recorded on the PR.

#111 is being re-reviewed in PR #121. Its applicability/target-safety blockers are fixed and independently falsified, but the source-preserving patch/edit contract is still intentionally open. The current Workshop carrier has spans and a mutable tree, but no source buffer or applyable patch type; no claim of source-trivia preservation or real consumer dogfood is being made yet.

#32 therefore remains an active dependency. #112 must not start until #32's source-preservation disposition and #111's source-edit plus downstream consumer evidence are complete.