Interactive Component Authoring

Interactive component authoring cycle

This is the repository's agreed editing rule for realistic assemblies. The simulator is an interactive workbench, not a batch USDA generator. Keep the headful production session open, edit one component at a time, inspect what the user can see, and stop at every checkpoint that can change the design.

Use this skill with edit-usd-assembly for the Editor lifecycle and assembly-quality for dimensions, frames, collision and visual gates. For a new reusable asset also read author-usd-component.

For a mission or operations-facing model, read the tailored mission and engineering quality gates before choosing component boundaries or fidelity. It adds ConOps, interface, fault, verification/validation, deterministic replay, and configuration baseline checks without introducing a vehicle-specific workflow.

The mandatory cycle

Keep one production Editor session open for the assembly and use Editor Perspective for every authoring checkpoint. The unit of progress is one component task, not a vehicle-wide script. After each task, stop and inspect the live projection; do not begin the next component until the typed readback and the Rhai gate agree with what is visible. This is the short interactive loop the agent must run itself, even when the user is not watching the terminal:

For each component, in order:

discover the exact USD document, preview, view, edit target and generation
  -> define the component contract and its local datum in SI metres
  -> build one pure Rhai plan using typed USD operations
  -> review and commit that one component change
  -> wait for projection_ready and the matching projected generation
  -> query the authored/composed prims, bounds, relationships and schemas
  -> inspect the focused Editor view and capture a project-local screenshot
  -> run the component's source-backed Rhai requirement gate
  -> show the checkpoint / collect feedback before the next component
  -> save only after the visual and typed gates agree

If a component is wrong, change only that component (or its explicit mount contract), re-project it in the same session, and repeat the checkpoint. Do not accumulate several speculative edits and then ask for a final review. When a task genuinely needs multiple dependent parts, make the dependency boundary explicit (for example, a wheel and its strut), run the local gate, then continue with the next separately named task.

Do not queue a bus, tanks, legs, engines, ramps and panels into one unobserved call. A component task may contain the minimum atomic operations needed for that component (for example a wheel plus its strut and mount), but it must produce its own projection, typed evidence and Rhai verdict. Then run an assembly integration gate that checks placement, symmetry, clearances, references, joints and cross-component wiring; an isolated component pass does not prove its mounting.

Unified editing substrate and format adapters

All editable artifacts use the same lower contract in lunco-doc and lunco-doc-bevy: a stable DocumentId, monotonically increasing generation, typed reversible DocumentOp, an atomic grouped-apply boundary, optimistic parent-generation checking, journal provenance, lifecycle notifications, and generic undo/redo/save/fork/close verbs. This substrate is the source of shared Editor behaviour; a format must not grow a private history stack, active-tab fallback, or second document identity.

Each format adapter implements only what is format-specific:

