Authored-quality editing

Esdieff revises present authored qualities in one supplied SDF document. An owned EditRequest selects the original model source, a request key and a distinct generated key. Each Edit selects one authored named definition by decoded JSON Pointer and one exact Quality Name. replace requires an accepted JsonValue, including JSON null. remove carries no value. Both require a present original member.

The operation supports label, description and $comment on the six base named-definition classes, including ordinary nested definitions. Property and sdfData definitions additionally support exactly type, sdfType, const, default, enum, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, format, minItems, maxItems, uniqueItems, nullable, contentFormat and unit. Those data qualities remain unsupported on Thing, Object, Action and Event owners. Information blocks, arbitrary JSON, effective-only content, Action input/output, Event output, direct items, map-data entries and Choice alternatives are outside this owner capability. The operation refuses an owner or enclosing definition/data-description context with an authored sdfRef, irrespective of its value shape. Untouched Composition branches remain preserved.

A const or documentary default object/array is one literal value, never model structure or a Composition patch. Replacing it replaces the whole value. Literal null remains a present member, while removal makes the member absent. Replacement values are retained faithfully without quality-shape repair or coercion. Documentary values do not specify device behavior.

All targets are established against the original document before application. Empty or excess requests, malformed or overlong pointers, known missing owners/members, unsupported roles/qualities, duplicate decoded targets, contradictory operation fields, unknown source identities and generated-key collisions are request errors. Unreadable or incompletely decoded content and exhausted target-establishment work instead return scoped operational incompleteness.

EditRequest::from_plan(catalogue, bytes) accepts a UTF-8 JSON map with string key, source and generated_key, optional string generated_label, and a nonempty edits array. Each edit has string owner, quality and operation, with operation exactly replace or remove. value must be present for replacement, including explicit null, and absent for removal. Unknown fields, duplicate decoded members and repeated decoded targets are refused. source matches one supplied key exactly, without consulting labels or filenames. The generated key must differ from every retained source key, including substituted original evidence.

The plan retains original bytes and spans independently of model-source bytes. Public request locations retain the request key, logical /edits/index coordinate and original-plan span when available. Nested replacement coordinates remain below /edits/index/value. Typed requests retain the same logical coordinates with null textual spans.

Ownership and inspection

EditResult owns accepted intent, immutable original evidence, available candidate bytes and the active result Catalogue. original_source() exposes exact original bytes, path/URI, version and digest metadata. catalogue() and into_catalogue() expose active sources after replacing exactly the selected original contributor with the generated source. retained_sources() includes every retained attempt, including substituted evidence. Other contributors retain their identities and metadata. Explicit aliases remain distinct. Original evidence is never a name-resolution fallback.

The generated source has a new identity, caller key, Generated role and Generated acquisition state. Its acquisition URI, path, version and digest are absent. Same-document references stay within the generated document, and unchanged global names remain available to other contributors. A local-only source needs no namespace assignment.

target(index) relates one accepted edit to its original owner/member and request intent. Original spans describe original bytes. Generated-member spans describe generated bytes. Removed members return Field::Absent and receive no generated span. Typed request locations use /edits/index with no textual-plan span. request_origin() relates generated replacement content to /edits/index/value and any nested literal coordinate. These relationships do not promise exhaustive provenance.

Preservation and completion

Editing fidelity has identity esdieff.authored-quality-edit/1. Established fidelity verifies every requested change and every other authored JSON value, Given Name, definition position, namespace mapping and reference spelling. Unchanged and replacement numbers retain accepted lexemes, including exponents and numbers inside opaque or literal containers. Opaque content stays in its original authored position without a claim about unknown meaning.

Generated output is indented UTF-8 JSON with a trailing newline. Original whitespace, escape spelling, member order and byte spans are presentation details and are not reproduced. No numeric float conversion, normalization or coercion occurs.

