Build a deterministic contribution score normalisation engine

[Lakes41]

Difficulty: Expert
Type: Feature
Recommended labels (if available in this repo): contributions, backend, consistency, expert

Background

GuildPass communities may eventually combine different contribution metrics, such as code contributions, participation or completed tasks, into comparable scoring dimensions.

Raw metrics can operate on incompatible scales. A standalone normalisation engine provides a mathematical primitive for later contribution systems without implementing the entire contribution engine.

Problem

There is currently no shared Core utility for converting heterogeneous weighted metrics into a deterministic bounded score.

Floating-point calculations, undefined missing-value behaviour and inconsistent clamping rules can make scoring difficult to reproduce.

Expected Outcome

Implement a pure contribution score normalisation engine using exact or explicitly controlled arithmetic and a documented scoring model.

Suggested Implementation

Inputs may resemble:

interface ContributionMetric {
  key: string;
  value: bigint;
  minimum: bigint;
  target: bigint;
  weightBps: number;
}

The engine should:

• validate metric ranges;
• use integer basis points or another exact weighting representation;
• avoid ordinary floating-point threshold calculations;
• normalise each metric into a bounded range;
• combine weighted metrics deterministically;
• define behaviour when a value exceeds its target;
• define behaviour for zero-range metrics;
• validate total configured weights;
• expose per-metric intermediate results for explainability;
• support large bigint input values;
• produce one documented final score scale, such as 0-10,000 basis points;
• remain storage-independent.

Acceptance Criteria

• Individual metrics are normalised deterministically.
• Weighted combination uses exact or controlled integer arithmetic.
• Final scores remain inside the documented range.
• Inputs below minimum and above target have explicitly defined behaviour.
• Invalid ranges are rejected.
• Invalid weights are rejected.
• Large bigint metrics are supported.
• Equivalent metrics supplied in different array order produce the same result if metric keys are unique.
• Per-metric calculation details are returned.
• Unit tests cover boundary values, weighting, clamping and large numbers.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No contribution persistence, badge or reward integration is included.

Likely Affected Files/Directories

packages/contribution-normalisation/ or equivalent isolated package
unit tests

Independence Requirement

This task must remain a pure scoring primitive and must not depend on the reward engine, contribution persistence or another campaign issue.

[diegoveme]

Hello Adamantine Guild team,

My background
My name is Diego, a full-stack developer with backend experience across TypeScript and systems-level work.

What I'd bring
This issue is a good fit for me since it's fundamentally about deterministic, exact arithmetic rather than product logic, and that's a space I'm comfortable in. I'd approach it as: bigint-based basis-point weighting throughout (no floats anywhere in the scoring path), explicit clamping rules for below-minimum and above-target values, a zero-range guard that's defined rather than left as a divide-by-zero trap, and validation that rejects malformed ranges or weight totals before any computation runs. I'd also make sure the engine returns per-metric intermediate results (not just the final score) so the combination step is auditable, and that array order never affects the result once keys are deduplicated.

I'd keep the package fully isolated, no dependency on persistence, rewards, or other campaign work, and back it with unit tests covering boundary values, large bigint inputs, and weight-combination edge cases.

Links
GitHub: https://github.com/diegoveme

Thank you for considering my application. I'm glad to answer any questions on the approach.

Best regards,
Diego

[Agbasimere]

Can I work on this?

[grantfox-oss]

🦊 GrantFox — @diegoveme 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 #387)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🦊 GrantFox — @diegoveme 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 #387)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.