docs(api): distinguish globally-unique id from MAX+1 external_key (TRA-885)#202
Merged
mikestankavich merged 3 commits intoMay 30, 2026
Conversation
…xternal_key Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
… external_key Ticket text is stale (Mike confirmed); source of truth is the bb-253 round-2.5 convergence. id is globally unique/opaque/permanent; external_key auto-mint is MAX(live key)+1, not lowest-unused-slot. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
… to MAX+1 (TRA-885) - id-format.md: scope the distribution claim to the surrogate id (high-entropy, globally unique, opaque, permanent/never-reused); add an id-vs-external_key note. - resource-identifiers.md: surrogate-key section now states global uniqueness (no cross-type id equality) + opaque/permanent; auto-mint corrected from 'lowest unused slot' to MAX(live key)+1 (permanent middle-delete gaps, only highest-freed reused, zero-padded). - changelog.md: new entry for both clarifications; fix stale 'lowest unused slot' assertions in the LOC-NNN and BB52 non-monotonic entries. Source: bb-253 round-2.5 convergence; platform-confirmed (assets.go:60 / locations.go:57 = MAX(live)+1). id global uniqueness backed by TRA-886 (single shared sequence). Ticket text superseded per Mike. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
|
🚀 Preview Deployment Update ✅ This PR has been successfully merged into the preview branch. The preview environment will update shortly at: https://docs.preview.trakrf.id |
Deploying docs with
|
| Latest commit: |
ef7ca6e
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://434fcd37.docs-4n7.pages.dev |
| Branch Preview URL: | https://miks2u-tra-885-docs-distingu.docs-4n7.pages.dev |
mikestankavich
deleted the
miks2u/tra-885-docs-distinguish-distributed-surrogate-id-from-sequential
branch
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.
TRA-885 — distinguish the globally-unique surrogate
idfrom theMAX+1external_keyConsumer-docs prose fix sharpening the line between the two identifier tiers. The original
blur (the id-format page called "the id" randomly distributed without naming the field) let
the random-distribution property bleed onto
external_key, which produced a false contractfinding in round 2.4/2.5.
What changed
docs/api/id-format.md— the distribution sentence now names the field: the surrogateidis high-entropy, globally unique across every resource type, opaque, and permanent(never reused — no hard delete, shared id sequence never reseeded). Added a
:::notepinningid≠external_key.docs/api/resource-identifiers.md— the "Numericidis a surrogate key" section nowstates global uniqueness (no cross-type id equality) + opaque/permanent. The
external_keyauto-mint mechanism is corrected from "lowest unused slot / gap-filling" to
MAX(live key) + 1: permanent middle-delete gaps, only the current highest live key's number freedfor re-issue, zero-padded
ASSET-%04d/LOC-%03d.docs/api/changelog.md— new entry for both clarifications; fixed the stale "lowestunused slot" assertions in the existing
LOC-NNN-finalize and BB52 non-monotonic entries.Source of truth
The TRA-885 ticket text is stale (confirmed by Mike — substantial post-ticket
investigation). Authoritative wording is the bb-253 round-2.5 §0 convergence:
idglobal uniqueness — operator-confirmed; backed by TRA-886 (PR fix(db): TRA-886 — single shared sequence for surrogate ids platform#443,Done — collapses to one shared sequence → globally unique by construction).
external_key=MAX(live key) + 1— platform code-confirmed (assets.go:60GetNextAssetSequence,locations.go:57GetNextLocationSequence) and independentlycode-read here.
Verification
pnpm buildpasses (Redocusaurus + broken-link check; all new anchors resolve).except where quoted-as-corrected in the new changelog entry; every distribution/allocation
claim names its field.
🤖 Generated with Claude Code