Generation is independently complete, partial or unavailable. Fidelity is independently established or undetermined. A proven wrong edit or preservation loss fails the operation. Exhausted application, emission, decoding or fidelity work cannot produce completed editing or a deliverable document. Available candidate bytes remain inspectable. Successful editing without a requested Model check establishes faithful source changes, including intentionally invalid quality shapes, without claiming a valid model.

Optional Model checking

EditRequest::checking(Assessment::Initial) and checking(Assessment::FullBaseline) request one ordinary assessment. Other assessments or a repeated checking selection are request errors. strict_warnings(true) applies the ordinary warning policy. Checking selects the entire generated source as its root and uses the active Catalogue to establish needed dependencies. It neither independently certifies unrelated sources nor all consumers of the revised definitions. A subsequent ordinary Catalogue check can request that wider scope.

EditResult::checking() exposes the assessment, outcome, requested root IDs and assessment-area coverage. Full checking separately exposes its 54-requirement coverage. No check has an absent assessment/outcome/coverage, rather than a fabricated passed assessment. Complete candidate bytes and established Editing fidelity remain inspectable when a requested check fails or is unfinished. Ordinary delivery additionally requires that check to pass under its warning policy.

Source decoding, plan admission, transformation, fidelity and checking retain cumulative numeric, allocation and work allowances. A late limit preserves earlier established findings and leaves the whole requested editing operation unfinished. It never replenishes the check budget or turns an available candidate into delivered output.

Report 1.2

The supported esdieff.report envelope adds operation edit and version 1.2. Older operation meanings and unknown-operation guards remain unchanged. Top-level request.assessment and request.inventory are null. request.editing contains key, original_source, generated_source, edit_count and checking. The no-check slice reports checking as not_requested in both request summary and result.checking.state.

Requested coverage has count unit editing, total 1, and the existing assessed/unassessed/undetermined partition. This unit covers the whole request, including optional checking. An unfinished requested check therefore leaves this unit undetermined even when generation is complete and fidelity established. A completed check with findings still completes assessment of the unit, while the aggregate disposition fails. Broader RFC coverage remains partial. result retains generation, fidelity state and contract identity, generated document state/content completeness/retained bytes, original-to-generated substitution, active_sources, checking state and omissions. No generated JSON payload is mandatory.

Requested result.checking separately carries its assessment, inventory, scope, outcome and coverage. Its existing assessment_area and requirement units never count individual edits or the editing operation. Available Full inventories retain totals of 13 assessment areas and 54 requirements. Both established inventory aggregates remain mandatory when optional requirement rows or diagnostics are omitted. An unavailable inventory keeps its ordinary null inventory/total meaning. Ordinary source/effective check locations keep their meanings. Findings on revised replacement content can relate the generated span to the original member and /edits/index/value or its nested literal coordinate. These bounded relationships do not promise complete causality, and removed members receive no invented generated span.

Mandatory source records include all supplied/generated attempts, including original evidence. Scope roots identify the active generated source. Aggregate errors, completeness, identities, substitution and edit count remain present when optional diagnostics or pointers are omitted. Human and JSON conclusions use the same bounded projection. Editing diagnostics use separate edit_request locations with request key, logical decoded pointer and available textual-plan span. Typed spans are null. Existing source and effective locations retain their meanings.

Finite operation

The generated attempt and mandatory report envelope are reserved before request content is copied. All retained attempts share the configured ceiling of 256. Request/generated keys are at most 256 bytes, labels at most 512 bytes, selectors at most the configured 8 KiB default, and the nonempty request has at most 256 edits. Caller metadata shares the 1 MiB pre-copy ceiling. Original and generated raw bytes both count toward 4 MiB per-document and 32 MiB aggregate defaults, including after reuse of an active result Catalogue.