The dynamic tool boundary is assets/scripting/tools/*.rhai. A tool is discoverable and hot-reloadable by name; it may call only the public cmd / query surface and reusable prelude helpers. New format support should add a small adapter plus a Rhai facade, not a vehicle-specific Rust builder or a copy of the USD/Modelica history machinery. authoring_session is the common facade for capability discovery, dry planning, grouped apply, checkpoint, undo and redo.

Every adapter must expose the same interaction invariants:

1. Inspect first: return document identity, origin, edit target (when applicable), generation/source revision, dirty/read-only state and diagnostics.
2. Plan before mutate: validate the complete operation list in Rhai and return a deterministic summary. A dry plan never calls cmd.
3. One intent, one group: submit the reviewed list through the owner's atomic grouped operation. The owner rejects stale generations, invalid ranges/paths, read-only origins and unsupported schemas with a structured error.
4. Verify the owner projection: wait for the matching generation and use the format's typed readback (USD composed stage, Modelica parse/compile, SysML semantic snapshot). A screenshot is an additional visual checkpoint, never the source of truth.
5. Recover explicitly: undo/redo target the same document id; save is a separate approval. There is no implicit active document, alternate writer, silent retry, or fallback format.

For Editor UX, keep a single session visible while this cycle runs. The user should see the dry operation count and affected identities, then one coherent change, the projection result, diagnostics and the undo affordance. Selection, camera and view state are presentation state and must survive a source edit; they are never encoded as an extra authored operation.

Source and requirements gate before geometry

Before opening an Editor document for a component, perform a short written analysis and keep it next to the Twin source. The analysis is part of the component contract, not an informal design note. For every component record:

1. the public/reference source (URL, paper, drawing, supplied image, or an explicitly labelled Twin study assumption), access date, and the exact fact extracted from it;
2. the subcomponents and ownership boundary (for example ramp deck, hinge, actuator, latch; or wheel, hub, knuckle, arm and strut), including which parts remain inside this file and which become detached referenced assets;
3. the local Y-up/SI-metre frame, mount datum/socket, handedness, envelope and all dimensional parameters needed to build it;
4. the required USD topology/types, standard schemas, collision and mass/inertia owner, material/purpose policy, and any articulation/limit;
5. a source-backed SysML requirement for each observable fact, with a source, rationale, units, and verification relationship; and
6. the Rhai checks that will prove the fact from composed USD (including missing-source, wrong-type, wrong-unit, boundary and reference-identity cases).

Use a separate requirements/<component>_requirements.sysml and scenarios/tests/<component>_requirements.rhai for every independently reusable or articulated component. The SysML file is the single source of truth for names, dimensions, limits and provenance; the Rhai test loads it via sysml_requirements::source() and must not repeat numeric literals. Keep the test fixture and component asset detached from the parent assembly so either can be opened and verified independently. The parent assembly gets a separate integration requirement file that checks only instance placement, symmetry, clearance, joints, and cross-component wiring.

Do not start detailed geometry when the source or datum is unresolved. Record the uncertainty as a failing requirement or an explicitly named study assumption and stop at that component checkpoint; do not silently invent a fallback dimension. This produces an auditable chain:

source evidence -> SysML requirement -> Rhai composed-stage check
                 -> detached USD component -> assembly integration check

Five-phase delivery workflow

Apply this order to every mission, vehicle, habitat, payload, or other model; it is not tied to a particular Twin:

1. Analyse the implementation seam. Identify what belongs in the Twin's USD files (identity, topology, geometry, references and transforms), what belongs in Rhai (scenario policy, requirement observation and reports), what belongs in Modelica (continuous equations and parameters), and what generic capability is genuinely missing from Rust (typed document operation, projection, physics or solver seam). Do not put Twin names or requirements into simulation-core Rust.
2. Split by ownership. Decompose the root into detached, independently openable components. A component may contain its local subcomponents when they share one datum/body and no independent lifecycle; otherwise give the subcomponent its own USD asset, SysML contract and Rhai gate. The assembly composes references and owns placement, joints and cross-component links.
3. Find and record specification. Gather public drawings, papers, product pages, supplied images or measured study assumptions. For each requirement record source URI/title, access date, extracted fact, rationale for including it, confidence/status (reference, derived, or study-assumption), and the SI-unit conversion. Unresolved facts are visible failing requirements, never silent defaults.
4. Build through the existing tools. Author or edit one component in the headful Editor with assembly_edit, assembly_builder, component and measurement facades. Use a pure Rhai plan and typed USD operations; let the document owner maintain ordered transforms, schemas and composition. If a needed standard operation is absent, stop with a loud Rust capability-gap report and add only the smallest generic feature.
5. Verify and iterate. Run the component's source-backed Rhai gate, then the parent assembly gate, then the whole mission/vehicle suite. Check topology, dimensions, units, frames, references, joints, collision/mass, limits, determinism and visual evidence. Repeat the one-component cycle for every failing checkpoint until all required verdicts are green; only then save/publish and record the exact evidence.

The required handoff is therefore an auditable set of artifacts, not just a final screenshot: an analysis/source record, one SysML contract and Rhai gate per detached component, the USD component files, an assembly contract/gate, and a whole-system test report.