canon: envelope-time-fields principle (tier-2 draft)#129
Merged
Conversation
Names the two-clocks rule for oddkit envelopes: - server_time is request time, always current per response - debug.generated_at is content-addressed BaselineIndex provenance First application will be oddkit 0.22.0 aligning every canon-reading tool's debug.generated_at upward to index.generated_at, removing the field-name ambiguity surfaced by the 2026-04-20 regression test. Challenged in canon-tier-2 mode before submission; draft addresses confidence, prior art (HTTP Date vs Last-Modified), three considered alternatives, costs/risks, and retraction condition. Ships as status: draft; graduates to active on third deciding-argument recurrence per cache-fetches-and-parses template.
klappy
pushed a commit
that referenced
this pull request
Apr 20, 2026
…elease-validation-gate Closeout ledger for the oddkit 0.22.0 ship cycle (PRs #124, #125, #127, #128, #129). First post-canon application of release-validation-gate (tier 1, landed earlier today in P1.3.3). Documents the retroactive-closure pattern used to heal PR #127's validation gap without reverting, and names the four criteria that make retroactive closure legitimate. Key contents: - Summary of what shipped (two envelope-conformance fixes into 0.22.0) - D3 names the retroactive-closure pattern and its four legitimacy criteria - Timeline of all agent/validator sessions with evidence trail - L2 distinguishes feature-branch validators from promotion-PR validators under canon's strict reading - L3 captures the Managed-Agent-bypass workaround for orchestrator-IP rate limits - H2 carries forward P11 (oddkit_gate mechanical enforcement of release-validation-gate) Writing canon gate satisfied: blockquote with compressed argument, Summary section, descriptive headers. Encoded via oddkit_encode (governance_source: knowledge_base) — 18 DOLCHE artifacts folded into D/O/L/C/H sections.
This was referenced Apr 20, 2026
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.
What
Adds a new tier-2 canon principle:
canon/principles/envelope-time-fields.md.Names the rule that every oddkit response carries two distinct clocks:
server_timeat envelope root = request time (always current per response)debug.generated_atin debug = content-addressed BaselineIndex provenance (tied to canon SHA)Why this ships now
The 2026-04-20 regression-test sweep of oddkit v0.21.0 found
debug.generated_atincatalogforty-eight minutes behindserver_time. Initial diagnosis: stale cache. Reading canon reversed the diagnosis:catalogwas the only tool doing it right — propagating the content-addressed index provenance perodd/constraint/anti-cache-lying. Every other canon-reading tool echoed request time under the same field name, hiding the content-freshness signal content-addressed caching exists to expose.The bug was ambiguity, not staleness. This canon names the rule so future tools do not silently reintroduce the collision.
Tier and stability
Ships
tier: 2 status: draftwith one application in hand (upcoming oddkit 0.22.0). Graduates tostatus: activeon third deciding-argument recurrence per thecache-fetches-and-parsestemplate (graduation through deciding-argument count, not appearance count).Challenge
Drafted, challenged in canon-tier-2 mode via oddkit, revised to address:
Scope
Single file add. No cross-reference backfill in this PR — the new doc declares its own
derives_fromandcomplements; reciprocal links into existing canon can land in a later housekeeping sweep.First application
Immediately followed by a klappy/oddkit PR aligning every canon-reading tool's
debug.generated_attoindex.generated_at, removing the field-name ambiguity this canon describes. That PR will cite this canon as its load-bearing reason.Note
Low Risk
Documentation-only change adding a new canon principle; low implementation risk, though it may influence future envelope semantics and downstream expectations.
Overview
Adds a new tier-2 draft canon principle,
canon/principles/envelope-time-fields.md, standardizing envelope timestamp semantics across oddkit-pattern responses.It explicitly separates request-time (
server_time, always current per response) from content provenance (debug.generated_at, pinned to the content-addressed index build time) and forbids emittingdebug.generated_atfor tools that don’t read canon to avoid ambiguous freshness signals.Reviewed by Cursor Bugbot for commit 5e0e7de. Bugbot is set up for automated code reviews on this repo. Configure here.