[dhutererprats]

Description

Closes #357
Fixes #359

This brings space-to-space imaging into BSK-RL. An imager selects an independently orbiting RSO, tracks it, completes the required pointing hold, and stores the image. Delivery reward is given after the complete image has been downlinked. These targets are whole spacecraft, while the existing RSO Inspection example observes surface points on one nearby spacecraft.

The component commits include Lorenzo's review changes:

• Targets bind to an explicit satellite name and use spacecraft dynamics. Ground-station dynamics are composed into an imager only when it needs a ground downlink.
• Catalog utc_init is optional. An unpinned catalog follows the environment's realized epoch on each reset, and saving the resolved catalog records that epoch for replay. An explicit mismatch raises an error.
• Satellite names are checked when constructed or renamed, then used directly for events. Hashing is removed. Existing examples and benchmarks now use valid names.
• The normalized target observation is the default. Observation and action counts can differ, with shared target ordering. Stale observations produce a warning without silently switching targets.
• Acquisition and delivery rewards accept callbacks. The default gives full priority credit on complete delivery (alpha=1.0). The example exposes its weights explicitly, including the existing AMOS alpha=0.1 option.
• The notebook is under Examples → Environments → RSO Missions, alongside RSO Inspection. Its optional evaluation produces action, reward, storage, battery, and wheel histories, with PNG/PDF plots and CSV records.

Following the agreed approach, acquisition uses a temporary BSK-RL gate with the existing Basilisk message API. Continuous holds reset when qualification breaks. Cumulative holds preserve qualifying intervals. Illumination is sampled over those intervals, and the capture is recorded only after the complete image reaches physical storage. This PR does not require the proposed native controller extension.

Type of change

• Bug fix
• New feature
• Breaking change

Satellite names must now be valid Python identifiers, such as EO_1 instead of EO-1. Target catalog IDs can still contain punctuation. This requirement is documented in the release notes.

How should this pull request be reviewed?

• By commit
• All changes at once

The history has been rewritten so each component contains its final implementation. There is no separate review-fix or lint-cleanup commit. Each of the 50 changed files reaches its final contents in one commit.

Commit	Component
226985b	Make eclipse observation regressions deterministic
ed6f14b	Add replayable RSO catalogs and explicit scene bindings
e214923	Add spacecraft imaging dynamics and stable access bindings
bbabd03	Gate RSO acquisition before physical image storage
191a0e4	Account for owned RSO images and complete deliveries
c947d1f	Share RSO candidate snapshots with action decoding
e39b097	Demonstrate RSO imaging and replayable AMOS settings
a3432fb	Add replayable RSO policy evaluation and plots
cdb0d95	Verify physical RSO acquisition and delivery end to end
c74260f	Document the space-to-space imaging API and model contracts

The eclipse tests come first. The naming migration is included with acquisition/event handling, policy evaluation comes before its integration tests, and documentation comes last. After reviewing the components, check the complete path from target selection through capture, storage, downlink, and reward.

How Has This Been Tested?

• Local unit and integration suites: 833 passed, 2 existing skips, using the unmodified Basilisk controller.
• Physical tests cover hold interruptions, cumulative/continuous timing, message freshness, storage capacity, capture confirmation, partial downlinks, cooldown, epoch handling, and episode resets.
• Existing ground-imaging and RSO-inspection benchmark smoke tests: 3 passed.
• The new notebook ran in both modes through capture, complete delivery, and exact initial-observation replay. The communication, satellite-configuration, and AEOS notebooks also executed successfully.
• An audit of the shipped examples and benchmarks found no remaining invalid literal satellite names or name templates. The existing asynchronous-training example's constructor setup was checked without starting training.
• Ruff lint, import ordering, and patch whitespace checks pass. HTML builds successfully with 16 existing documentation warnings. Notebook execution and HTML rendering were checked separately.

Local checks used Python 3.11.9 and the existing Basilisk 2.13.0b0 runtime, without the proposed controller extension. The physical imaging/example checks also passed with the existing 2.12.0 validation runtime. All eight GitHub checks passed on the previously published history, including the Python 3.10–3.13 test matrix, benchmark smoke tests, commit messages, and documentation build.

The October 7 update changes only the release-note bullet and commit metadata. CI is running on the latest head.

The separate eclipse-test commit fixes the incorrect countdown assumption tracked in #359. The tests use the same simulation start date, orbit, and random seed on every run so the results are repeatable, then check ordinary countdowns, shadow entry, and rollover to later orbits. Eclipse prediction is unchanged. The release notes include a separate bullet identifying this as a test bug fix.

Future Work

Basilisk #1602 requests cumulative holds and target illumination in simpleInstrumentController. BSK-RL #358 tracks replacing the temporary gate after that update is merged and available. The native implementation and tests are prepared separately and are not part of this branch.

Checklist

• I have performed a self-review of my code
• I have commented the acquisition and storage logic
• I have updated the documentation and release notes
• I have added unit and Basilisk integration tests
• I have run existing ground-imaging and RSO-inspection regressions
• GitHub CI has passed for the latest head
• Final review is complete

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[LorenzzoQM]

Looks good! Thank you for addressing all comments.