Luncosim Architecture

LunCoSim architecture

Use this skill before changing a reusable engine feature. Keep the authored system declarative and composable, and make each concern live in its native representation:

Before calling an architectural capability missing or impossible, use capability-discovery. Search the relevant skills and architecture docs, identify the standard or project owner, inspect registrations and callers, check maintained dependencies, and verify the production/API surface when relevant. Classify the result as found, implemented-but-unwired, present on another branch/version, not found in the searched scope, or externally blocked. Do not create a second owner, fallback, or compatibility shim because the first search was incomplete.

For cross-domain execution, read 62-deterministic-runtime-and-async-boundaries.md. Keep parsing, source resolution, and immutable preparation off the UI/fixed schedule when inputs can be captured by revision. Admit results only at an owner boundary in stable identity order. Keep live-world hooks and physics inside their deterministic schedule. The required Rhai USD composition policy decides incomplete initial stage and newly mounted reference closures before their respective admission and projection boundaries. A Rhai scenario that depends on Modelica ports or events declares the participating entity ids in simulation_dependencies(me, ctx), where ctx is the validated scenario parameter map. The hook returns a map with modelica_entities: [ids], entity_reads: [ids], entity_writes: [ids], query_reads: ["PublicQueryName"], and required_inputs: [#{ owner, identity }]. All five arrays are required even when empty. The owner resolves all declared ids once per source/parameter revision. modelica_entities ids must identify live Modelica participants and grant both directions of access. Directional read/write ids may identify any live entity; a Modelica entity in either set also joins the shared causal barrier. Unresolved ids fail that source revision with a visible diagnostic. Every simulation-clock Modelica port access must be covered by the calling scenario's own plan, including get, port, and query("ReadPorts", #{ api_id, port_names }); aggregate barrier membership from USD wiring or another scenario does not authorize the read or write. The owner enforces this at the port, query, targeted-command, and event-delivery boundaries. Generic reflected reads and direct mutations also require the matching entity_reads or entity_writes declaration. After a typed simulation command materializes an entity whose id was not available during plan preparation, track_entity_read(id) or track_entity_write(id) adds the directional access in serialized simulation order before the entity is used. Tracked Modelica entities join the same barrier when they enter the current Modelica projection. Entity-targeted API query providers report their live target ids through simulation_entity_reads; the scripting bridge checks them against the scenario's read plan before execution. Broad spatial/world queries use an explicit coarse declaration by public provider name in query_reads. Mounted-scene USD queries without doc_id use the active committed Twin generation. Unknown query providers default to the broad declared scope, and broad queries cannot run while simulation_dependencies is resolving. Required input keys refer to producer namespaces registered in the generic SimulationDependencyStates resource. The scenario holds its existing ScriptPreparation key until every required input is Ready; it retries only after an owner-published state revision, and the visible wait reason names the input. A missing producer is a terminal diagnostic; a producer's Failed state reports its errors. Omitting the hook declares no Rhai dependencies. The plan runs before mutable top-level initialization, so derive it from me, scenario parameters, and read-only world queries. Top-level initialization runs in its own Initialization phase after the plan commits. Dependency planning may resolve identities but cannot access live ports, issue commands, mutate the world, or emit events. Invalid or unresolved ids fail that source revision with a diagnostic. Unbarriered port access and Modelica event delivery fail visibly. Connected Modelica event edges are sampled only while the simulation clock advances, after SimTickSet and before Rhai; this gives an initially active output its producer tick after scenario readiness. USD simulation projection uses stable logical stage source, optional instance-root path, and authored prim path for bounded admission, topology-preparation order, and dynamic-body promotion; missing or ambiguous identities fault, remain queued, or stay kinematic. Physics operations that can accumulate into shared bodies use PhysicsOrderKey from the stable logical stage source, instance root, and authored prim path. Joint solving, motor warm-start, custom prismatic correction, raycast and jointed tire forces, and raycast mass-property folds consume stable key order. The production multi_rover_stress Rhai gate selects a profile from typed scene-test parameters and compares only the requested reference row at each sample. Rust loads the portable JSON at the --determinism-reference PATH process boundary and exposes typed values through the existing Rhai query bridge. Rhai owns profile matching and exact comparison (numeric_tolerance=0) for six physics checkpoints, selected Modelica and articulated checkpoints, and the explicit final physics, Modelica, and articulated state. The test keeps only checkpoint tick numbers and the first mismatch; it also verifies Rhai rejects a deliberately altered physics row and does not emit or retain a trace bundle. The Bash and PowerShell matrices in scripts/test-deterministic-physics-profiles.sh and scripts/test-deterministic-physics-profiles.ps1 invoke regular production luncosim test processes and trust their exit status. They leave --tick-hz unset, so the default fixed step is 60 Hz; the runner advances the manual clock without wall-time pacing. This remains fixture-specific evidence. Do not claim whole-simulation replay determinism while the remaining reviewed gaps are open.

Reflected commands sent through ApiCommandEvent retain whether they came from an API transport or a Rhai evaluation; generated CommandOccurred facts carry that origin. The workbench uses PanelCtx::trigger_command to carry an explicit local-user SessionId across deferred UI dispatch; the port inspector therefore enters fixed-tick input admission. Direct typed Bevy triggers without an explicit origin remain unclassified, and the occurrence fact still lacks command parameters, target, scene generation, effective tick, and per-tick input order. Rhai scenario origins carry their stable actor id and source execution sequence. SimulateIntentEdge preserves the complete origin through its typed semantic edge into the bounded CausalTrace query; Rhai records include owner route, phase, generation, sequence, and actor id. API, application-Rhai, and direct typed discrete edges receive a committed scene generation, next SimTick, and per-tick sequence, then reach the event bus from the fixed-step owner. Simulation-clock Rhai edges remain derived behavior and do not receive this external-input stamp. The queue is bounded to 4,096 pending records and clears on scene teardown; the trace is not durable replay storage. External held SimulateIntent changes share the bounded queue and per-tick order with edges. API, direct typed, and actorless Rhai producers provide a stable nonzero producer_id; Twin Rhai retains its route and stable actor identity. Held acknowledgements, telemetry, CausalTrace, and session records retain producer identity. drive_from_bindings captures physical ActionState<UserIntent> into a by-value PhysicalIntentFrame semantic snapshot. Admission requires the local input SessionId, target GlobalEntityId, and committed scene generation. The fixed-step owner stamps the frame with those identities, the current SimTick, and a sequence from the shared lunco-control-core::SimulationInputOrderAllocator before controller translation. The allocator resets on scene teardown so producers share one per-tick order space. Admitted external semantic payloads wait in lunco-core-session::PendingSessionInputs; core-session clears that queue on scene teardown. Its fixed-step coordinator validates and captures due records, then publishes typed commit events in shared sequence order while simulation time is running; a pause leaves inputs queued for the next running tick. The controller applies semantic payloads before physical input sampling. Raw-file runtime spawns also enter this commit boundary; the scene-command owner checks the current frame and catalog and inserts the reserved root identity before identity admission. Physical frames remain sampled at their consuming fixed tick through the same per-tick allocator. Missing facts or duplicate target/session order keys hold input with a structured runtime error; ordering does not fall back to Bevy Entity bits. An active SessionInputStream captures sorted canonical intent ids, admitted controls, lifecycle input-hold releases, and raw-file spawn records. ControlAuthorityChanged queues ReleaseControlInputs for the next fixed tick. At its ordered commit, the co-simulation owner clears controller-owned port holds and the controller clears held semantic intents; authored program setpoints, endpoint values, and physics state remain intact. The release writes no stop value. Twin policy owns any stop setpoint and issues explicit named SetPorts writes. Capture retains the ordered lifecycle record when active. Missing target, generation, tick, or order facts produce a runtime error and leave existing holds intact. Spawn records retain producer, correlation, stable scene-root and active-frame identities, original f64 pose, admission stamp, and reserved root id; acknowledgements expose that stamp. Document-backed SpawnEntity still authors only ApplyUsdOps into the Twin journal. Capture remains bounded and in-memory; baseline manifests, playback, and other typed commands remain open. The persistent canonical WorldGrid has deterministic content provenance, so the default active physics frame also has a stable GlobalEntityId.

Scenario actor compile submission, completion commit, and hook execution use the source-owned GlobalEntityId component directly; the Update-synchronized API lookup index is not an ordering source. A local-only host without that component uses its Bevy entity key only within the current World and has no cross-session replay identity. Author observable multi-actor ordering checks in Rhai scene tests; reserve Rust tests for the generic ordering and async commit mechanisms.

For file-backed documents, use PreparedFileBacked with the shared DocumentRegistry::open_prepared_file path when source parsing moves to a worker. The registry remains authoritative for path identity, dirty-document preservation, and lifecycle events. Owners fence results against the exact source/document revision before committing them. The default USD Twin scene uses this path for native USDA parse and persistent-source serialization; runtime sidecar restore and the browser worker transport remain separate open boundaries.

Twin teardown releases domain documents and browser preparations before the replacement is admitted. Reopening keeps logical source identity but receives a fresh load authority. Resolve authored dependencies through lunco-assets-core::asset_path::load_asset_path with the admitted live origin; retired origins fail before rebinding, and origin-free requests keep exact transport authority. Background file snapshots resolve logical source names and fence publication by scope and mount revision. See 61-scene-lifecycle-and-teardown.md.

Lifecycle work that changes authoritative scene state participates in lunco-core-runtime::SimulationProgress. Acquire with a typed owner/operation key, carry that identity through async preparation, and release it only after the owning terminal result has been committed. Scene load/restart/clear use SceneTransitionId; same-path transitions still have distinct identities. The coordinator advances the shared scene generation only for the matching successful transition and emits SceneTransitionCommitted. Scenario and other Twin-scoped cycle owners read that committed generation; do not maintain a subsystem-local scene counter or arm lifecycle work from a stale completion. Lifecycle hooks receive a discrete owner context keyed to the exact transition. For example, scene.time.select runs as Twin/Lifecycle/Preparation with no elapsed clock, and its typed result carries the same SceneTransitionId through application. The time owner ignores stale results and terminal edges after a replacement begins. One-shot policy inspection uses Application/Repl/Evaluation. Keep participant readiness and PhysicsHolds in their owners: they control local/world physics admission, while SimulationProgress controls whether the shared causal tick may advance. UsdSceneRuntimePlugin installs this shared resource when selected and holds active reference spawns on the mounted primary scene through closure preparation and live ECS projection. Preview and additive mounts retain diagnostics without pausing or faulting the primary simulation. A terminal primary reference failure retains its exact hold and publishes a path diagnostic plus RuntimeFault until scene teardown; inactive or removed, nonfaulted operations release their own keys. Surface the active wait reason through the existing status bus. Async data that changes authoritative physics, including a mounted DEM download/build, also holds an exact terrain entity key through the committed collider/oracle result; on web the hold spans the coarse preview and full worker result. The DEM bridge and readiness scan run in PreUpdate before SimulationAdmissionSet, including while a Twin manifest scan is pending, so the first eligible fixed tick cannot precede terrain admission. UI and presentation schedules remain live. Persistent edits to the mounted primary USD document hold one coalesced UsdDocumentProjection key from the observed registry revision through the matching ECS projection commit; disposable view-layer edits do not hold world time when their typed operation suffix is available; an unavailable suffix is conservatively treated as causal. Change detection admits UI/command edits in the SimulationProgressAdmissionSet after entity indexing and before the PreUpdate simulation-admission boundary, and admits edits issued inside a fixed Rhai/event pass in that lane in FixedLast. The fixed runner completes the current cycle, then preserves its remaining overstep until the projected revision is committed. Do not poll document contents on steady frames or release the hold from a stage-only cursor before ECS projection completes. Physics readiness then admits bodies and joints on fixed steps. An active USD Modelica participant remains readiness-held through its first successful communication point; a compiled, intentionally paused model is ready without being stepped. Keep that participant readiness separate from the shared SimulationProgress lifecycle gate. First-compile intent is admitted by request_modelica_compiles in the lifecycle cycle while solver stepping stays in FixedUpdate, so compilation can be requested while virtual simulation time is held. The Modelica execution owner consumes typed CompileRequested intent, validates its pinned document runtime lifetime, and owns same-owner source gathering and worker dispatch; the UI command only chooses the class and publishes intent. On native, source-root installation, compile requests, Reset, parameter updates, and cache-invalidating Step auto-init share one single-owner Rumoca actor FIFO. Results return asynchronously and commit in submission order; actor requests and solve preparations use bounded admission. A Step that requires a rebuild resumes only after the matching session and library generation commit. Compile results must match both worker session and captured document generation. A result for an edited source revision is discarded, and an active model keeps its compile-run intent until a current result commits. The execution owner reconciles active causal models into SimulationProgress before SimulationAdmissionSet and releases each exact entity key only after the matching compile result has been committed. Intentionally paused and noncausal models do not hold world time. Their first normal co-simulation step uses the per-step barrier after activation. The root USD loader composes the available dependency closure before publishing the stage asset, and scene admission ends after structural projection. CPU mesh construction stays on the presentation path. Keep owner-specific clock gates separate; production acceptance must still prove that the first authoritative fixed tick observes each dependency declared by the scene and scenario, independent of worker completion order.

For engineering requirements, keep the same split at the numerical boundary: SysML owns typed intent, units, normative tolerances, and requirement/ verification identity; USD owns realized geometry and standard scene facts; Modelica/Rumoca owns equations and continuous state; Rhai owns the selected mechanical relation, orchestration, and evidence; Rust owns only reusable, hot, type-safe f64 mechanisms. The authored assets/scripting/tools/mechanical_relations.rhai library is the extension point for CAD-like predicates such as distance, coincidence, parallelism, under/clearance, mirroring, and symmetry. Do not grow a Rust registry of relation names or product-specific checks.

Use the existing Rhai standard math surface for ordinary scalar operations and the native Rust bridge for f64 vector validity, dot/cross, clamped cosine, angle, and native component access. Keep native values in hot loops; arrays are only explicit interchange boundaries. Use typed predicates (f64_only, array_is, map_is, string_is, vec3_is_native) instead of string-based runtime type protocols. Numerical settings are explicit per dimension and are resolved once per report/solve; they do not replace a source-owned SysML tolerance or become a global epsilon.

For Avian-backed physics, keep one numeric admission contract at lunco-physics::avian_backend. The BigSpace bridge owns lifecycle admission of f64 poses and collider support geometry before the Avian step, GridSpatialQuery reuses the converted-ray predicate, and USD projection reuses shape/AABB and leaf structure predicates before ECS insertion. Convex colliders are checked by their actual support points; composite or non-convex shapes use the conservative AABB boundary. A failed live invariant raises the shared scene-scoped runtime fault and gates the remaining nested physics phases. Do not turn these checks into per-call query fallbacks or lint-only warnings.

Rhai task callback contract

Task leaves accept anonymous closures (|me| ...) or named script callbacks (Fn("name"), declared fn name(me)). me is the host entity id; both forms receive persistent state as the driver-bound this. The native task driver owns progression and state transfer. Rhai map parameters are value/copy-on-write values: a helper that assigns a state field must return the updated map, and the lifecycle callback must assign it back to this. Do not rely on helper side effects to persist task state.

Plugin and crate layering

Use a domain CorePlugin for headless-safe state, lifecycle, commands, and runtime mechanisms, then add a separate UI plugin only for panels and visual presentation. Do not create a UI plugin merely to host API queries. If a provider belongs to a core domain but importing the API crate would create a dependency cycle, put the provider in a small *-api adapter crate and have each API-capable composition root install it explicitly. Keep the data/core crate independent of transport and presentation layers.

For dynamic providers, keep lunco-hooks as the single reflected contract and invocation owner. HookInvocation carries the typed runtime context with the validated values. lunco-hooks-plugin-api owns the stable edition-2024 ABI v2 and typed invocation wire helpers; lunco-hooks-native owns libloading, unsafe admission, callback limits, and exact-registration teardown. Enable that path only from an application composition feature. A Twin must explicitly approve a provider with a Twin-relative [[native_plugins]] manifest entry. Reject rooted, volume-relative, traversal, and alternate-stream paths; resolve through the asset owner's canonical containment check before loading. USD and Rhai source do not load shared libraries. Native code is trusted process code, so untrusted bundles require deployment-level signature and isolation controls.

A provider may implement only an existing reflected, installable hook and must return typed data or a validated action plan. It must not mutate ECS/USD or add a second domain registry. The owner invokes it through lunco_hooks::invoke with a typed HookInvocation: cycle-owned callers supply their runtime context, while discrete boundaries explicitly use an unclassified context. The owner validates the result and reports a fault or unconfigured state according to the hook contract. Policy manifests may mark an optional feature-owned hook with skip_when_hook_unavailable; the runtime reports that capability in policy_status().unavailable, while compile and activation failures remain in failed. Put an eventual expensive terrain provider at the consumed lunco-terrain-bake kernel boundary; keep lunco-terrain-core projection-free and leave lunco-terrain-surface as the runtime projection owner. See native-hook-providers.md.

Keep stateful per-entity Rhai scenarios on their owning Simulation lane. For a stateless Rhai decision at another cadence, prefer an existing owner-invoked hook with typed facts and context over adding more lifecycle callbacks to the scenario runtime. Cross-cycle results return as typed owner actions; a scenario this map never moves between cycles.

Keep the workbench split at the dependency boundary: lunco-workbench-core owns renderer-independent panel/menu/perspective/registration contracts, tab navigation, source-view commands, scene display state, pending tab-close state, and the published WorkbenchSnapshot; lunco-workbench-widgets owns shell-independent egui controls; lunco-workbench owns egui_dock, bevy_egui, viewport rendering, persistence, source editing, and command observers; and lunco-workbench-guided-ui owns the optional Rhai-driven HUD, spotlight, coach-mark, and guided-recovery surfaces; and lunco-workbench-browser owns the optional Twin/Files panels, browser state, and built-in filesystem/library sections without depending on the concrete shell. Rename payloads belong to lunco-doc-bevy or lunco-workspace according to the identity they address; the shell retains only picker/execution observers. Domain UI crates implement contracts from the core crate, read layout facts from the snapshot, and depend on the concrete shell only when they use those presentation services. Do not expose or consume the shell's private WorkbenchLayout outside that crate.

Keep application-edge presentation separate from the reusable shell: lunco-luncosim-presentation owns the final status/environment, terrain-horizon, USD camera/light, capture, and scene-presentation bridges, while lunco-luncosim-ui owns window/plugin composition and installs that package at the boundary. Native updater startup and its rendered surface belong to the optional lunco-updater package, not to the ordinary UI closure. Celestial body projection and cadence belong to lunco-celestial-spatial; ordinary moving scene objects use standard USD timeSamples through lunco-usd-bevy-animation. Do not create a mission-only trajectory component or clock when composed USD animation expresses the motion. Celestial state uses the one lunco-time::CelestialTime sample, an affine child of WorldTime. It drives ephemerides, body rotation, solar irradiance, lighting, shadows, geometry queries, and target positions consumed by the generic EnvironmentProbe direction resolver. SunState contains irradiance; it is not a parallel direction source. A rate up to 100,000× leaves Avian and Modelica at their ordinary fixed-step cadence. From lunar ground, Earth stays near one sky position because the Moon is tidally locked; its axial spin still advances the day/night pattern. BigSpace propagates both the changed Earth grid pose and rotation to GlobalTransform; one cadence gate commits the CelestialTime sample it read. Static authored-light rays are selected only after the active composed root's celestial projection has classified its source ownership. A celestial root owns the finite body target exclusively; any static ray seeded before classification must be withdrawn before probe resolution. The celestial hierarchy must not wait on interactive input bindings: invalid bindings may withhold the optional observer camera, but must not suppress the finite targets consumed by physics and Modelica.

Runtime scopes, cycles, and publication boundaries

Use the shared lunco_runtime_context::RuntimeScope and lunco_core::RuntimeCycleSet vocabulary when placing a cross-cutting system. Core, Application, and Twin describe ownership; Lifecycle, Simulation, Interaction, Command, Repl, Telemetry, Ui, Presentation, and Visualization describe cadence. These are schedule labels and typed route metadata, not a new global event bus. Twin-owned resources and completions must carry their mount generation and be retired at Twin teardown.

Cycle labels do not create independent clocks, CPU isolation, or execution cadence. Rust plugin composition decides which capabilities a host installs; Bevy's owning schedules provide the actual execution boundary. A typed RuntimeExecutionContext carries the current owner route, cycle, phase, clock sample, logical sequence, and optional event producer stamp into synchronous Rhai calls. Scenario hooks and one-shot REPL/tool calls use their owning contexts: RunRhai runs as Application/Repl, while typed UI tool callbacks run as Application/Ui after picking in PreUpdate and before fixed simulation. execution_context() exposes a read-only Rhai map. Generic hook calls carry HookInvocation; nested invoke_hook forwards its active context, and an isolated Rhai hook reads it from the immutable runtime_context map. The shared hook registry rejects a clock that does not belong to its cycle, missing or invalid clock samples, and non-zero Core/Application generations before invoking either Rhai or native policy. twin.lifecycle uses the mounted Twin's TwinId as its Twin/Lifecycle generation, with explicit Start, Event, or Stop phase and no elapsed clock; policy_status().lifecycle.runtime_context exposes the exact stamp. Rust call sites without a classified owner use the explicit unclassified hook entry point. The physics escape policy is a scheduled core simulation hook and receives its Behavior context from SimTick and Time<Fixed>; its authored policy rejects off-cycle calls. The scheduled readiness.action policy uses Core/Simulation/Behavior with Time<Fixed> and the latest SimTick, and its authored policy rejects calls from other cycles. sim_tick(), dt(), and elapsed_seconds() reject calls outside the simulation cycle as invocation errors, while missing mandatory simulation clock resources remain runtime faults. An unclassified invocation has no route; Rhai exposes its scope, cycle, and generation as unit instead of inventing an owner. Add a separate schedule driver only when a cycle needs independent cadence or overload semantics, and keep expensive calculations off the UI/physics-critical thread.

Native immutable preparation uses lunco_core_runtime::AsyncWorkAdmission; do not add another per-crate priority queue. Each request carries its scope generation, stable owner identity, source revision, and operation id. Priority selects which queued job starts; the owner still validates and commits its typed result at its own boundary. WebAssembly's Bevy async-compute pool runs cooperatively on the browser main thread, so expensive web work needs an explicit worker transport rather than this native dispatcher. Native terrain cover analysis and streamed tile-mesh bakes share this admission. Tile bakes use Interactive priority and a stable owner-selected nearest-first rank; the terrain owner fences completions by operation key and publishes meshes in stable coordinate order under its frame budget. Surface changes and owner removal withdraw queued work, and already-running stale results are discarded. Keep the browser tile-cache path explicit until Web Worker transport is available. Serialize each Modelica step's input assignments in variable-name order; never let hash-map iteration choose a worker command's observable order. File-backed Rhai source assets are parsed and const-folded by the asynchronous asset loader, which publishes their canonical id, exact text, AST, and literal import dependencies together. Activation owners commit the complete loaded dependency graph before binding or starting a source; Bevy can report graph readiness before its Added messages are consumed. Startup/Twin tools and the prelude reuse that AST; scenario workers reuse it only when the source bytes match, and parse inline roots or uncommitted sources inside shared admission. Do not compile loaded tool or prelude source synchronously during registration. The asset publisher retains each loaded AssetId's canonical URI and retires it on AssetEvent::Removed, because AssetServer::get_path may fail after the last handle is released. Ignore the earlier Unused edge, and prevent a stale asset removal from deleting a replacement source with the same URI. Twin SysML analysis follows the same boundary: twin.lifecycle selects the checked manifest source set, PrepareTwinSysmlAnalysis loads source assets and prepares one immutable snapshot through shared admission, and runtime twin:// queries read only the current Twin-id/root/operation result. Pending, failed, and unprepared snapshots remain visible. This read-only active-Twin work uses Interactive priority and never holds SimulationProgress; a scenario that requires SysML facts declares the typed owner key in its dependency plan. Open SysML documents use the same bounded Interactive admission. Lifecycle events capture immutable source/origin facts, and SysmlDocumentAnalyses commits only for the exact current document generation and origin URI. InspectSysmlDocument returns analysis_state as pending, ready, or failed; pending diagnostics and error fields are null. Rhai editor verification must return a retryable pending result and must not call it clean. These editor analyses do not hold simulation progress. Browser worker transport is explicit and remains unsupported by this native dispatcher. The Twin analysis producer registers sysml.twin-analysis and publishes each mounted Twin's state under its exact name. A scenario that needs those facts lists #{ owner: "sysml.twin-analysis", identity: twin_name } in required_inputs; only that scenario's activation hold waits for the async analysis. The analysis worker itself remains read-only and never acquires a world-time hold. Telemetry samples are captured with the fixed tick, then delivered through the plugin-owned bounded Telemetry cycle. Never run subscription, retention, or logging observers inline with fixed physics; report queue loss through the telemetry status query and keep simulation progress independent. The GUI installs TerrainSurfaceVisualizationPlugin; server and scene-test compositions keep terrain physics/query support but omit camera-driven LOD, visual-map baking, and overlays entirely. A system hidden behind a server-mode run_if still exists in that schedule and is not equivalent to omitting it. Application builders install the selected capabilities automatically; authors should not assemble Bevy schedules by hand. Rhai currently declares peer-role selection through @peer host|client|both, with simulation as its supported timing. An unknown execution target, unsupported timing, or unknown metadata directive disables only that scenario and publishes one document error for its source generation instead of breaking the host, defaulting to host, or guessing a clock. Cycle and clock selection come from the Rust owner, not a script directive. A callback error remains visible and local to its owner; required authoritative hooks hold/fault their owner. Never panic or silently report success for a failed hook.

The initial camera policy receives Application/Presentation/Preparation with the Time<Real> presentation clock. Its RuntimeCycleSet::Presentation labels are ordering metadata inside Update; they do not give UI or visual LOD an independent cadence. The runtime UI recording selector receives Application/Ui/Preparation with the Application clock in its PostUpdate owner chain; it runs only when its revisions change, not as a separate cadence. The authored runtime-surface visibility/property policies receive typed Application/Ui/Preparation context from exposure publication; camera-status properties receive Application/Presentation/Initialization or Application/Presentation/Event from the camera-status publisher. Add a policy guard and verify both the scheduled owner context and an off-cycle call when assigning context to another hook. The route_lifecycle production gate checks ReadExposures for an authored program-browser surface after metadata admission.

The rendering-quality catalog receives Application/Presentation/Initialization on startup and Application/Presentation/Preparation for stale-policy refreshes, both using Time<Real>. The render shadow-warning policy receives Presentation Preparation context from its PostUpdate owner when its configuration changes. The Presentation cycle set remains ordering metadata and does not add a separate cadence.

The event-driven usd.component_refresh owner supplies Twin/Lifecycle/Preparation with the active or committed generation for a mounted-Twin document, and Application/Lifecycle/Preparation for a preview- only document. The owner requires a generation for a mounted Twin; a missing generation rejects that policy-controlled refresh visibly.

Cycle labels identify ordering and ownership; they do not imply that every owner already publishes timing and queue metrics. Expose bounded aggregates at task boundaries where measurements are needed, then use them to target a Tracy capture and measure frame responsiveness in a separate unprofiled run. Do not feed a per-frame diagnostics firehose through the simulation telemetry sampler. CosimStatus exposes per-session Modelica solver-step duration, dispatch-to- response latency, and the native worker's pending-task count at step start. Pass include_values: false for a bounded fleet view without input/output maps or verbose model/error details; status, counts, and timing remain available. Rhai profilers can pass include_entities: false to read aggregate worker metrics without constructing a string-bearing row for every participant. Response latency includes queueing, transport, and owner response handling; it is not a pure queue-wait measurement. The browser worker does not expose its internal queue depth.

Keep telemetry's two lanes distinct: authoritative events used by Rhai retain their producer tick and deterministic delivery order; continuous samples are bounded observations of committed state. The fixed sample boundary captures due channels into a small typed record. A cached channel plan still requires a fixed-path walk and live port reads; its samples then go through a bounded post-simulation cycle. Logging, subscriber fan-out, formatting, serialization, persistence, and UI plot decimation run outside the physics transaction. Reducing fixed-path sampling work and measuring its effect on throughput remain open owner-level work, not a completed guarantee.

Commands and one-shot Rhai/REPL evaluations have independent application clocks. Record command cadence from the shared CommandOccurred publication and REPL cadence from actual drain_world_scripts evaluation. Both use the wall clock, never simulation time; a queued script is not counted as evaluated until the exclusive REPL owner runs it. Publish their sequence and timing through ApplicationCadence/application-cadence so consumers do not add their own timers or infer cadence from render frames.

World-bound one-shot Rhai requests remain serial because their verbs read and mutate the live World. The REPL owns a bounded FIFO (64 pending requests by default), evaluates one request per Update, and applies a 100,000-operation ceiling per invocation. Queue overflow is a terminal command error. Keep scenario and hook execution in their owning clocks; do not parallelize callbacks that still use live-world access.

Publish each fact through its one domain boundary before adding a consumer: scalar co-simulation endpoints use PortRegistry; presentation-ready values use EngineExposures; lifecycle occurrences use typed events or revisioned resources. Status bars, authored HUDs, telemetry adapters, API readers, and recorders consume those publications. They must not independently scan engine diagnostics, query a physics owner, or introduce a widget-specific registry. The fixed-step and rollback co-simulation paths share one propagation function and compiled cache; transform propagation remains a separate spatial owner. Rollback is an instantaneous replay cycle over recorded inputs, so systems in RollbackReplay must not be gated by the live virtual clock's paused/running condition. Keep its actuation ordering aligned with the fixed path and test the real replay schedule while Time<Virtual> is paused. This body prediction replay does not reconstruct whole-session commands, Rhai state, or Modelica state; do not claim whole-simulation replay determinism from it.

For a ShaderLook with vertex_shader, treat the fragment and vertex sources as one linked material contract: both stages read the same @binding(0) uniform block, so their Material fields, order, and WGSL types must agree. The fragment schema is the packed layout; do not invent a second vertex schema or silently select a replacement shader. Validate the requested stage positively: sourceAsset needs @fragment and vertex_shader needs @vertex; a combined WGSL module is valid for either role. A missing or invalid stage is a structured runtime diagnostic and an unbound material. Rust must not install a StandardMaterial, neutral shader, or another guessed source as recovery. If a scenario needs recovery, make it an explicit Rhai policy that can be replaced or disabled without rebuilding the renderer. Add a cross-file ABI test when maintaining a multi-stage shader pair. See shader-layers-and-params.md.

Treat an illumination-bearing grayscale orthophoto as measured imagery, not intrinsic reflectance. The native lunco-assets-processing kind = "albedo" pipeline removes its low-frequency illumination field, anchors local detail at a neutral material base, and sRGB-encodes the resulting linear colour for the 8-bit PNG contract. The texture loader decodes that material back to linear; terrain shaders use it directly and have no orthophoto compensation function. kind = "map" remains an analysis/display contrast map and must not be bound directly as inputs:albedo_map. When weight_albedo is authored, it owns terrain colour variation; scale procedural dust/mottle by 1 - weight_albedo, while keeping relief normals, roughness, ambient occlusion, and photometry independent. Heavy raster math stays in Rust; Rhai assembly policy selects and authors the standard USD material inputs. The packed surface map's G channel is ambient occlusion: route it through the shared terrain_surface_occlusion helper into Bevy's PbrInput.diffuse_occlusion, never into base albedo. AO is indirect-light visibility; multiplying it into albedo creates broad false colour patches and darkens direct sunlight. The render-side ShaderLook binder owns event-driven preparation of filterable authored RGBA8 maps: it deduplicates off-thread mip generation by image asset version, filters colour in linear light, averages scalar maps linearly, renormalizes normal vectors, and then enables trilinear/anisotropic sampling. Do not skip a zero-weight map at load time: authored weights are live inputs, while mip preparation is the separate renderer-owned image lifecycle.

Project-owned persistence policy belongs to the active Twin manifest's generic settings boundary. A domain may define one namespaced scalar key and expose it through the existing SetTwinSetting path; it must not add a global settings section or a second cache reader/writer for the same artifact.

The local avatar is a runtime kinematic camera embodiment. Its collision movement uses Avian's existing MoveAndSlide query against standard UsdPhysics colliders in ActivePhysicsFrame; it does not need a second USD body schema or a separate collision representation. An explicit Twin setting may select a documented unsafe policy, but the movement owner reads that setting directly and remains safe when the setting is omitted, malformed, or the Twin closes.

The shared semantic input contract lives in lunco-control-core, while the persisted device-to-intent map lives in lunco-input-core, and is not avatar-only: the workbench owns one app-level local intent surface for editor actions when an isolated preview has no avatar. Shared actions such as CancelIntent read that surface through the same InputBindingsSettings map, while avatar control continues to use its own surface; neither path may introduce a raw-key or duplicate binding. InputBindingsSettings::default() is a valid neutral override: it has no key or pointer overrides and uses the schema-defined Right look button until the application overlays its authored defaults. The authored document remains the source of product bindings, and persisted explicit values take precedence. An explicit invalid runtime value must be rejected, diagnosed in the status bar, and clear every live semantic input map so a stale map cannot continue controlling the simulation. The Workbench host remains alive with input disabled until settings are corrected. Invalid persisted sections are removed with a settings warning before the authored defaults are installed.

Source-backed program attachment

AttachProgram is the one authoring boundary for binding a .mo, .py, .rhai, or behaviour-tree source to an existing USD prim. Rust owns the generic command and lowers a complete ProgramAttachSpec into one journalled USD change set. The spec carries the source asset, explicit scalar inputs and outputs, defaults, native USD connections, and the explicit realtimeSafe promise.

The Models palette, Rhai assembly_edit::attach_program(...), HTTP callers, and the Assembly editor all use this command. None may insert an ECS marker or maintain a second program registry. An empty port contract is a valid source-only attachment, but it is not a running scalar cosim participant; the author must declare the interface before wiring or stepping it.

Generic authoring evidence

Authoring review is a Rhai policy over generic typed substrate. The shipped authoring_inspection library owns candidate comparison, diagnostic grouping, diagnostic navigation, unified inspection records, and inspection-mode policy; it does not know about rovers, landers, or other product nouns. Rust only provides the reusable mechanisms: document-scoped QueryUsdPrim and InspectUsdDocument reads, exact preview selection/framing, generic SetDiagnosticLayers, and settings-backed view-only camera presets.

Keep the ownership split explicit:

• USD remains authoritative for identity, topology, standard visual/collision facts, joints, frames, materials, connections, and provenance.
• Rhai chooses the affected paths, groups findings, decides which diagnostic layers to show, and composes the evidence record for a human or AI review.
• The Editor owns selection and preview leases; FrameUsdPreviewSelection frames one exact composed path and must not fall back to a whole-stage frame when the requested path is unavailable.
• Shared settings own persisted view-only camera presets. Presets never become USD camera prims, journal entries, or another scene graph.

Use exact DocumentId, UsdPreviewId, UsdPreviewViewId, edit target, and projection generation at every boundary. A document-local Editor fork may be queried through its composed document stage even when it has no mounted Twin projection; a stale mapped Twin document must still fail visibly. Missing collision or provenance is an explicit diagnostic record, not a fabricated default. Keep positive and negative contracts in the production Rhai scene gate; do not duplicate these observable assertions in Rust unit tests.

Document-private viewport mounts are recorded separately from workspace/preview leases in DocBackedTwinScenes. Release them at DocumentClosed, or when the final preview lease ends with no workspace projection owner. The projection synchronizer must not consume that closure bookkeeping. Catalog mount-set changes also prune private authorities before replacement scans.