Skip to content

docs(changelog): uuidv7 canonical ids entry - #154

Merged
indykish merged 4 commits into
mainfrom
chore/uuidv7-canonical-ids-changelog
Jul 23, 2026
Merged

docs(changelog): uuidv7 canonical ids entry#154
indykish merged 4 commits into
mainfrom
chore/uuidv7-canonical-ids-changelog

Conversation

@indykish

@indykish indykish commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

Companion to agentsfleet/agentsfleet#547 — the changelog entry for the identifier change that PR ships.

The API and agentsfleet CLI now reject an uppercase or mixed-case UUIDv7 instead of accepting it. Postgres folds ::uuid to lowercase while Redis dedupe keys and cache keys do not, so one entity could carry two spellings that behaved differently depending on which storage boundary it crossed.

Scope

One <Update> block, append-only — no historical entry was touched (+15 / -0 at the time of writing, rebased since onto the trimmed history from #153).

No page revisions needed. I surveyed the repo before writing: zero pages mention UUIDv7, and every UUID example across all .mdx files is already lowercase. The changelog entry is the only content this behaviour change requires here.

Land together

This should merge alongside agentsfleet/agentsfleet#547 — the entry describes behaviour that only exists once that PR ships.

Verification

make lint — exit 0 (Mintlify broken-links check clean).

🤖 Generated with Claude Code

Greptile Summary

Adds a changelog entry documenting canonical lowercase UUIDv7 identifiers.

  • Explains API and CLI rejection of uppercase or mixed-case identifiers.
  • Documents both reachable API error codes and migration guidance.
  • Notes failure behavior for clocks before the UUIDv7 representable range.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename Overview
changelog.mdx Adds the UUIDv7 canonicalization changelog entry and fully addresses the previously reported error-code, upgrade-guidance, and breaking-tag issues.

Reviews (4): Last reviewed commit: "docs(changelog): tag the canonical-id en..." | Re-trigger Greptile

Re-applies the "An identifier has exactly one spelling" entry on top of
the Jun 23, 2026 changelog trim (#153). The original edit was written
against the pre-trim 1,189-line file and could not merge cleanly, so it
is re-authored here in the trimmed voice rather than force-fitted.

Load-bearing facts carried over verbatim: the 400 status, the
ERR_INVALID_REQUEST code, the example id 0195B4BA-8D3A-7F13-…, the uuid
field name, and the pre-1970 clock failure.

Prose tightened to match the surrounding entries — the lead drops from
65 words to 52 and states the change before the prior behavior. UUIDv7
is expanded on first mention per the acronym rule.

make test passes; gitleaks clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Comment thread changelog.mdx Outdated
Comment thread changelog.mdx Outdated
indykish and others added 2 commits July 23, 2026 14:53
The bullet named ERR_INVALID_REQUEST, a Zig constant, where a reader needs
the wire code. It also missed UZ-UUIDV7-009, the dedicated identifier-shape
code already published in the error reference and returned by every route
using the shared guard. Both codes are reachable for the same input, so the
entry names both.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The entry rejects input that used to be accepted, and the changelog already
carries an Upgrading section for that class of change. Names the narrow case
that actually needs action: code that uppercases an id itself, rather than
one echoed back from the API.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Comment thread changelog.mdx Outdated
Comment thread changelog.mdx Outdated
…or codes

Two review findings on the same entry:

Breaking tag — the entry rejects input that used to be accepted, so a reader
scanning the changelog before an upgrade should see it flagged. No other entry
carries this tag yet; this one starts the vocabulary rather than leaving the
one genuinely breaking entry unmarked.

Error code — the Upgrading section named only UZ-UUIDV7-009 while the API
reference section directly above it named both that and UZ-REQ-001. Same
input, same entry, two different answers. Both sections now say both.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@indykish
indykish merged commit 2fc02f9 into main Jul 23, 2026
3 checks passed
@indykish
indykish deleted the chore/uuidv7-canonical-ids-changelog branch July 23, 2026 12:39
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.

1 participant