Mechanism: Stages declare flexible_schema input/output contracts (refs #324)

[mmcdermott]

Summary

Part 1 of #324. Introduces the mechanism by which stages declare their input and output schemas, and demonstrates it on aggregate_code_metadata.

• Stage now accepts input_schema, output_schema, metadata_input_schema, metadata_output_schema (all flexible_schema.Schema subclasses, all optional).
• Stage.register forwards these kwargs unchanged.
• Stage.declared_schemas returns the four roles as a dict for consumers (pipeline-load-time validation, downstream composer checks in We should support a "meta-stage" set-up where you can run multiple transformations in a single stage at once, without caching the files in between. #56).
• aggregate_code_metadata declares DataSchema on input_schema and CodeMetadataSchema on metadata_output_schema — a case where the schemas actually differ, so the declaration carries real information. (An earlier draft annotated filter_subjects with DataSchema on both sides, but that was just restating the default; reverted and replaced per review.)

Scope

Deliberately minimal. Full stage-by-stage migration is a follow-up so each migration can land with its own targeted review and tests (every stage is doing slightly different shape transforms and the output_schema may need to be derived from the stage config for some of them). This PR is the enabling plumbing.

Test plan

• Full non-parallel suite: 145 passed.
• New declared_schemas doctest covers all four role slots.
• Registered-stage suite for aggregate_code_metadata: 7 passed, including the existing example scenarios.

Refs #324

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.25%. Comparing base (ce04e87) to head (ddd1676).
⚠️ Report is 22 commits behind head on dev.

Additional details and impacted files

@@            Coverage Diff             @@
##              dev     #379      +/-   ##
==========================================
+ Coverage   98.23%   98.25%   +0.01%     
==========================================
  Files          54       55       +1     
  Lines        2607     2630      +23     
==========================================
+ Hits         2561     2584      +23     
  Misses         46       46              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Copilot]

Pull request overview

This PR adds plumbing for MEDS-Transforms stages to declare optional flexible_schema input/output contracts, and demonstrates the pattern by annotating the filter_subjects stage (per #324).

Changes:

• Extend Stage to accept optional input_schema, output_schema, metadata_input_schema, metadata_output_schema.
• Add Stage.declared_schemas to expose the four schema roles in a consistent dict for downstream consumers.
• Update filter_subjects to declare DataSchema as both its input and output schema.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/MEDS_transforms/stages/base.py	Adds schema contract fields to Stage plus a declared_schemas accessor (with doctest).
src/MEDS_transforms/stages/filter_subjects/filter_subjects.py	Declares DataSchema for filter_subjects via Stage.register(...).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mmcdermott]

Can this not go straight into dev, but into another branch that is for the broader feature set this is a part of? If all we're adding is this, I'm not sure I see the point.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.