Author Hook Policy

Inspect and test

Use list_hooks() to inspect the reflected declaration. It reports parameters: [{name, type}], output, ownership, policy binding, determinism, requirement, and installation state. Use policy_status() for startup/Twin load diagnostics and the last typed Twin lifecycle result. The owner must consume every non-Unit result; the lifecycle dispatcher retains its returned map and exact invocation context in that status surface. Twin lifecycle calls use a Twin/Lifecycle route whose generation is the mounted Twin's nonzero TwinId; startup/reload, asset events, and teardown use Start, Event, and Stop phases with no elapsed clock. The assets_mounted lifecycle event receives the parsed Twin manifest, indexed relative paths, exact twin:// authority, and active-Twin fact. Its ordered {command, params} actions go through the generic typed command bridge; Rhai chooses loaders and order, while each domain owner validates paths and performs asynchronous work. A malformed plan faults and queues no commands; a rejected command is reported while later actions continue. invoke_hook(id, [args]) distinguishes unavailable hooks from installed functions that fault.

Scheduled owner calls supply an immutable runtime_context map with their route, cycle, phase, clock, and logical sequence. If a policy is valid only in one cycle, reject other contexts and verify the real scheduled owner path in an authored production test. For example, readiness.action runs under Core/Simulation/Behavior with fixed-clock time and the latest SimTick; its policy rejects direct calls from other cycles. Physics initialization is a discrete lifecycle decision: use the required physics.initialization(facts) seam, a generation-qualified Twin/Lifecycle/Preparation route, and no clock sample. Its stable facts include the selector, validation status, pose, assembly size, and measured penetration when present. accept admits the authored pose unchanged, pause disables the validated penetrating assembly and removes it from scene readiness, and reject keeps it held. The shipped Application policy pauses measured terrain penetrations and remains installed across Twin reloads; a mounted Twin may replace it. Keep authored selector names in facts.policy; do not construct dynamic hook ids or expose process-local ECS entity ids as deterministic policy facts.

The application twin.lifecycle policy selects the active Twin's default USD scene, tool libraries, timeline data, SysML/KerML sources, and Modelica roots from its typed manifest and indexed file inventory. Loader commands keep only generic ownership, safe-path, asset-read, and domain-registration mechanics.

For application UI contributions, reuse the optional application.asset.lifecycle(event, ctx) hook. The shared asset layer emits JSON-scope loading/changed events after asynchronous reads, including the canonical asset_root_uri; the Rhai policy can parse each record with parse_json(text) and return a generic menus tree. Scene completion is also delivered with the canonical loaded path and root_prim; return selected declared dataset ids in dataset_text_artifacts when the scene needs their text. The Rust host validates the complete action map, while DatasetArtifactPlugin resolves each registry id to its canonical asset URI and reads through the shared TextAsset loader. Missing or unreadable requested datasets are reported; unrequested datasets remain quiet. SceneTransitionStarted retires pending reads. Keep asset selection and menu policy in Rhai; Rust owns typed lifecycle facts, safe asset delivery, action-shape validation, rendering, and provider cleanup.

Put policy and observable runtime assertions in an authored Rhai production scene test. Cover the declared signature, successful binding/invocation, missing-policy status, rejected deterministic inline binding, and exact unbinding. Keep Rust coverage to the low-level HookValue conversion and registry mechanics; do not embed long USD or load Twin assets in Rust tests.

The primary USD scene lifecycle also owns required deterministic usd.scene_composition(facts: Map) -> Map for incomplete composition closures. Its facts contain the scene address and ordered unresolved arcs. The shipped application policy returns #{action: "allow_partial"} to preserve the existing partial-load behavior; a Twin may replace it with reject_scene. The owner invokes it after structural projection but before releasing the simulation hold. Rejection tears down the partial primary scene, and missing, faulting, or malformed policy results fail admission visibly. Keep the loader's missing-arc warning and the policy's admission decision as separate owner responsibilities.

Handoff

Report the owner-side declaration, manifest/source files, reflected signature, failure semantics, focused checks, and the production Rhai test evidence.

Scene avatar availability

lunco-camera-core declares camera.scene_avatar(ctx: Map) -> Map independently of camera selection. The windowed camera owner calls it in Application/Presentation/Preparation on scene/projection/policy changes. The application policy returns create: bool and, for creation, bindings containing [intent, port, f64 factor] rows. Rust validates the shared control vocabulary, installs the scene-owned transient rig, and reports invalid results through the camera contract. The rig has no USD prim identity and does not enter saved layers. Keep director/operator selection independent of avatar availability; reuse an authored avatar and retire transient rigs at scene teardown.

Verify both avatar-free and authored-avatar cases with scene_avatar_presence.rhai in an owned windowed production session, supplying its exact doc_id and authored_avatar_path (unit for a transient avatar). The scenario saves an ignored artifact and compares all document layers. The production test_hook_policies.rhai covers declaration and off-cycle rejection.