GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
`stale_after` comparison has no timezone anchor, so staleness depends on where a bundle is read
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
§5.5 defines staleness as a date comparison:
> Optional. An absolute date (`YYYY-MM-DD`). A concept is stale when `today >= stale_after`. An absolute date, not a relative TTL, keeps the staleness decision a plain date comparison with no reference to when the concept was read.
§10.5 step 6 makes the same comparison load-bearing:
> **Gate**: refuse to display a failing attestation; warn or refuse when `today >= stale_after`.
"today" is not defined anywhere in the document.
## Why it matters
The reasoning in §5.5 is that an absolute date removes any dependence on when the concept was read. Without a timezone it introduces a dependence on where it is read instead. A bundle carrying `stale_after: 2026-12-31` is stale in Auckland while still fresh in Los Angeles, for about 26 hours in the general case. §10.5 turns that difference into a display-or-refuse decision, so two consumers acting correctly can disagree about whether the same value may be shown.
The reference implementation resolves it silently to the consumer's local timezone. `reference_agent/bundle/document.py`:
```python
return (today or date.today()) >= stale_after
```
`date.today()` is system-local. An independent consumer has no way to know that is the intended reading, and a different choice is equally defensible from the text.
## Suggestion
Name the timezone in §5.5. UTC is the obvious candidate. It costs one sentence. If the intent is deliberately that the consumer's local date governs, saying that explicitly is just as good, because the ambiguity rather than the choice is what makes this unimplementable consistently.
Contributor guide
Research direction
Read §§5.5 and 10.5 alongside reference_agent/bundle/document.py, especially the date.today() comparison. Confirm how the specification should define “today,” then update the relevant specification text so the timezone rule is explicit and consistent with the reference behavior; done means independent consumers can make the same staleness decision.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100