Fusion - the Fusion 360 Bridge
Public Made by Adomby adom
Drive Autodesk Fusion 360 from the cloud via Adom Bridge: component libraries, IPC package generation, board layout, exports (STEP/Gerbers/BOM/CPL), fast APS cloud search, and parametric modeling.
master
b2d7cdb
26d ago
Native root assembly contract
Use X-Adom-Mechanical-Contract: native-root-assembly-v1, the existing session/token envelope, current sessionId, and an exact current-session target.documentId. All earlier operation-specific contract headers remain accepted for their prior operations. This adds three finite writes and one read; it does not change the legacy shared schemas into a full parity claim.
native_assembly_inspect is read-only and requires no operation ID. It opens a retained view only when the exact design initially contains just its root component and no occurrences. It preserves bounded existing root geometry. Subsequent reads validate the exact retained native definitions and root occurrences; no name, list-index, token or coordinate lookup adopts a replacement. The response is success:true, data containing root, components, occurrences, target, revisionScope, complete:false, and nativeMetadataObserved. Each component has componentId and ref:{documentId,revision,objectType:"Component",componentId}. Each occurrence has a distinct occurrenceId, its shared componentId, observed grounding/context flags and an identity matrix in explicit getCell row-major order. Raw attributes are JSON-encoded AdomMechanical strings, compatible with BOM metadata decoding. IDs remain stable within this exact document/epoch lifetime; revisions guard snapshots, not persisted document identity after a reload.
The default projection omits native PN/description getters: partNumber:null, description:null, nativeMetadataObserved:false. Explicit nativeMetadata:true requires online Fusion and complete successful native getters for every owned definition. Verified empty strings are preserved. The two modes produce different revisions. A known offline native-metadata refusal leaves the retained local view usable; a failed/uncertain identity capture retires that view. Never use an offline projection ref for a native PN/description update.
component_create: required nonempty name (at most 256 UTF-8 bytes); creates one empty internal root definition/occurrence, retains both exact returned objects, then sets the actual name and optional local metadata. Native PN/description in create metadata refuse before admission because their original values cannot be preflighted before the object exists.occurrence_insert: required exact published component ref; inserts another root occurrence of that same definition.independentCopymust be absent/false. Parent selection is unsupported.component_metadata: required exact published owned component ref and nonempty changes. Fields: name, partNumber, description, supplier, supplierPartNumber, sourceUrl, asPurchased, excludeFromBom. Native PN/description requires an online-mode ref and complete preflight. Name-only and local attribute writes use the local projection. When rename and description are combined, explicit partNumber is required so no implicit default-PN preservation is invented.
Every write requires matching target.revision with root-assembly-projection-v1: prefix. Component refs must contain exactly documentId/revision/objectType/componentId, matching the request target. All supplied legacy arguments are validated; unsupported parents, independent copies, or nonidentity transforms refuse before journal admission. Explicit identity transforms are accepted without invoking a transform setter. The transform planner does not capture pending positions. Existing pending snapshots refuse before effects; an unexpected pending state after insertion is an unknown result.
Metadata invocation order is name, partNumber, description, then lexically sorted attribute keys. Empty PN uses the documented reset-to-current-component-name behavior, verified against the final name. Strings are validated and JSON-encoded before effects, with a 4096-byte encoded-value bound; no truncation. Native PN/description values are never fabricated or replaced after getter failures. Updating a shared definition naturally affects all its occurrences; readback checks unrelated definitions, existing occurrence placements and root resource counts remain unchanged.
Successful writes return the updated projection in data, the selected componentId, and stages with explicit attempt.invoked/acknowledged, component and occurrence slots. Stages are preallocated before the first SDK call and marked conservatively before invocation. A failure after any invocation returns outcome:"unknown", reconciliationRequired:true, nativeExecutionStarted:true, observed stages and bounded SDK diagnostics. The assembly book then refuses further authoring. No automatic retry, compensating delete/rollback, or implicit snapshot action occurs. The existing retained journal reserves result storage, persists start before execution, and preserves observations after terminal persistence failure; duplicate operation IDs replay the recorded outcome, not SDK effects.
Bounds: 16 document views per runtime; 32 owned definitions and64 owned root occurrences per view; 128 attributes per definition; 128KiB raw projection; 128 existing root bodies/512 sketches/4096 timeline items. Root timeline must be at its end. Root and leaves exclude configurations, references, nested occurrences, mesh bodies and assembly solver graph resources. Leaves must have no bodies/sketches. Two full projections, each bracketed by root observation, must agree. Exact refs release explicitly before parent documents/context; uncertain release prevents a clean unload claim.
Qualification still needed: actual SDK default names, timeline/automatic grounding behavior, identity insert pending-snapshot behavior, metadata update/readback and native online metadata availability. Source/fake tests do not prove these actual-app semantics. Existing BOM may inspect these actual empty/shared definitions, but positive BOM quantity/purchasing qualification requires its own online complete snapshot gate. Child-solid authoring/body transfer, transformations, nested assemblies, joints, deletion, exploded views and full legacy mechanical parity remain later slices.
R20-fix2 refinement: acknowledged effect readback alone may retain and discard one initial capture whose root bracket changed only in revision. Two following internally stable complete projections must exactly equal that first projection after replacing only its root revision with the first observed final revision. Maximum three captures, no SDK-error or later-change retry, no repeated effect. Reads/preflight remain strict. readbackEvidence records capture hashes, changed-root evidence and a bounded first differing projection field on refusal. See the exact policy; prior unknown operations remain unknown.
R20-fix3 supersedes that initial comparison only: if the first root revision drift qualified, initial component revision witnesses may also be replaced with their second observed values. Every other field remains exact; the third full projection must equal the second, including all revisions. The subsequent pre-effect delta guard still rejects unrelated component revision changes. Combined root/component revision evidence must fit 8 KiB or the operation refuses unknown with complete hashes/lengths and explicit omitted payload. See the two-layer policy. No stable-first or later revision drift allowance is added.
# Native root assembly contract
Use `X-Adom-Mechanical-Contract: native-root-assembly-v1`, the existing session/token envelope, current `sessionId`, and an exact current-session `target.documentId`. All earlier operation-specific contract headers remain accepted for their prior operations. This adds three finite writes and one read; it does not change the legacy shared schemas into a full parity claim.
`native_assembly_inspect` is read-only and requires no operation ID. It opens a retained view only when the exact design initially contains just its root component and no occurrences. It preserves bounded existing root geometry. Subsequent reads validate the exact retained native definitions and root occurrences; no name, list-index, token or coordinate lookup adopts a replacement. The response is `success:true`, `data` containing `root`, `components`, `occurrences`, `target`, `revisionScope`, `complete:false`, and `nativeMetadataObserved`. Each component has `componentId` and `ref:{documentId,revision,objectType:"Component",componentId}`. Each occurrence has a distinct `occurrenceId`, its shared `componentId`, observed grounding/context flags and an identity `matrix` in explicit getCell row-major order. Raw `attributes` are JSON-encoded AdomMechanical strings, compatible with BOM metadata decoding. IDs remain stable within this exact document/epoch lifetime; revisions guard snapshots, not persisted document identity after a reload.
The default projection omits native PN/description getters: `partNumber:null`, `description:null`, `nativeMetadataObserved:false`. Explicit `nativeMetadata:true` requires online Fusion and complete successful native getters for every owned definition. Verified empty strings are preserved. The two modes produce different revisions. A known offline native-metadata refusal leaves the retained local view usable; a failed/uncertain identity capture retires that view. Never use an offline projection ref for a native PN/description update.
- `component_create`: required nonempty name (at most 256 UTF-8 bytes); creates one empty internal root definition/occurrence, retains both exact returned objects, then sets the actual name and optional local metadata. Native PN/description in create metadata refuse before admission because their original values cannot be preflighted before the object exists.
- `occurrence_insert`: required exact published component ref; inserts another root occurrence of that same definition. `independentCopy` must be absent/false. Parent selection is unsupported.
- `component_metadata`: required exact published owned component ref and nonempty changes. Fields: name, partNumber, description, supplier, supplierPartNumber, sourceUrl, asPurchased, excludeFromBom. Native PN/description requires an online-mode ref and complete preflight. Name-only and local attribute writes use the local projection. When rename and description are combined, explicit partNumber is required so no implicit default-PN preservation is invented.
Every write requires matching `target.revision` with `root-assembly-projection-v1:` prefix. Component refs must contain exactly documentId/revision/objectType/componentId, matching the request target. All supplied legacy arguments are validated; unsupported parents, independent copies, or nonidentity transforms refuse before journal admission. Explicit identity transforms are accepted without invoking a transform setter. The transform planner does not capture pending positions. Existing pending snapshots refuse before effects; an unexpected pending state after insertion is an unknown result.
Metadata invocation order is name, partNumber, description, then lexically sorted attribute keys. Empty PN uses the documented reset-to-current-component-name behavior, verified against the final name. Strings are validated and JSON-encoded before effects, with a 4096-byte encoded-value bound; no truncation. Native PN/description values are never fabricated or replaced after getter failures. Updating a shared definition naturally affects all its occurrences; readback checks unrelated definitions, existing occurrence placements and root resource counts remain unchanged.
Successful writes return the updated projection in `data`, the selected `componentId`, and `stages` with explicit `attempt.invoked`/`acknowledged`, component and occurrence slots. Stages are preallocated before the first SDK call and marked conservatively before invocation. A failure after any invocation returns `outcome:"unknown"`, `reconciliationRequired:true`, `nativeExecutionStarted:true`, observed stages and bounded SDK diagnostics. The assembly book then refuses further authoring. No automatic retry, compensating delete/rollback, or implicit snapshot action occurs. The existing retained journal reserves result storage, persists start before execution, and preserves observations after terminal persistence failure; duplicate operation IDs replay the recorded outcome, not SDK effects.
Bounds: 16 document views per runtime; 32 owned definitions and64 owned root occurrences per view; 128 attributes per definition; 128KiB raw projection; 128 existing root bodies/512 sketches/4096 timeline items. Root timeline must be at its end. Root and leaves exclude configurations, references, nested occurrences, mesh bodies and assembly solver graph resources. Leaves must have no bodies/sketches. Two full projections, each bracketed by root observation, must agree. Exact refs release explicitly before parent documents/context; uncertain release prevents a clean unload claim.
Qualification still needed: actual SDK default names, timeline/automatic grounding behavior, identity insert pending-snapshot behavior, metadata update/readback and native online metadata availability. Source/fake tests do not prove these actual-app semantics. Existing BOM may inspect these actual empty/shared definitions, but positive BOM quantity/purchasing qualification requires its own online complete snapshot gate. Child-solid authoring/body transfer, transformations, nested assemblies, joints, deletion, exploded views and full legacy mechanical parity remain later slices.
R20-fix2 refinement: acknowledged effect readback alone may retain and discard one initial capture whose root bracket changed only in revision. Two following internally stable complete projections must exactly equal that first projection after replacing only its root revision with the first observed final revision. Maximum three captures, no SDK-error or later-change retry, no repeated effect. Reads/preflight remain strict. `readbackEvidence` records capture hashes, changed-root evidence and a bounded first differing projection field on refusal. See [the exact policy](R20-POST-EFFECT-READ-SETTLING-FIX2.md); prior unknown operations remain unknown.
R20-fix3 supersedes that initial comparison only: if the first root revision drift qualified, initial component revision witnesses may also be replaced with their second observed values. Every other field remains exact; the third full projection must equal the second, including all revisions. The subsequent pre-effect delta guard still rejects unrelated component revision changes. Combined root/component revision evidence must fit 8 KiB or the operation refuses unknown with complete hashes/lengths and explicit omitted payload. See [the two-layer policy](R20-INITIAL-COMPONENT-REVISION-FIX3.md). No stable-first or later revision drift allowance is added.