GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

`stale_after` comparison has no timezone anchor, so staleness depends on where a bundle is read

Open Beginner friendly
#242 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.