social-app/docs/plans/2026-03-16-calendar-timezone-unification.md

# Calendar Timezone Unification Implementation Plan

> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Eliminate calendar time mismatches by enforcing one end-to-end timezone policy across App input, Agent runtime context, tool execution, and UTC database storage.

**Architecture:** Keep database schema unchanged (`start_at/end_at TIMESTAMPTZ + timezone`) and enforce strict runtime normalization. Device timezone is injected from `RunAgentInput.forwardedProps`, resolved into a single `effective_timezone`, then written explicitly into tool arguments and persisted as event timezone while timestamps are stored in UTC. Calendar read responses include deterministic event-timezone-rendered values so frontend rendering is stable and no implicit `toLocal()` conversion remains.

**Tech Stack:** FastAPI, Pydantic v2, AgentScope runtime/tooling, Flutter (Dart), PostgreSQL TIMESTAMPTZ, pytest, Flutter test.

---

## Chunk 1: Protocol and Backend Runtime Normalization

### Task 1: Freeze protocol and timezone precedence contract

**Files:**
- Modify: `docs/protocols/agent/run-agent-input.md`
- Create: `docs/protocols/calendar/timezone-policy.md`

- [ ] **Step 1: Write protocol delta checklist in docs first**

Document the exact policy:
- `event_timezone > device_timezone > profile.timezone > UTC`
- `event_timezone` must be present in final tool call
- `start_at/end_at` must be timezone-aware
- DB stores UTC timestamps and IANA timezone string

- [ ] **Step 2: Update RunAgentInput protocol with forwardedProps contract**

Add canonical payload example:

```json
{
  "forwardedProps": {
    "client_time": {
      "device_timezone": "America/Los_Angeles",
      "client_now_iso": "2026-03-16T09:12:33-07:00",
      "client_epoch_ms": 1773658353000
    }
  }
}
```

- [ ] **Step 3: Add calendar timezone policy protocol doc**

Include:
- accepted datetime formats
- explicit error codes
- write/read response semantics
- DST handling rule

- [ ] **Step 4: Verify docs consistency**

Run: `cd backend && uv run python -m pytest tests/unit/core/agentscope/test_system_prompt.py -q`
Expected: PASS (no protocol-breaking prompt assumptions)


### Task 2: Parse forwarded device time and compute effective timezone

**Files:**
- Modify: `backend/src/core/agentscope/schemas/agui_input.py`
- Modify: `backend/src/core/agentscope/runtime/runner.py`
- Modify: `backend/src/core/agentscope/prompts/system_prompt.py`
- Test: `backend/tests/unit/core/agentscope/test_system_prompt.py`

- [ ] **Step 1: Write failing tests for effective timezone resolution**

Add tests covering:
- forwarded `device_timezone` present -> selected
- missing forwarded timezone -> fallback profile timezone
- invalid forwarded timezone -> fallback profile timezone

- [ ] **Step 2: Run tests to confirm RED**

Run: `cd backend && uv run pytest tests/unit/core/agentscope/test_system_prompt.py -k timezone -v`
Expected: FAIL on new assertions

- [ ] **Step 3: Implement minimal runtime context extraction**

Implement a typed helper in runner path to read:
- `run_input.forwarded_props.client_time.device_timezone`
- `client_now_iso`
- `client_epoch_ms`

Compute `effective_timezone` using fixed precedence and pass it into `build_system_prompt(...)`.

- [ ] **Step 4: Inject effective_timezone into ENV section**

Update `build_system_prompt` env payload to include:
- `timezone_profile`
- `timezone_device`
- `timezone_effective`

Update guidance sentence to resolve ambiguous time with `timezone_effective`.

- [ ] **Step 5: Run tests to confirm GREEN**

Run: `cd backend && uv run pytest tests/unit/core/agentscope/test_system_prompt.py -v`
Expected: PASS


### Task 3: Remove timezone ambiguity and hidden fallbacks from calendar write

**Files:**
- Modify: `backend/src/core/agentscope/tools/utils/calendar_domain.py`
- Modify: `backend/src/core/agentscope/tools/custom/calendar.py`
- Modify: `backend/src/v1/schedule_items/schemas.py`
- Modify: `backend/src/v1/schedule_items/service.py`
- Test: `backend/tests/unit/core/agentscope/test_calendar_tools.py`
- Test: `backend/tests/unit/v1/schedule_items/test_schemas.py`
- Test: `backend/tests/unit/v1/schedule_items/test_service.py`

- [ ] **Step 1: Write failing tests for forbidden naive datetime and required timezone**

Add tests for:
- naive `start_at` rejected
- missing `event_timezone` rejected in tool path
- parse failure does not fallback to `now + 1h`

- [ ] **Step 2: Run tests to confirm RED**

Run: `cd backend && uv run pytest tests/unit/core/agentscope/test_calendar_tools.py tests/unit/v1/schedule_items/test_schemas.py -v`
Expected: FAIL on new constraints

- [ ] **Step 3: Implement strict parsing and normalization**

Implementation requirements:
- `parse_iso_datetime` rejects naive input
- remove default `Asia/Shanghai` in tool
- remove fallback auto-generated start time
- validate IANA timezone and normalize `start_at/end_at` to UTC before persistence

- [ ] **Step 4: Enforce service-level invariants**

Service invariant set:
- timezone non-empty and valid IANA
- `end_at is None or end_at >= start_at`

- [ ] **Step 5: Run backend tests**

Run: `cd backend && uv run pytest tests/unit/core/agentscope/test_calendar_tools.py tests/unit/v1/schedule_items/test_schemas.py tests/unit/v1/schedule_items/test_service.py tests/integration/test_schedule_items_routes.py -v`
Expected: PASS