Source decoding, replacement admission, selection, traversal, transformation, verification and generated decoding share finite parsed-node/allocation, derived-node/allocation, numeric and work allowances. Storage and work are charged before allocation and emission, including JSON escaping, indentation and the trailing newline. Report detail has separate finite count, byte and pointer presentation limits. No phase replenishes an allowance. Reusing an active result Catalogue retains identity, acquisition-attempt and stored-byte accounting.

Plans are at most 4 MiB and obey any smaller configured document-byte ceiling. Generated-attempt and mandatory metadata/report reservation precede retained plan/request copying. Plan storage, JSON decoding and owned replacement copies consume the operation’s remaining allowances. Already charged replacement copies are admitted without charging their storage twice. Plan traversal carries its derived/work remainder into target establishment and generation.

Syntax and established field-shape errors are request errors. A hard decoding or admission ceiling that prevents a complete root, exact edit count or owned bounded request is a distinct admission-limit error and generates no document. Once request identity and the complete edit list are admitted, unavailable numeric capability, replacement copying or target-establishment work instead retains an unfinished result with the exact accepted edit count, original plan evidence and source substitution. It never permits ordinary document delivery.

Command and document delivery

The command accepts only explicit sources and a saved plan.

esdieff edit --source KEY PATH --plan PLAN --document-output DEST
  [--report-output DEST] [--check initial-v1|full-baseline]
  [--format human|json] [--strict-warnings]
  [--replace-document] [--replace-report]

Repeat --source KEY PATH for other contributors. The plan’s source selects exactly one supplied key. Document output is required, and report output defaults to stdout. One source or the plan may use - for stdin. Document and report may each use - for stdout, but never together. There is no directory discovery, implicit acquisition or parent-directory creation. Plans are bounded by 4 MiB, CLI metadata by 1 MiB, and supplied source attempts by 255 so that the generated attempt remains reserved within 256.

An ordinary document is delivered only after complete generation and established Editing fidelity, plus a passing requested check under the warning policy. Without a check, the report explicitly says not_requested. Failed or unfinished work emits a report without writing the ordinary document. Exit codes are 0 for passed work, 1 for findings or strict warnings, 2 for invalid invocation/request, 3 for unfinished work without independent failure, and 4 for host or output failure. Hard pre-admission plan ceilings produce exit 2 before an owned editing request exists. Admitted incomplete requests retain a report and use their ordinary outcome code.

Human/JSON reports and generated JSON use distinct destinations. Report color never changes generated document bytes or JSON reports. Source and plan bytes remain immutable. File destinations protect every supplied source and the plan against direct, symlink, hard-link and resolved-parent aliases. Document/report file identities must also differ. Existing outputs require their corresponding replacement flag and must be regular non-symlink files. A replacement flag never permits an input alias, and it does not apply to stdout.

Each file output rechecks destination and protected-input identities, writes and syncs bounded staging in the existing destination directory, rechecks again and then commits individually. Create-only output uses a hard link so an existing file cannot be overwritten. Explicit replacement of an existing file uses rename. There are at most 100 staging-name attempts. Named FIFO input identities are retained without opening their streams before acquisition.

The document is delivered before the report. On any abandoned-staging failure, cleanup is attempted explicitly. Cleanup failure returns exit 4 and names the retained staging path, the original failure when present and whether the document was committed/delivered. A report failure after document delivery identifies that delivered document on stderr. Failed stdout delivery can leave partial bytes. There is no transaction across the two destinations or stdout rollback.

Reacquire a delivered file through ordinary checking or inspection, supplying needed dependencies and the edited file rather than its original contributor. For example, esdieff inspect --view source --document revised.sdf.json --pointer /sdfObject/Sensor revised.sdf.json examines the revised authored owner, and esdieff check --assessment full-baseline revised.sdf.json requests ordinary Model checking.

This contract follows ADR 0034: Authored-quality editing with source substitution. Renaming/moving definitions, inserting absent qualities, reference rewriting, namespace rebinding, in-place source writes, composition-patch editing and before-and-after equivalence remain separate capabilities.