Define the canonical Workshop comment and source-preservation contract

[Teakowa]

Parent: #108
Related 1.0 API contract: #112

Goal

Define the canonical workshop-rs source-preservation contract for authored Workshop comments/trivia and mixed-source consumers while keeping source/provenance information an optional capability attached to the canonical Workshop semantic program rather than a mandatory part of ordinary semantic construction.

Context

workshop-rs owns the canonical public Workshop program model used by raw parsing, tooling, and independent source-language lowering. The 1.0 API contract in #112 requires ordinary generated/lowered Workshop nodes to remain usable without synthetic spans or repeated source-metadata fields, while source-aware consumers must still be able to retain the provenance required for diagnostics, validated edits, comment/trivia preservation, and useful reconstruction.

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

deltin-rs integration history provides consumer evidence for source files that mix DEL/OSTW constructs with vanilla Workshop blocks and comments. workshop-rs owns the Workshop-language preservation semantics; deltin-rs owns how its grammar embeds/resolves those regions.

Scope

• Define which Workshop comments/trivia are preserved and which are presentation-only/non-semantic.
• Define stable attachment/provenance semantics for authored program/rule/condition/action/value/settings source where preservation is supported.
• Keep source spans, provenance, comment/trivia attachment, and edit-oriented source information optional with respect to the Workshop semantic nodes themselves.
• Allow raw Workshop parsing to populate source metadata automatically, source-language consumers to attach it when available, and programmatic generation to omit it entirely.
• Preserve enough source structure for diagnostics, validated source edits, and useful reconstruction without requiring exact whole-file formatting reproduction.
• Ensure embedded supported vanilla Workshop content uses the same canonical public Program semantics 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.

Non-goals

• Mandatory span: Option<_>/comment/provenance fields on every public Workshop semantic constructor or builtin API.
• A second opaque/raw semantic representation for ordinary supported Workshop constructs.
• 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 generated Workshop semantic construction requires no source metadata.
• Raw parsing and source-aware consumers can associate stable source/provenance metadata with canonical Program concepts without exposing storage internals.
• A reviewed public contract defines supported comment/trivia preservation and attachment/provenance behavior.
• Supported source-aware edits preserve unrelated comments/trivia and structure rather than requiring full regeneration.
• Malformed/unsupported embedded content fails or remains explicitly incomplete without guessed semantics.
• Parser/program/source APIs provide enough stable provenance for consumers to explain and preserve authored Workshop content.
• deltin-rs and future consumers can integrate through the canonical Workshop semantic/source APIs without copying parser/catalog/emitter logic or inventing a parallel raw Workshop model.
• The resulting contract is compatible with the 1.0 public API contract in Define and migrate to the canonical Workshop-facing Rust API for 1.0 #112.

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