Build a deterministic semantic version constraint evaluator for GuildPass capabilities

[Lakes41]

Difficulty: Advanced
Type: Feature
Recommended labels (if available in this repo): backend, compatibility, type-safety, advanced

Background

GuildPass modules and future smart contract interfaces may evolve independently. Core will need a small compatibility primitive capable of determining whether a declared capability version satisfies a required version constraint.

This issue introduces a standalone semantic-version evaluation module and does not implement package management, deployments or contract upgrades.

Problem

There is currently no standard GuildPass mechanism for representing and evaluating version compatibility.

Ad-hoc string comparisons such as 2.10.0 > 2.9.0 are incorrect and can produce subtle compatibility bugs.

Expected Outcome

Implement a strongly typed semantic version parser and constraint evaluator suitable for internal GuildPass capability checks.

Suggested Implementation

The module should support valid semantic versions such as:

1.0.0
2.3.1
3.0.0-beta.1

At minimum, support constraints such as:

=1.2.3
>1.2.3
>=1.2.3
<2.0.0
<=2.0.0

Optionally support bounded compound constraints if implemented cleanly.

The implementation should:

• parse major, minor and patch components numerically;
• support semantic version precedence rules;
• handle prerelease identifiers correctly;
• reject malformed versions;
• reject malformed constraints;
• expose deterministic comparison functions;
• avoid relying on lexicographical string ordering;
• either use a lightweight trusted semver dependency or implement the required subset explicitly and test it thoroughly;
• remain free of API and database concerns.

Acceptance Criteria

• Valid semantic versions parse correctly.
• Invalid versions are rejected.
• 1.10.0 correctly compares greater than 1.9.0.
• Major, minor and patch precedence is correct.
• Prerelease precedence is handled according to documented semantics.
• Equality, greater-than, greater-than-or-equal, less-than and less-than-or-equal constraints work.
• Malformed constraints fail safely.
• Evaluation results are deterministic.
• Public APIs are strongly typed.
• Unit tests cover boundary and prerelease cases.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No package installation or deployment workflow is implemented.

Likely Affected Files/Directories

packages/version-constraints/ or equivalent isolated package
unit tests

Independence Requirement

This task must remain a standalone compatibility primitive and must not depend on another GuildPass feature being implemented first.

[Santia2004]

Hi! I would like to work on this issue. I have solid experience with TypeScript/JavaScript, backend architectures, and Stellar/Soroban contracts, and I recently contributed merged implementations to the campaign. I can deliver a clean, tested solution following the repo's guidelines and best practices. Please feel free to assign it to me. Thanks!

[Faizehy]

hello maintainer I would love to work on this

[grantfox-oss]

🦊 GrantFox — @Faizehy has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #355)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.