[JSDoc] Document Parameter Constraints and Return Types in src/lib/utils/time.ts

• Labels: good first issue, documentation, difficulty:beginner, area:core
• Target File: src/lib/utils/time.ts
• Estimated Time: 10–15 minutes
• Difficulty: Level 1 (Beginner)

Why This Matters

Clear and unambiguous JSDoc documentation ensures developers and new open-source contributors understand timezone conversion contracts and return formats directly inside IDE autocomplete popups.

Current Behavior

Time utility functions in src/lib/utils/time.ts lack comprehensive JSDoc annotations detailing parameter expectations, UTC/local timezone conventions, and return value object shapes.

Requested Change

Add standard JSDoc comments to exported helper functions in src/lib/utils/time.ts detailing:

• @param parameter constraints and types
• @returns string / object return specification
• @example usage snippets for common date computations

Acceptance Criteria

• Complete JSDoc blocks added to export functions in src/lib/utils/time.ts.
• Code passes type checking cleanly without lint or compilation warnings.
• Verification command succeeds: npm run test:file -- tests/temporal-engine.test.ts.

Verification

npm run test:file -- tests/temporal-engine.test.ts

Contributor Notes

Documentation-only enhancement.

🚀 How to Claim and Implement an Issue

1. Choose an Issue: Browse our open issues and pick one matching your interest and available time.
2. Comment on GitHub: Leave a comment on the corresponding GitHub issue: "I would like to work on this issue. Please assign it to me."
3. Follow the Guide: Review our Beginner's Contribution Guide for step-by-step Git instructions.
4. Verify Locally: Run the specific verification command listed on the issue before opening your PR.
5. Submit PR: Open a pull request against main referencing this issue number!

Start with the exported helper functions in src/lib/utils/time.ts and read their existing signatures and timezone behavior. Add JSDoc covering parameter constraints, UTC/local conventions, return shapes, and examples. Done means all exported helpers have complete documentation and npm run test:file -- tests/temporal-engine.test.ts passes without type, lint, or compilation warnings.