Add explicit producer observation metadata

[AlexanderFengler]

Purpose

Add a small, out-of-band descriptor API for producer observation schemas. This lets a
consumer inspect semantic observation width and per-field domains before simulation,
without changing any simulator result, registered model, HSSM wrapper, or downstream
consumer.

Scope

• add validate_observation_metadata(...) for explicitly declared producer metadata
• add get_observation_metadata(...) for explicit mappings and annotated callables
• return a fresh plain descriptor with exactly:
  • observation_schema_version
  • ordered observation_schema
  • schema-derived obs_dim
• support the named legacy_rt_choice profile only when both the profile and exact
  categorical choices are declared
• reuse the native result contract's structural schema validation while keeping concrete
  floating-dtype representability checks on actual result arrays
• expose the two functions from ssms.basic_simulators

The descriptor is not simulator-result metadata. Existing result metadata remains an
open producer-extension mapping, and no keys are added to or removed from it here.

Fail-closed behavior

The accessor never executes a callable and never infers a schema from obs_dim,
nchoices, result keys, sampled values, tags, simulator identity, or a dummy RT.
Callable legacy .obs_dim is deliberately ignored: semantic descriptor width comes from
the schema and does not rewrite the existing HSSM compatibility attribute.

Verification

• full test suite: 1,209 passed, 134 skipped
• focused producer-metadata suite: 33 passed
• new module: 100% branch coverage
• ruff check .
• ruff format --check .
• focused mypy on both affected source modules
• git diff --check
• two independent read-only reviews; final head has no findings

Deferred

• built-in registry, decorated-callable, and Simulator adoption
• RLSSM ModelConfig / AssembledModel adoption
• HSSM, LANfactory, LAN-pipeline, tutorial, and optional GUI compatibility matrix
• contributor documentation for the completed producer-adoption stack

Those remain separate stacked PRs so this root stays reviewable. There are no dependency,
lockfile, simulator-output, or default-behavior changes in this PR.

[coderabbitai]

Warning

Review limit reached

Next included review available in 40 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e9499a3b-b816-4489-901a-052635c571a8

📥 Commits

Reviewing files that changed from the base of the PR and between 8260ffa and 2adf3f7.

📒 Files selected for processing (4)

• ssms/basic_simulators/__init__.py
• ssms/basic_simulators/observation_metadata.py
• ssms/basic_simulators/observation_results.py
• tests/test_observation_metadata.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
unittests	94.33% <100.00%> (+0.08%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
ssms/basic_simulators/observation_metadata.py	100.00% <100.00%> (ø)
ssms/basic_simulators/observation_results.py	94.24% <100.00%> (+0.01%)	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.