# R20 finite native assembly authoring plan

Baseline is exact R19-fix1 product freeze1 `3465c2fd655934c365ca5d4e3b5ee74300a0895abd9e898155aceeaac79b51d3` (168 files), archived before editing. All existing contracts remain. New explicit contract: `native-root-assembly-v1`.

The first implementation creates named native internal components under the root, inserts shared root occurrences of those exact current-session definitions, and writes owned definition metadata. It publishes an honest finite root-assembly projection with exact retained component/occurrence identities. No name, entity-token string, list position or coordinate equality substitutes for a retained SDK identity. Existing BOM reads can consume the resulting actual component graph and AdomMechanical attributes; BOM still requires online Fusion and its independent complete snapshot contract.

Initially only identity placement is supported. Any supplied nonidentity translation/rotation is refused before admission, not ignored. This avoids importing the legacy transform-array layout assumption and pending-position semantics into the first slice. Current-session assembly creation starts with no root occurrences; existing root geometry is observed/preserved but never moved. Repeated additions retain every exact returned definition/occurrence, bounded to32 definitions and64 occurrences. Nested definitions, preexisting/foreign component adoption, independent copies, external/configured/suppressed/pattern/jointed assemblies, occurrence movement/deletion and grounding edits are unsupported. Any unexpected pending snapshot is refused before effects; pending state arising after an add is unknown, with no speculative capture or rollback.

`component_create` retains the returned occurrence before any fallible read, then its exact Component, then applies the required name and validated optional metadata as explicit sequential stages. `occurrence_insert` only accepts a published owned definition, root parent, independentCopy absent/false and identity pose. `component_metadata` changes only exact owned definitions; shared occurrences therefore see one definition's changes. Local fields are name plus JSON-encoded AdomMechanical supplier, supplierPartNumber, sourceUrl, asPurchased and excludeFromBom. Native partNumber/description need online preflight and successful complete current-value getters before any mutation; unavailable offline is a precise refusal, never an empty fabricated value. Unsupported/ambiguous legacy args refuse explicitly.

Rust owns validation, deterministic metadata order/escaping, unit/policy bounds, canonical projection digest, readback comparisons and partial-stage results. Typed C++ only retains SDK objects, validates parents/membership and invokes one getter/setter/add per typed operation. Add/name/each-attribute are separately tracked, and all capacity is reserved before effects. Existing durable journal start precedes the execute callback; execute revalidates current root/assembly before the first effect. Any post-invocation error, acknowledgment loss, panic or changed final readback remains unknown with preserved prefix, faults the local assembly book and never grants replay/rollback. SDK leases release before document/context; uncertain release blocks clean teardown.

Projection guard is explicitly assembly-scoped: exact document/root revision, current component/occurrence membership, per-component revision/name/supported metadata, observed grounding/context flags, identity placements, bounded resource/timeline/pending state. Two complete captures must agree. It is not a full geometry revision. Capture distinguishes offline-omitted native cloud metadata from verified empty values. Reference IDs are document/epoch/session-bound and never reused.

Tests will exercise repeated definitions versus distinct occurrences/BOM quantities, mandatory name and strict legacy argument handling, metadata JSON escaping, per-stage failure/panic and acknowledgment uncertainty, capacity before effect, foreign/retired selectors, stale projection both before and after durable start, duplicate operation replay/conflict through the actual coordinator, unsupported scope/no backend effects, exact release failure and SDK diagnostic retention. Full Linux workspace, GNU Windows bindings, installed SDK syntax and formatting precede frozen handoff. Host qualification remains root-only with independent SDK observations.

Installed SDK evidence: Occurrences.addNewComponent creates a component plus occurrence; addExistingComponent creates another occurrence of a definition; independent-copy/nested/proxy behavior is separate. Occurrence.transform is retired in favor of transform2. Snapshots.add is valid only for pending state; no implicit capture of preexisting user changes is acceptable. Attributes.add updates the same group/name and returns the attribute; Rust must preserve typed JSON encoding. Component.partNumber empty resets to component name, so empty native metadata semantics need explicit readback. Existing BOM stage-specific evidence proves partNumber can fail offline. Current native sketch/extrusion authoring remains root-only: empty/shared assembly quantities and metadata are useful R20 coverage, while child-component solid creation/body transfer, placement and eventually exploded views remain subsequent ports.