Repository navigation
Conversation
okfctl parsed stale_after (Node.StaleAfter, Node.IsStale) but no command
reported it, and the age-based freshness signals can't see a declared
expiry on a recently generated node. analyze now lists every node with
now >= stale_after in freshness.expired ({path, stale_after}, always an
array) and a "past stale_after" section of the human report.
It stays a report entry: analyze exits 0, and no validate or lint rule is
added, so a date passing never turns a gate red (§11 soft guidance). An
absent or unparseable stale_after is silent.
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
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.
Summary
okfctl analyzenow warns about every node whose §5.5stale_afterdate has passed, so a bundle's declared recheck dates surface in the curation report instead of being parsed and ignored.analyze report
freshness.expiredlist: one{path, stale_after}entry per node wherenow >= stale_after(§5.5), printed as "Freshness — past stale_after (§5.5, recheck)". It needs no threshold, because the producer chose the date.analyzeexits 0 as before. Novalidateorlintrule is added, so a date passing never turnslint --strictred with no change to the bundle (§11: everything beyond the floor is soft guidance).next quartercarries no instant to compare.okf (
internal/okf/)analyze.go: addsExpiredNodeandFreshnessReport.Expired, fills it from the existingNode.IsStale, and normalises it to[]likestaleandtime_sensitive.analyze_expired_test.gocovers a past date (listed, with its value, and kept out of the age-basedstalelist), the exact instant (listed, per>=), negatives (future, one second ahead, absent, unparseable) and the JSON shape ("expired":[]).cmd (
cmd/)analyze.go: prints the new section in the human report.analyze_test.goaddsTestAnalyzeCmd_ExpiredStaleAfter_Section5_5, which checks the past node in both human and JSON output, the future node absent, and exit 0.docs
2026-11-04-analyze-expired-stale-after.md(docs/specs/): the problem, the decision (report, not gate) and the controls.CHANGELOG.md: Unreleased / Added entry.Evidence
Spec: upstream
GoogleCloudPlatform/open-knowledge-formatSPEC.md, header confirmed**Version 0.2**. Sections cited:§5.5:
stale_afteris optional, and a concept is stale whennow >= stale_after.§11: consumers SHOULD derive staleness only from the fields specified, and treat other constraints as soft guidance.
Before:
Node.IsStaleexisted, with conformance tests, but no command called it. A node generated yesterday withstale_afterlast month appeared in no list.After: that node is listed under
freshness.expiredand nowhere else.Gate layer 1:
go test ./internal/okf/ ./cmd/ -run Conformance, both packagesok.Gate layer 2:
gofmt -l .is empty andgo vet ./...is clean.go test ./...has 15 failures, all Windows-only and all outside this change: plugin install and discovery, dispatch,node editwith$EDITOR, and git clone/pull. The same 15 fail onfork/nextwithout this change.go test ./... -racein CI'sbuild-testjob (Linux): every packageok, including the 15 Windows-only tests that fail locally. It wasn't run locally, because the Windows machine has no C compiler.Gate layer 3, real corpus: the four market-fr bundles, base binary vs this branch.
The only
stale_afterin the corpus is in the future (2027-03-31), soexpiredis 0 everywhere. Positive control on a copy of nf525-lne: backdating one concept to an instant (2026-01-01T00:00:00Z) and another in the corpus's date-only form (2026-03-31) lists exactly those two, andvalidatestill prints OK.v0.1 bundle: legacy
timestamp, a body# Citationslist, one past and one futurestale_after.validateprints OK with both binaries.stalelist is identical (none).Merge Danger
Door: two-way
Blast Radius: analyze output
analyze --jsongains afreshness.expiredkey. A consumer that decodes into a strict schema with unknown keys rejected would need the field. Existing keys are unchanged.Not in this PR: a
lintcheck for passedstale_after(deliberately left out, see above), and any change to how the age-basedstalelist is computed.