### Task 4: Keep DB schema, add non-breaking constraint migration only

**Files:**
- Create: `backend/alembic/versions/20260316_000x_schedule_items_time_constraints.py`
- Test: `backend/tests/integration/test_schedule_items_routes.py`

- [ ] **Step 1: Write migration test expectation first**

Add/extend integration assertion for invalid `end_at < start_at` returning 422.

- [ ] **Step 2: Run integration test to confirm RED**

Run: `cd backend && uv run pytest tests/integration/test_schedule_items_routes.py -k end_at -v`
Expected: FAIL

- [ ] **Step 3: Implement migration with CHECK only (no new columns)**

Migration includes:
- `CHECK (end_at IS NULL OR end_at >= start_at)`

- [ ] **Step 4: Run migration + integration test**

Run: `cd backend && uv run alembic upgrade head && uv run pytest tests/integration/test_schedule_items_routes.py -v`
Expected: PASS

---

## Chunk 2: Frontend Deterministic Display and Agent Input Wiring

### Task 5: Wire device timezone into RunAgentInput forwardedProps

**Files:**
- Modify: `apps/lib/features/chat/data/services/ag_ui_service.dart`
- Modify: `apps/lib/features/chat/data/models/ag_ui_event.dart` (only if serialization helper is needed)
- Test: `apps/test/features/chat/ag_ui_event_test.dart`

- [ ] **Step 1: Write failing test for forwarded client_time payload**

Assert outgoing run request contains:
- `forwardedProps.client_time.device_timezone`
- `client_now_iso`
- `client_epoch_ms`

- [ ] **Step 2: Run test to confirm RED**

Run: `cd apps && flutter test test/features/chat/ag_ui_event_test.dart`
Expected: FAIL

- [ ] **Step 3: Implement payload injection in one place**

Add a single helper to build client time context and attach it to run input requests.

- [ ] **Step 4: Run test to confirm GREEN**

Run: `cd apps && flutter test test/features/chat/ag_ui_event_test.dart`
Expected: PASS


### Task 6: Remove implicit local-time rendering and render by event timezone

**Files:**
- Modify: `apps/lib/features/calendar/data/models/schedule_item_model.dart`
- Modify: `apps/lib/features/calendar/ui/screens/calendar_event_detail_screen.dart`
- Modify: `apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart`
- Modify: `apps/lib/features/calendar/ui/screens/calendar_month_screen.dart`
- Modify: `apps/lib/features/messages/ui/widgets/calendar_message_card.dart`
- Modify: `apps/lib/features/calendar/ui/widgets/create_event_sheet.dart`
- Test: `apps/test/features/calendar/ui/calendar_time_utils_test.dart`
- Test: `apps/test/features/calendar/ui/create_event_sheet_time_align_test.dart`

- [ ] **Step 1: Write failing tests for timezone-specific rendering**

Cover cases:
- same UTC event shows different local clock time under different `event.timezone`
- list/day/week/month are consistent for one event
- create sheet sends explicit timezone in payload

- [ ] **Step 2: Run tests to confirm RED**

Run: `cd apps && flutter test test/features/calendar/ui/calendar_time_utils_test.dart test/features/calendar/ui/create_event_sheet_time_align_test.dart`
Expected: FAIL

- [ ] **Step 3: Implement deterministic time conversion utility**

Implement one utility used by all calendar UI surfaces:
- input: UTC datetime + IANA timezone
- output: event-local datetime

Replace direct `.toLocal()` usage in calendar model/view with this utility.

- [ ] **Step 4: Enforce explicit timezone on create/update payload**

Create/update must always include `timezone` field from selected event timezone.

- [ ] **Step 5: Run Flutter tests**

Run: `cd apps && flutter test test/features/calendar/ui/calendar_time_utils_test.dart test/features/calendar/ui/create_event_sheet_time_align_test.dart`
Expected: PASS


### Task 7: End-to-end verification matrix and release checklist

**Files:**
- Modify: `docs/plans/timezone-e2e-checklist.md`
- Test: `backend/tests/integration/test_schedule_items_routes.py`
- Test: `apps/test/features/calendar/ui/create_event_sheet_time_align_test.dart`

- [ ] **Step 1: Add reproducible matrix**

Matrix axes:
- device timezone: `America/Los_Angeles`, `Asia/Shanghai`
- profile timezone: `Asia/Shanghai`, `Europe/Paris`
- explicit event timezone: `Asia/Tokyo`

- [ ] **Step 2: Run backend + frontend verification commands**

Run:
- `cd backend && uv run pytest tests/unit/core/agentscope/test_system_prompt.py tests/unit/core/agentscope/test_calendar_tools.py tests/integration/test_schedule_items_routes.py -v`
- `cd apps && flutter test test/features/chat/ag_ui_event_test.dart test/features/calendar/ui/calendar_time_utils_test.dart test/features/calendar/ui/create_event_sheet_time_align_test.dart`

Expected: all PASS

- [ ] **Step 3: Manual scenario check**

Manual script:
1. device timezone set to Los Angeles
2. profile timezone set to Shanghai
3. ask agent create "明天上午9点开会"
4. verify assistant text, tool card, DB UTC value, and calendar detail all align to chosen event timezone semantics

- [ ] **Step 4: Capture release notes**

Record:
- removed hidden timezone defaults
- deterministic precedence
- no schema expansion

---

Plan complete and saved to `docs/superpowers/plans/2026-03-16-calendar-timezone-unification.md`. Ready to execute?