Adopt OKF 62432a0: every timestamp is a datetime with a UTC offset - #60
Merged
Merged
Conversation
Every timestamp-valued key is now an ISO 8601 datetime with an explicit offset, and stale_after is an instant compared as now >= stale_after. Date-only values from earlier revisions still validate and are read as midnight UTC; okf/timestamp-without-offset reports them and offset-less datetimes as advisories. okf format --migrate-timestamps rewrites the date-only values, which is the one form that migrates without guessing.
leoafarias
force-pushed
the
feat/spec-62432a0-timestamps
branch
from
September 11, 2026 21:35
faaa189 to
5508064
Compare
The matrix said date-only values read as midnight UTC, which is true only for stale_after, usage_window and last_modified. generated.at and verified[].at have always required a time, so a date-only value there carries no instant; the row now says so, and notes that --strict fails on the advisory and that migrating verified[].at can change trust_tier. Adds the test that was missing for the compatibility promise: a bundle full of date-only timestamps still reports isConformant, and each field reads the way the matrix now claims. Co-authored-by: Cursor <cursoragent@cursor.com>
This was referenced Sep 11, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #56. Also completes #57, together with #59. Stacked on #59: review and merge that first, and this PR will retarget to
main.Upstream 62432a0 (PR #323) makes every timestamp-valued key an ISO 8601 datetime with an explicit UTC offset (
generated.at,verified[].at,stale_after,sources[].last_modified,usage_window).stale_afterbecomes an instant, and a concept is stale whennow >= stale_after.Validation (advisories only; conformance is unchanged)
okf/timestamp-without-offsetadvisory. It flags date-only values, with the exact rewrite and a pointer to the migration, and datetimes that have no offset. The finding names the location, such assources[0].last_modified.okf/invalid-stale-afterandokf/invalid-usage-windowaccept datetimes. Date-only values are still accepted there, so a bundle written for the old revision gets one migration advisory rather than two findings.okf/invalid-stale-after(seetest/spec_rules/rule_test.dart).Metadata (behavior change)
staleAfter,lastModifiedand theusage_windowboundaries parse full instants. Date-only values are read as midnight UTC.isStale/isStaleOncompare instants instead of local calendar days. Before,stale_after: 2026-09-23meant "from local midnight"; it now means2026-09-23T00:00:00Z, which is what the migrated value says. The parameter is renamed fromtodaytonow, which doesn't affect callers because it is positional.Migration
okf format --migrate-timestampsrewrites date-only values toYYYY-MM-DDT00:00:00Zand lists each change (Migrated alpha.md: stale_after 2026-09-23 -> 2026-09-23T00:00:00Z). It works with--check.okf formatnever changes a timestamp's value.Docs: the README and
docs/conformance-matrix.mdmove the pin from 3fcbb9f to 62432a0 and add §5 and §5.5 rows.Release: the
isStalesemantics change suggests 0.5.0. I haven't added a CHANGELOG entry, because the first## <version>section feeds release notes; it will be added with the release.Checks:
dart analyze --fatal-infosis clean anddart testpasses (225 tests).test/ci/gate_test.darthas formatter drift that is already onmain; I didn't touch it here.