0017: Reference-preserving sdfThing authoring

The first Model authoring operation creates a new sdfThing from explicitly selected reusable sdfObject definitions, caller-chosen Given Names, namespace intent and Composition patches. Its authoring contract fixes ownership, generated-content access, fidelity, optional checking and explicit CLI output behavior. It builds on ADR 0013: Shared workflow and report guarantees and ADR 0007: Generated SDF and sample JSON.

Generated SDF retains an authored sdfRef to each selected sdfObject’s established global name and the caller’s patch, rather than silently flattening or transplanting reusable definitions. The generated catalogue contains the immutable supplied documents and the new document. Namespace mappings are explicit; source namespace prefixes are not copied as if they were global identities. Global contributor ambiguity and missing required dependencies leave affected work incomplete. Copied references inside the selected definitions follow ADR 0036: Copied reference relocation. A local-only sdfObject is a scoped unsupported authoring capability in this first reference-preserving operation, not invalid SDF. No namespace is assigned to its source without a request.

Explicit declaration requiredness uses an abbreviated Referenceable name only when that Given Name is valid in the abbreviated form. A Given Name containing # is preserved and selected by an encoded same-document SDF pointer reference instead, following RFC 9880 Section 4.5. Decoded JSON Pointer tokens and URI-fragment encoding remain distinct. This rule authors new declaration references. Inherited requiredness needs no rewriting, because copied pointers relocate to the new sdfThing’s coordinates.

Generation and fidelity are distinct from requested Model checking. Complete generated bytes can coexist with undetermined fidelity or a failed assessment, and remain available as a clearly tagged candidate for library inspection. A faithful result requires established composition and preservation of known semantics, Given Names, accepted number lexemes and permitted opaque structure; uncertainty about context-dependent opaque meaning leaves fidelity undetermined. Restrictive refinement is the RFC’s convention, not a general subset proof promised by authoring. An initial check can establish its own narrower result without establishing full RFC coverage.

The CLI emits a generated document only when generation and fidelity are complete and any requested check passes under the selected warning policy. Report and document destinations are separate, with one stdout user at most. Existing outputs require an explicit replacement option; input aliases and report/document collisions are always refused. Files are committed individually through bounded staging, without promising a transaction across two files or stdout. Inputs are immutable and never output targets.

Generated bytes and request-plan parsing are finite and charged before allocation or emission. Shared source, metadata, parsed/derived content, work, path and report limits apply across authoring and its optional checking; phases do not reset them. This follows ADR 0009: Bounded processing and reporting and ADR 0012: Exact numbers and JSON input policies.

Considered Options

Automatically copying local-only sdfObject definitions into the new document or flattening effective content can move opaque semantics out of the context that gives them meaning. Inventing a namespace for a supplied document changes its contributed identities. Automatically choosing prefix spellings or collision winners hides caller intent. Requiring all sample support or specialized checking would postpone ordinary established composition without improving its fidelity. Treating candidate availability as fidelity or completed checking hides independent limitations. Implicit overwrite or combined report/document stdout makes authoring unreliable in command-line workflows.