refactor(time): migrate runtime time handling to Temporal

apps/bot/src/anonymous-feedback.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, mock, test } from 'bun:test'
 
 import type { AnonymousFeedbackService } from '@household/application'
+import { instantFromIso, nowInstant, Temporal, type Instant } from '@household/domain'
 import type {
   HouseholdConfigurationRepository,
   TelegramPendingActionRepository
@@ -43,7 +44,7 @@ function anonUpdate(params: {
 }
 
 function createPromptRepository(): TelegramPendingActionRepository {
-  const store = new Map<string, { action: 'anonymous_feedback'; expiresAt: Date | null }>()
+  const store = new Map<string, { action: 'anonymous_feedback'; expiresAt: Instant | null }>()
 
   return {
     async upsertPendingAction(input) {
@@ -60,7 +61,7 @@ function createPromptRepository(): TelegramPendingActionRepository {
         return null
       }
 
-      if (record.expiresAt && record.expiresAt.getTime() <= Date.now()) {
+      if (record.expiresAt && Temporal.Instant.compare(record.expiresAt, nowInstant()) <= 0) {
         store.delete(key)
         return null
       }
@@ -477,4 +478,68 @@ describe('registerAnonymousFeedback', () => {
     expect(calls[1]?.method).toBe('answerCallbackQuery')
     expect(calls[2]?.method).toBe('editMessageText')
   })
+
+  test('includes the next allowed time in cooldown replies', async () => {
+    const bot = createTelegramBot('000000:test-token')
+    const calls: Array<{ method: string; payload: unknown }> = []
+
+    bot.botInfo = {
+      id: 999000,
+      is_bot: true,
+      first_name: 'Household Test Bot',
+      username: 'household_test_bot',
+      can_join_groups: true,
+      can_read_all_group_messages: false,
+      supports_inline_queries: false,
+      can_connect_to_business: false,
+      has_main_web_app: false,
+      has_topics_enabled: true,
+      allows_users_to_create_topics: false
+    }
+
+    bot.api.config.use(async (_prev, method, payload) => {
+      calls.push({ method, payload })
+
+      return {
+        ok: true,
+        result: {
+          message_id: calls.length,
+          date: Math.floor(Date.now() / 1000),
+          chat: {
+            id: 1,
+            type: 'private'
+          },
+          text: 'ok'
+        }
+      } as never
+    })
+
+    registerAnonymousFeedback({
+      bot,
+      anonymousFeedbackServiceForHousehold: () => ({
+        submit: mock(async () => ({
+          status: 'rejected' as const,
+          reason: 'cooldown' as const,
+          nextAllowedAt: nowInstant().add({ hours: 6 })
+        })),
+        markPosted: mock(async () => {}),
+        markFailed: mock(async () => {})
+      }),
+      householdConfigurationRepository: createHouseholdConfigurationRepository(),
+      promptRepository: createPromptRepository()
+    })
+
+    await bot.handleUpdate(
+      anonUpdate({
+        updateId: 1008,
+        chatType: 'private',
+        text: '/anon Please clean the kitchen tonight.'
+      }) as never
+    )
+
+    expect(calls).toHaveLength(1)
+    expect(calls[0]?.payload).toMatchObject({
+      text: 'Anonymous feedback cooldown is active. You can send the next message in 6 hours.'
+    })
+  })
 })

apps/bot/src/anonymous-feedback.ts

@@ -1,4 +1,5 @@
 import type { AnonymousFeedbackService } from '@household/application'
+import { Temporal, nowInstant, type Instant } from '@household/domain'
 import type { Logger } from '@household/observability'
 import type {
   HouseholdConfigurationRepository,
@@ -43,7 +44,30 @@ function shouldKeepPrompt(reason: string): boolean {
   return reason === 'too_short' || reason === 'too_long' || reason === 'blocklisted'
 }
 
-function rejectionMessage(reason: string): string {
+function formatRetryDelay(now: Instant, nextAllowedAt: Instant): string {
+  if (Temporal.Instant.compare(nextAllowedAt, now) <= 0) {
+    return 'now'
+  }
+
+  const duration = now.until(nextAllowedAt, {
+    largestUnit: 'hour',
+    smallestUnit: 'minute',
+    roundingMode: 'ceil'
+  })
+
+  const days = Math.floor(duration.hours / 24)
+  const hours = duration.hours % 24
+
+  const parts = [
+    days > 0 ? `${days} day${days === 1 ? '' : 's'}` : null,
+    hours > 0 ? `${hours} hour${hours === 1 ? '' : 's'}` : null,
+    duration.minutes > 0 ? `${duration.minutes} minute${duration.minutes === 1 ? '' : 's'}` : null
+  ].filter(Boolean)
+
+  return parts.length > 0 ? `in ${parts.join(' ')}` : 'in less than a minute'
+}
+
+function rejectionMessage(reason: string, nextAllowedAt?: Instant, now = nowInstant()): string {
   switch (reason) {
     case 'not_member':
       return 'You are not a member of this household.'
@@ -52,9 +76,13 @@ function rejectionMessage(reason: string): string {
     case 'too_long':
       return 'Anonymous feedback is too long. Keep it under 500 characters.'
     case 'cooldown':
-      return 'Anonymous feedback cooldown is active. Try again later.'
+      return nextAllowedAt
+        ? `Anonymous feedback cooldown is active. You can send the next message ${formatRetryDelay(now, nextAllowedAt)}.`
+        : 'Anonymous feedback cooldown is active. Try again later.'
     case 'daily_cap':
-      return 'Daily anonymous feedback limit reached. Try again tomorrow.'
+      return nextAllowedAt
+        ? `Daily anonymous feedback limit reached. You can send the next message ${formatRetryDelay(now, nextAllowedAt)}.`
+        : 'Daily anonymous feedback limit reached. Try again tomorrow.'
     case 'blocklisted':
       return 'Message rejected by moderation. Rewrite it in calmer, non-abusive language.'
     default:
@@ -91,7 +119,7 @@ async function startPendingAnonymousFeedbackPrompt(
     telegramChatId,
     action: ANONYMOUS_FEEDBACK_ACTION,
     payload: {},
-    expiresAt: new Date(Date.now() + PENDING_ACTION_TTL_MS)
+    expiresAt: nowInstant().add({ milliseconds: PENDING_ACTION_TTL_MS })
   })
 
   await ctx.reply('Send me the anonymous message in your next reply, or tap Cancel.', {
@@ -175,10 +203,12 @@ async function submitAnonymousFeedback(options: {
       await options.promptRepository.clearPendingAction(telegramChatId, telegramUserId)
     }
 
+    const rejectionText = rejectionMessage(result.reason, result.nextAllowedAt, nowInstant())
+
     await options.ctx.reply(
       shouldKeepPrompt(result.reason)
-        ? `${rejectionMessage(result.reason)} Send a revised message, or tap Cancel.`
-        : rejectionMessage(result.reason),
+        ? `${rejectionText} Send a revised message, or tap Cancel.`
+        : rejectionText,
       shouldKeepPrompt(result.reason)
         ? {
             reply_markup: cancelReplyMarkup()

apps/bot/src/miniapp-dashboard.test.ts

@@ -4,6 +4,7 @@ import {
   createFinanceCommandService,
   createHouseholdOnboardingService
 } from '@household/application'
+import { instantFromIso } from '@household/domain'
 import type {
   FinanceRepository,
   HouseholdConfigurationRepository,
@@ -53,7 +54,7 @@ function repository(
         amountMinor: 12000n,
         currency: 'USD',
         createdByMemberId: member?.id ?? 'member-1',
-        createdAt: new Date('2026-03-12T12:00:00.000Z')
+        createdAt: instantFromIso('2026-03-12T12:00:00.000Z')
       }
     ],
     listParsedPurchasesForRange: async () => [
@@ -62,7 +63,7 @@ function repository(
         payerMemberId: member?.id ?? 'member-1',
         amountMinor: 3000n,
         description: 'Soap',
-        occurredAt: new Date('2026-03-12T11:00:00.000Z')
+        occurredAt: instantFromIso('2026-03-12T11:00:00.000Z')
       }
     ],
     replaceSettlementSnapshot: async () => {}

apps/bot/src/purchase-topic-ingestion.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from 'bun:test'
 
+import { instantFromIso } from '@household/domain'
 import { createTelegramBot } from './bot'
 
 import {
@@ -25,7 +26,7 @@ function candidate(overrides: Partial<PurchaseTopicCandidate> = {}): PurchaseTop
     threadId: '777',
     senderTelegramUserId: '10002',
     rawText: 'Bought toilet paper 30 gel',
-    messageSentAt: new Date('2026-03-05T00:00:00.000Z'),
+    messageSentAt: instantFromIso('2026-03-05T00:00:00.000Z'),
     ...overrides
   }
 }

apps/bot/src/purchase-topic-ingestion.ts

@@ -1,5 +1,5 @@
 import { parsePurchaseMessage, type PurchaseParserLlmFallback } from '@household/application'
-import { Money } from '@household/domain'
+import { instantFromEpochSeconds, instantToDate, Money, type Instant } from '@household/domain'
 import { and, eq } from 'drizzle-orm'
 import type { Bot, Context } from 'grammy'
 import type { Logger } from '@household/observability'
@@ -24,7 +24,7 @@ export interface PurchaseTopicCandidate {
   senderTelegramUserId: string
   senderDisplayName?: string
   rawText: string
-  messageSentAt: Date
+  messageSentAt: Instant
 }
 
 export interface PurchaseTopicRecord extends PurchaseTopicCandidate {
@@ -170,7 +170,7 @@ export function createPurchaseMessageRepository(databaseUrl: string): {
           telegramMessageId: record.messageId,
           telegramThreadId: record.threadId,
           telegramUpdateId: String(record.updateId),
-          messageSentAt: record.messageSentAt,
+          messageSentAt: instantToDate(record.messageSentAt),
           parsedAmountMinor: parsed?.amountMinor,
           parsedCurrency: parsed?.currency,
           parsedItemDescription: parsed?.itemDescription,
@@ -286,7 +286,7 @@ function toCandidateFromContext(ctx: Context): PurchaseTopicCandidate | null {
     threadId: message.message_thread_id.toString(),
     senderTelegramUserId,
     rawText: message.text,
-    messageSentAt: new Date(message.date * 1000)
+    messageSentAt: instantFromEpochSeconds(message.date)
   }
 
   if (senderDisplayName.length > 0) {

apps/bot/src/reminder-jobs.ts

@@ -1,5 +1,5 @@
 import type { ReminderJobService } from '@household/application'
-import { BillingPeriod } from '@household/domain'
+import { BillingPeriod, nowInstant } from '@household/domain'
 import type { Logger } from '@household/observability'
 import { REMINDER_TYPES, type ReminderType } from '@household/ports'
 
@@ -27,11 +27,7 @@ function parseReminderType(raw: string): ReminderType | null {
 }
 
 function currentPeriod(): string {
-  const now = new Date()
-  const year = now.getUTCFullYear()
-  const month = `${now.getUTCMonth() + 1}`.padStart(2, '0')
-
-  return `${year}-${month}`
+  return BillingPeriod.fromInstant(nowInstant()).toString()
 }
 
 async function readBody(request: Request): Promise<ReminderJobRequestBody> {

apps/bot/src/telegram-miniapp-auth.test.ts

@@ -1,12 +1,14 @@
 import { describe, expect, test } from 'bun:test'
 
+import { instantFromIso, instantToEpochSeconds } from '@household/domain'
+
 import { verifyTelegramMiniAppInitData } from './telegram-miniapp-auth'
 import { buildMiniAppInitData } from './telegram-miniapp-test-helpers'
 
 describe('verifyTelegramMiniAppInitData', () => {
   test('verifies valid init data and extracts user payload', () => {
-    const now = new Date('2026-03-08T12:00:00.000Z')
-    const initData = buildMiniAppInitData('test-bot-token', Math.floor(now.getTime() / 1000), {
+    const now = instantFromIso('2026-03-08T12:00:00.000Z')
+    const initData = buildMiniAppInitData('test-bot-token', instantToEpochSeconds(now), {
       id: 123456,
       first_name: 'Stan',
       username: 'stanislav'
@@ -24,9 +26,9 @@ describe('verifyTelegramMiniAppInitData', () => {
   })
 
   test('rejects invalid hash', () => {
-    const now = new Date('2026-03-08T12:00:00.000Z')
+    const now = instantFromIso('2026-03-08T12:00:00.000Z')
     const params = new URLSearchParams(
-      buildMiniAppInitData('test-bot-token', Math.floor(now.getTime() / 1000), {
+      buildMiniAppInitData('test-bot-token', instantToEpochSeconds(now), {
         id: 123456,
         first_name: 'Stan'
       })
@@ -39,15 +41,11 @@ describe('verifyTelegramMiniAppInitData', () => {
   })
 
   test('rejects expired init data', () => {
-    const now = new Date('2026-03-08T12:00:00.000Z')
-    const initData = buildMiniAppInitData(
-      'test-bot-token',
-      Math.floor(now.getTime() / 1000) - 7200,
-      {
-        id: 123456,
-        first_name: 'Stan'
-      }
-    )
+    const now = instantFromIso('2026-03-08T12:00:00.000Z')
+    const initData = buildMiniAppInitData('test-bot-token', instantToEpochSeconds(now) - 7200, {
+      id: 123456,
+      first_name: 'Stan'
+    })
 
     const result = verifyTelegramMiniAppInitData(initData, 'test-bot-token', now, 3600)
 
@@ -55,8 +53,8 @@ describe('verifyTelegramMiniAppInitData', () => {
   })
 
   test('rejects init data timestamps from the future', () => {
-    const now = new Date('2026-03-08T12:00:00.000Z')
-    const initData = buildMiniAppInitData('test-bot-token', Math.floor(now.getTime() / 1000) + 5, {
+    const now = instantFromIso('2026-03-08T12:00:00.000Z')
+    const initData = buildMiniAppInitData('test-bot-token', instantToEpochSeconds(now) + 5, {
       id: 123456,
       first_name: 'Stan'
     })

apps/bot/src/telegram-miniapp-auth.ts

@@ -1,5 +1,7 @@
 import { createHmac, timingSafeEqual } from 'node:crypto'
 
+import { instantToEpochSeconds, nowInstant, type Instant } from '@household/domain'
+
 interface TelegramUserPayload {
   id: number
   first_name?: string
@@ -19,7 +21,7 @@ export interface VerifiedMiniAppUser {
 export function verifyTelegramMiniAppInitData(
   initData: string,
   botToken: string,
-  now = new Date(),
+  now: Instant = nowInstant(),
   maxAgeSeconds = 3600
 ): VerifiedMiniAppUser | null {
   const params = new URLSearchParams(initData)
@@ -35,7 +37,7 @@ export function verifyTelegramMiniAppInitData(
   }
 
   const authDateSeconds = Number(authDateRaw)
-  const nowSeconds = Math.floor(now.getTime() / 1000)
+  const nowSeconds = instantToEpochSeconds(now)
   if (authDateSeconds > nowSeconds) {
     return null
   }