From c197bb24dbaa9954c0c50a0369e7dbe3a4a2fca1 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Thu, 23 Jul 2026 13:16:39 +0530 Subject: [PATCH 1/4] docs(changelog): uuidv7 canonical ids entry, rebased on trimmed history MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- changelog.mdx | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/changelog.mdx b/changelog.mdx index 02dbf52..df9588e 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -7,6 +7,21 @@ description: "Stay up to date with the latest agentsfleet product updates, new f agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner. + + ## An identifier has exactly one spelling + + Every workspace, fleet, and event id is a lowercase Universally Unique Identifier version 7 (UUIDv7). An uppercase id used to be accepted, and the two spellings could then drift apart: the database read one record, while caches, deduplication keys, and plain string comparisons read two. The API and the `agentsfleet` CLI now reject a non-lowercase id. + + ## API reference + + - **Uppercase and mixed-case ids return `400`** — a request sending `0195B4BA-8D3A-7F13-…` where a `uuid` field is expected now fails with `ERR_INVALID_REQUEST` instead of being silently normalized. Every id the API returns is already lowercase, so anything echoing back a server-issued id is unaffected. + - **The CLI rejects the same shape** — `agentsfleet` checks id arguments before the request leaves your machine, so a miscased id fails immediately, not after a round trip. + + ## Bug fixes + + - **A clock outside the representable range fails loudly** — minting an id on a host whose clock is set before 1970 now returns an error, instead of an id whose embedded timestamp is corrupted and sorts in the wrong place. + + ## A struggling fleet explains itself From cc7758f681afdad5fa49db8431fe1424225c41b5 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Thu, 23 Jul 2026 14:53:20 +0530 Subject: [PATCH 2/4] docs(changelog): name the uuidv7 error code the API actually emits 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) --- changelog.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog.mdx b/changelog.mdx index df9588e..f9f76c2 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -14,7 +14,7 @@ description: "Stay up to date with the latest agentsfleet product updates, new f ## API reference - - **Uppercase and mixed-case ids return `400`** — a request sending `0195B4BA-8D3A-7F13-…` where a `uuid` field is expected now fails with `ERR_INVALID_REQUEST` instead of being silently normalized. Every id the API returns is already lowercase, so anything echoing back a server-issued id is unaffected. + - **Uppercase and mixed-case ids return `400`** — a request sending `0195B4BA-8D3A-7F13-…` where a `uuid` field is expected now fails with [`UZ-UUIDV7-009`](/api-reference/error-codes) instead of being silently normalized. Routes that validate the id inline answer the generic [`UZ-REQ-001`](/api-reference/error-codes) for the same input, so handle both. Every id the API returns is already lowercase, so anything echoing back a server-issued id is unaffected. - **The CLI rejects the same shape** — `agentsfleet` checks id arguments before the request leaves your machine, so a miscased id fails immediately, not after a round trip. ## Bug fixes From 900ad2b2e12542bf6a47a553516aceadfffb797a Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Thu, 23 Jul 2026 15:57:10 +0530 Subject: [PATCH 3/4] docs(changelog): add upgrade guidance for the canonical-id change 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) --- changelog.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/changelog.mdx b/changelog.mdx index f9f76c2..c8d8b1c 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -17,6 +17,10 @@ description: "Stay up to date with the latest agentsfleet product updates, new f - **Uppercase and mixed-case ids return `400`** — a request sending `0195B4BA-8D3A-7F13-…` where a `uuid` field is expected now fails with [`UZ-UUIDV7-009`](/api-reference/error-codes) instead of being silently normalized. Routes that validate the id inline answer the generic [`UZ-REQ-001`](/api-reference/error-codes) for the same input, so handle both. Every id the API returns is already lowercase, so anything echoing back a server-issued id is unaffected. - **The CLI rejects the same shape** — `agentsfleet` checks id arguments before the request leaves your machine, so a miscased id fails immediately, not after a round trip. + ## Upgrading + + - **Lowercase any identifier your code stores or builds itself.** Ids handed back by the API and the CLI are already lowercase, so echoing one straight back needs no change. Action is only required where your code uppercases an id, reads one from a system that upper-cases (some spreadsheet and logging pipelines do), or hard-codes one in a fixture or webhook URL. Those requests now fail with [`UZ-UUIDV7-009`](/api-reference/error-codes) rather than being accepted. + ## Bug fixes - **A clock outside the representable range fails loudly** — minting an id on a host whose clock is set before 1970 now returns an error, instead of an id whose embedded timestamp is corrupted and sorts in the wrong place. From 5e69fb0a30569f6eb15d705c387dd5e0232d7179 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Thu, 23 Jul 2026 18:02:42 +0530 Subject: [PATCH 4/4] docs(changelog): tag the canonical-id entry Breaking and pin both error codes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- changelog.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/changelog.mdx b/changelog.mdx index c8d8b1c..4a73504 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -7,7 +7,7 @@ description: "Stay up to date with the latest agentsfleet product updates, new f agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner. - + ## An identifier has exactly one spelling Every workspace, fleet, and event id is a lowercase Universally Unique Identifier version 7 (UUIDv7). An uppercase id used to be accepted, and the two spellings could then drift apart: the database read one record, while caches, deduplication keys, and plain string comparisons read two. The API and the `agentsfleet` CLI now reject a non-lowercase id. @@ -19,7 +19,7 @@ description: "Stay up to date with the latest agentsfleet product updates, new f ## Upgrading - - **Lowercase any identifier your code stores or builds itself.** Ids handed back by the API and the CLI are already lowercase, so echoing one straight back needs no change. Action is only required where your code uppercases an id, reads one from a system that upper-cases (some spreadsheet and logging pipelines do), or hard-codes one in a fixture or webhook URL. Those requests now fail with [`UZ-UUIDV7-009`](/api-reference/error-codes) rather than being accepted. + - **Lowercase any identifier your code stores or builds itself.** Ids handed back by the API and the CLI are already lowercase, so echoing one straight back needs no change. Action is only required where your code uppercases an id, reads one from a system that upper-cases (some spreadsheet and logging pipelines do), or hard-codes one in a fixture or webhook URL. Those requests now fail with [`UZ-UUIDV7-009`](/api-reference/error-codes), or [`UZ-REQ-001`](/api-reference/error-codes) on routes that validate the id inline, rather than being accepted. ## Bug fixes