0034: Authored-quality editing with source substitution

Existing-document maintenance uses a distinct Authored-quality edit and Editing fidelity contract. Explicit owners select ordinary authored named definitions, and replacement or removal requires a present quality. Every target is established against original content before application. Owners inside any authored sdfRef context are excluded because Composition patch null has a different meaning from a literal JSON null replacement. The editing contract fixes source preservation, identity, limits and report meanings without changing ADR 0017: Reference-preserving sdfThing authoring.

The original retains exact bytes and acquisition metadata as evidence. Source substitution replaces exactly that active contributor with a distinct generated source, preserving other contributor identities and genuine ambiguity. Untouched references resolve through the active result Catalogue. Local-only documents need no invented namespace. Candidate generation, Editing fidelity and any requested Model checking remain independent conclusions.

Editing fidelity under esdieff.authored-quality-edit/1 verifies requested changes and preservation of every other authored JSON value and context. Numbers retain accepted lexemes, and opaque JSON remains in place. This does not prove before-and-after model equivalence or unknown extension meaning. It follows ADR 0007: Generated SDF and sample JSON, ADR 0012: Exact numbers and JSON input policies, and the finite cumulative budgets in ADR 0009: Bounded processing and reporting.

The additive report operation edit uses version 1.2 and counts one editing operation. Model assessment identity and counts remain separate, following ADR 0011: Machine-readable report contracts and ADR 0013: Shared workflow and report guarantees. Mandatory substitution, source attempts, aggregate outcomes and candidate completeness survive omission of optional detail.

The one editing unit includes any requested Model checking. Generation and Editing fidelity remain independent when that assessment fails or remains unfinished. Checking uses the generated root and ordinary needed dependencies under the same cumulative operation allowances. Hard plan ceilings that prevent complete request admission are distinct from an admitted unfinished operation, which retains its exact edit count and report.

The CLI reuses authoring destination identity protection, explicit replacement and individually committed bounded staging. Ordinary document delivery requires complete generation, established Editing fidelity and a passing requested check. Abandoned staging receives explicit cleanup. Cleanup or later report failure retains the primary error, identifies any retained staging and states whether the document was delivered. Two destinations and stdout do not provide transaction or rollback guarantees.

Considered Options

Adding editing to new-Thing authoring would merge different preservation claims. A generic JSON patch or upsert could add stale targets or edit opaque occurrences without an established definition role. Keeping old and edited sources simultaneously active manufactures global-name collisions, while coalescing byte-identical aliases would hide real ambiguity. Extending literal-null editing into Composition patches would silently adopt different semantics.