Skip to content

fix: accept RFC 3339 datetimes for stale_after (OKF §5.5) - #39

Open
tuan-nng wants to merge 1 commit into
okfcli:mainfrom
tuan-nng:fix/34-stale-after-datetime
Open

tuan-nng wants to merge 1 commit into
okfcli:mainfrom
tuan-nng:fix/34-stale-after-datetime

Conversation

@tuan-nng

@tuan-nng tuan-nng commented Oct 6, 2026

Copy link
Copy Markdown

Problem

OKF v0.2 §5.5 defines stale_after as "an absolute instant" and says a concept is stale when now >= stale_after. Its example is a datetime:

stale_after: 2026-09-23T00:00:00Z   # content is stale on/after this instant

okf validate rejects that form with okf/lifecycle/stale-after-invalid ("must be an absolute YYYY-MM-DD date"), and Frontmatter.IsStale treats it as unparseable, so okf show reports stale: false for a datetime that has already passed. §11 says a validator must accept every conformant bundle.

Change

  • New concept.ParseStaleAfter accepts an RFC 3339 datetime with any offset (through the existing ParseDatetime) or a YYYY-MM-DD date. Frontmatter.IsStale and validateV02 both use it, so validation and the stale check cannot disagree.
  • A datetime is stale from that instant on. A date behaves as before: stale from 00:00 UTC of that day.
  • An unparseable value still raises okf/lifecycle/stale-after-invalid as an error. The message and the rule description now name both accepted forms: 'stale_after' must be an RFC 3339 datetime or a YYYY-MM-DD date, got "soon" (OKF §5.5).
  • The okf/lifecycle/stale warning reads now >= stale_after instead of today >= stale_after. Rule IDs, severities, commands and JSON shape are unchanged.

Tests

  • internal/concept: table-driven TestIsStale_DateAndDatetimeForms covers dates in the past, in the future and today; datetimes in the past, in the future, exactly at now and one second after; quoted datetimes; non-UTC offsets on both sides of now; and invalid values (soon, 2026-13-01, a datetime without an offset).
  • internal/validate: TestValidate_DatetimeStaleAfter checks that datetime values raise no okf/lifecycle/stale-after-invalid finding, raise the okf/lifecycle/stale warning when past and raise nothing when in the future. TestValidate_MalformedStaleAfter checks that the message names both forms.
gofmt -l . && go vet ./... && go test -race ./... && golangci-lint run ./...

All pass locally on go1.27.0. Against a bundle with stale_after: 2026-09-01T00:00:00Z (run on 2026-10-06), the built binary reports only the stale warning from validate, and okf show <bundle> <id> | jq .concept.stale prints true. With a datetime one year ahead it prints false. v0.5.0 reports stale-after-invalid for the same bundle.

Fixes #34

Drafted with Claude Code and tested locally.

OKF v0.2 §5.5 defines stale_after as an absolute instant and shows a
datetime example, but validate rejected anything but YYYY-MM-DD and the
stale check ignored datetimes. Parse both forms through one helper,
concept.ParseStaleAfter, used by IsStale and validateV02. A datetime is
stale from that instant on; a date keeps its behavior (stale from 00:00
UTC of that day).

Fixes okfcli#34

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

validate rejects the spec's own §5.5 example for stale_after (datetime), demands YYYY-MM-DD

1 participant