Attention Trends: the window moves every day, so every cached artefact is keyed to a date

[ssdavidai]

The TRENDS tab computes its window at page load:

const [trendsFrom] = useState(thirteenWeeksAgo);  // today − 91 days
const [trendsTo]   = useState(now);               // today

So the requested window shifts by one day, every day. Two consequences, one already worked around and one still latent.

Worked around (#643). Alfred's read is stored against the exact grain:from:to key and joined by exact match, so a weekly schedule would have written a key matching only one day in seven. The schedule is daily for that reason alone — not because a daily refresh is otherwise wanted. That is a cadence chosen to compensate for an unstable key.

Still latent — timezone. The workflow derives to from workflow.now() (UTC) while the browser derives it from local time. At 04:00 local these agree for most offsets, but not all: at UTC+13, 04:00 local is the previous day in UTC, and the pre-computed read would be keyed one day off and never display. Home is UTC+2 so this does not bite today; it would on a far-east tenant.

The better fix is to stop the window moving: snap it to period boundaries — the last N complete weeks/months/quarters plus the current partial one. That would give a stable key, let the schedule fire on a natural cadence, remove the timezone hazard entirely, and stop the chart shifting subtly between page loads on the same data.

It would also mean the displayed window no longer silently changes underneath a reader comparing two visits.

Not urgent. The current arrangement works on every tenant in the fleet. Filed so the daily cadence is not mistaken for a considered choice about refresh frequency.

Related: #584.

[github-actions]

This issue is missing prioritization dimensions, so it will not
appear correctly in Now/Next/Later portfolio views.

#644 Attention Trends: the window moves every day, so every cached arte
    missing:     kind, impact, effort, priority, horizon, customer, theme, area

0/1 open issues fully classified.

Rubric: docs/ISSUE-TAXONOMY.md

[ssdavidai]

Foreman specification — canonical Attention Trends windows

Research findings

The moving key is encoded in both sides of the current contract:

• packages/web/src/dashboard/AttentionPage.tsx initializes trendsFrom to today - 91 days and trendsTo to today, then sends the exact dates to getAttentionTrends and interpretAttentionTrends.
• packages/learn/src/workflows/attention_trend_read.py deliberately reproduces that rolling 91-day window from workflow.now().date() when the schedule supplies only grain.
• packages/learn/scripts/register_schedules.py therefore registers al-attention-trend-read daily at 04:00 tenant-local time with {"grain":"week"}. Existing tests explicitly defend the daily workaround.
• Trend reads are identified by the exact attention_trend:<grain>:<from>:<to> subject, so a one-day shift creates a different cached artefact rather than refreshing the one the browser asks for.

The replacement must make the date range a canonical function of (grain, tenant-local calendar date), not an elapsed-day lookback.

LANES

Lane A — shared browser window contract

Add a pure, testable window derivation in the web trends core and use it to initialize/recompute the TRENDS request dates.

Canonical inclusive windows:

• week: 13 complete ISO weeks plus the current ISO week (from Monday 13 weeks before the current week; to Sunday of the current week).
• month: 3 complete calendar months plus the current month (from first day three months before; to last day of current month).
• quarter: 1 complete calendar quarter plus the current quarter (from first day of previous quarter; to last day of current quarter).

This preserves the present approximately-13-week horizon and approximately the same point counts (14 weekly, 4 monthly, 2 quarterly periods), while keeping the key stable throughout the selected period. Recompute the canonical window when grain changes. Use calendar-date arithmetic; do not round-trip through UTC timestamps in a way that shifts the browser's local date.

Lane B — workflow parity and tenant timezone

Replace _window_for_grain's rolling 91-day implementation with the same boundary rules. The scheduled workflow must derive its reference date in the tenant schedule timezone, not from UTC workflow.now().date().

Propagate the IANA timezone used by ScheduleSpec.time_zone_name into the workflow args (for example {"grain":"week","timezone":"Europe/Budapest"}), validate it, and derive the local calendar date deterministically. Explicit button/API calls that provide both from and to remain authoritative and unchanged.

Lane C — natural schedule cadence

Change al-attention-trend-read from daily to weekly, once per ISO week at 04:00 tenant-local time (Monday is preferred so the new current-week key exists at the start of the period). Keep overlap/retry policy unchanged. Update schedule registration tests so they defend weekly cadence, timezone propagation, and a single idempotent schedule entry rather than the old rolling-key workaround.

Lane D — regression coverage and documentation

Update stale module comments/tests that claim the TRENDS window is today - 91 days → today. Add contract tests on both TypeScript and Python sides for ordinary dates, month/quarter/year boundaries, leap years, and a far-east timezone such as Pacific/Auckland or Pacific/Kiritimati.

CONTRACTS

1. deriveTrendsWindow(grain, referenceLocalDate) returns ISO YYYY-MM-DD inclusive boundaries and is pure.
2. For any two reference dates in the same grain period, the returned (from,to) pair is identical.
3. Browser and scheduled workflow return the same pair for the same grain and tenant-local calendar date.
4. week uses ISO Monday–Sunday boundaries; month and quarter use calendar boundaries.
5. The API/read identity remains exact grain:from:to; no fuzzy cache lookup, alias key, or migration of historical observations is introduced.
6. Explicit requests with both from and to continue to use those exact values. Supplying only one still raises the existing validation error.
7. Invalid/missing scheduled timezone fails clearly or uses the already-validated tenant timezone source; it must not silently fall back to host UTC.
8. Grain changes in the UI update the canonical dates before fetching or generating Alfred's read.

Acceptance criteria

• Reloading TRENDS on different days in the same week produces the same default weekly request key.
• Switching to monthly or quarterly produces the canonical windows above and stable keys within that month/quarter.
• A tenant at UTC+13/UTC+14 gets the same scheduled key that its browser requests at 04:00 local, including on Monday and period boundaries.
• The scheduled read runs weekly, not daily, and its payload carries enough timezone context to avoid workflow.now() UTC drift.
• Existing manually generated reads remain discoverable for their exact historical keys; no destructive rewrite occurs.
• Web unit tests, learn workflow tests, and schedule-registration tests pass.
• The PR includes a ## Smoke evidence section.

Smoke plan

1. Run the focused TypeScript trends-core test command documented in attentionTrendsCore.test.ts and add cases asserting the exact ranges for a mid-week date, New Year ISO week, leap-February month, and quarter rollover.
2. Run pytest for packages/learn/tests/test_attention_trend_read.py, including browser/workflow parity fixtures and Pacific/Kiritimati Monday-boundary coverage.
3. Exercise schedule-entry construction for at least Europe/Budapest and Pacific/Kiritimati; assert weekly day-of-week, 04:00 local, timezone name, grain, and workflow timezone arg.
4. In a browser/dev smoke, open TRENDS on two simulated dates within one week and confirm the network request and generated-read subject are identical; switch grains and confirm the documented canonical ranges.