Build a deterministic time-window eligibility engine for GuildPass rules

[Lakes41]

Difficulty: Advanced
Type: Feature
Recommended labels (if available in this repo): policy, backend, consistency, advanced

Background

GuildPass rules may need to apply only during defined time windows, for example temporary access grants, campaign eligibility, governance periods or reward qualification windows.

This issue introduces a generic time-window evaluator that remains independent of any particular GuildPass domain feature.

Problem

Time-based rules are easy to implement inconsistently. Boundary inclusivity, timezone handling and overlapping intervals can produce different results across modules if there is no common primitive.

Expected Outcome

Implement a pure time-window engine that evaluates whether an instant falls inside one or more configured windows using explicit and deterministic boundary semantics.

Suggested Implementation

A window may resemble:

interface TimeWindow {
  startsAt: Date;
  endsAt: Date;
  startInclusive: boolean;
  endInclusive: boolean;
}

The engine should:

• validate that start is not after end;
• support explicit inclusive or exclusive boundaries;
• evaluate a timestamp against a single window;
• evaluate against multiple windows using any and all semantics where useful;
• normalise comparisons to UTC instants rather than local timezone strings;
• optionally merge overlapping windows through a separate pure helper;
• reject invalid dates;
• accept an injectable clock for current-time evaluation;
• avoid real-time sleeps in tests;
• remain free of database and API dependencies.

Acceptance Criteria

• Inclusive and exclusive start boundaries are tested.
• Inclusive and exclusive end boundaries are tested.
• Instants inside a window evaluate correctly.
• Instants outside a window evaluate correctly.
• Invalid reversed windows are rejected.
• Invalid dates are rejected safely.
• UTC-equivalent instants evaluate identically regardless of source timezone representation.
• Multiple-window semantics are deterministic and documented.
• Tests cover exact boundary timestamps.
• Current-time evaluation can use an injected clock.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No membership, reward, governance or persistence integration is included.

Likely Affected Files/Directories

packages/time-window/ or equivalent isolated package
unit tests

Independence Requirement

This issue must remain a generic rule-evaluation primitive and must not depend on another policy or domain issue.

[Violetlove200100]

Hi maintainer, I would like to work on this issue please assign it to me

[Santia2004]

Hi team! I’d love to take on this issue. I’ve previously contributed and had multiple PRs successfully merged in this repository, so I’m already well-familiar with the codebase, architecture, and workflow. Could you please assign this to me? Thanks!

[grantfox-oss]

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

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@Violetlove200100's PR #407 was approved and merged by @Lakes41.

🏆 @Violetlove200100: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (204 total points). Track your full progress on GrantFox.

👏 Great work, @Violetlove200100! Keep contributing to Adamantine-guild.