7 - API (feat): Unify Proposal Number

[RobertRosca]

PR no. 7 of the big refactor.

Proposal numbers are kinda confusing throughout as they are untyped str/ints which are used throughout the code for e.g. GraphQL input, filesystem paths, keys, etc..., all of which currently does validation/formatting ad hoc wherever needed.

This makes it hard to hard what a 'proposal number' is or what it's intended to be, especially with strings that colud be one of '1234', '001243', 'p001243', 'p1234'.

This PR tries to help with this by adding one ProposalNumber value type (plus a matching ProposalNo GraphQL scalar) which is then used across the slices. Adds ADR-004 for the reasoning.

Details

ProposalNumber + ProposalNo

ProposalNumber (in shared/models.py) is a pure int subclass that:

• validates the range (1-999999) and rejects floats
• formats to the canonical p{n:06d} form via __str__ (e.g. p001234)
• carries a pydantic core schema so it validates/serialises in models

This replaces the old Annotated[int, Field(...)] alias, and drops the duplicate ProposalId alias that was the same thing under a different name.

ProposalNo is the strawberry scalar wrapping it (serialises to a plain int), so the value type is used at the graphql edge too.

One gotcha worth calling out: since str(proposal) now gives p001234 rather than 1234, anywhere that built a string from the number needed a look - the MyMdC client now formats it as an integer explicitly when building API URLs, otherwise the p-prefixed form would leak into the requests.

TBH I'm not set on this design, was just curious about how well a weird custom int subclass would work for this. A saner and clearer alternative would be not screwing with __str__ for the subclass and instead adding some explicit .as_str() method which returns the prefixed/padded proposal number string.

Path resolution

get_damnit_path now raises ProposalNotFoundError (ADR-001) instead of a bare RuntimeError when a proposal directory can't be found.

ADR-004 is included here but it's only half-landed (the usual pattern by now): it describes both the pure value type and an injectable ProposalPathLocator that owns the slow GPFS number-to-directory resolution behind a swappable seam. Only the value type half is in this branch - the locator (async resolution, off-event-loop timeouts,
GPFS vs fixed implementations) is a later branch. Path resolution still lives in get_damnit_path reading settings for now.

ty

This branch adds ty to the lint group since I... accidentally added it.

Tests

• test_models.py covers ProposalNumber validation and formatting
• new tests cover ProposalNo scalar rejection and the path-not-found case
• the gql parity snapshot (schema.graphql) is updated for the new scalar

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[CammilleCC]

We might have to get ready for a bit more generalization. From the ongoing Petra III integration, it seems that they have proposals as strings, here: https://github.com/European-XFEL/DAMNIT/blob/bb53ce207593fff57c41716f8c4c435cee271e75/damnit/ctxsupport/find_beamtime.py#L7

[CammilleCC]

Why do we use pyright AND ty? Might make more sense to choose one over the other. Also please include the chosen type checker in the CI and pre-commit.