Registration is the durable identity, 2026-08-16
Status: RULED by the owner on 2026-08-16 and IMPLEMENTED in this
change. The ruling accepts the recommendation in
2026-08-16-marketplace-entitlement-and-licensing.md
§2.2 and closes its Q1. Everything below marked (measured) was read
or counted out of the tree today; nothing here is an estimate.
“let’s just go straight through the registration approach then instead of domains since we’re shifting more into that approach anyway.” (owner, 2026-08-16)
0. The ruling is narrower than the sentence
Section titled “0. The ruling is narrower than the sentence”Registration became the primary key. Domain-proof was not deleted.
| answers | lives in | |
|---|---|---|
| registration | who is this customer’s cluster, across time | metadata.registration, the record’s primary key |
| domain-proof | may this box receive a file bound to this name, right now | the DNS/cert/nonce callback, and the domain compare inside the signed file |
Deleting domain-proof was Alternative B in §2.3 and was refused there for three reasons this change honours in code:
- Self-serve activation would die.
shc license activatewith no key, no account and no portal produces a licensed estate today. Requiring a registration first makes the portal a hard dependency for entitlement, not just for the marketplace. - The bootstrap loop would close. The broker runs as an SHC app on a vendor estate that must be licensable without the broker.
- Vendor-outage resilience would go. Offline verification is what makes a multi-week vendor outage a “customers can’t grow” event rather than an outage. The binding inside the signed file must stay a domain, because a domain compare is the only thing an airgapped verifier can evaluate with no network.
So the runtime check is unchanged: License.DomainMatches(SHC_HOST),
exact, normalized, offline. TestSteadyStateFileStillBindsToExactlyOneDomain
pins it.
1. What was already there, wearing another name
Section titled “1. What was already there, wearing another name”Nothing here is new machinery. /refresh already treated the licence
id as a continuity credential: an estate that names the licence it
holds, whose domain still carries that exact licence in the system of
record, skips the domain-control callback. Both halves required:
domain alone would let any estate refresh any domain’s licence, id alone
would let a moved or revoked licence keep refreshing on the estate it
left.
That pair is a registration identifier. It is precisely the fact “this is the same cluster we sold to, across time”. So it was promoted rather than duplicated:
- HasLicenseRecord(ctx, domain, licenseID) bool+ RegistrationFor(ctx, domain, licenseID) (registration string, ok bool)The predicate is byte-for-byte the same. It now yields the identity it
was implicitly testing. ok is still the gate; the registration is what
the gate learned, and it is logged on the skip so an operator can follow
one cluster across a rename instead of losing the thread at it.
The registration is an OUTPUT, never an INPUT. A record that predates
this change has none, and still refreshes:
TestLegacyRecordStillRefreshesWithoutARegistration. Requiring one would
have been Alternative B by the back door: every existing estate silently
loses its callback skip and starts re-proving domain control every six
hours.
2. Two false problems, already dissolved (measured)
Section titled “2. Two false problems, already dissolved (measured)”- “A cluster has several domains” is false for SHC’s own entitlement.
modules/license/domain.goresolves the estate serving domain to ONE cluster-scoped fact. It remains a real problem for the app-licence plane, which this change does not touch. - “The format only holds one domain” is false.
License.Domainsis a list andDomainMatchesis a membership test (modules/license/license.go:322); both minters merely only ever emitted a single-element list. That is what made the dual-domain transition file cost nothing.
3. The expensive part: idempotency
Section titled “3. The expensive part: idempotency”POST /record’s idempotency was keyed on metadata.domain; “replaying
the same invoice event finds the record it created last time and updates
it in place”. That single property is what stops a double charge
becoming a double grant.
It is preserved by making the lookup a ladder, not a swap
(brokerd/record.go, resolveRecord):
1. metadata.registration (when the request names one)2. metadata.domain <- the old key, still second3. metadata.domainPrev (only while its window is open)4. only then, createOrder is load-bearing in both directions. Registration first is the ruling. Domain second is the safety: the moment a registration miss fell through to a create, a caller sending a registration we have never seen would mint a SECOND record for a domain that already has one: one invoice, two grants, and the mint path would then serve whichever Keygen returned first.
A registration resolving to one record while the domain resolves to a
different one is refused (X400972LICREQ). Every other reading of
that writes somebody’s rights onto somebody else’s record.
The one honest degradation
Section titled “The one honest degradation”A record written before this change carries no registration, so its first
/record after it writes once to adopt it. The documented property
degrades from:
a replayed unchanged invoice writes nothing
to:
a replayed unchanged invoice writes nothing, except the single adoption write that converts a legacy record, once
That is convergence, not accumulation (which is what the Recorder
contract requires), and it is proven, not asserted, by
TestLegacyAdoptionCostsExactlyOneWriteThenGoesQuiet: the second replay
issues zero POSTs and zero PATCHes.
No staged path was needed. The migration preserves idempotency in one step because adoption happens in place on the record the domain rung already found. At no point can a second record exist for one estate.
4. The migration, with a deadline
Section titled “4. The migration, with a deadline”| path | reaches | writes |
|---|---|---|
lazy, adoption on /record | anything commercially active | one metadata PATCH per legacy record, once |
explicit, POST /backfill-registrations | everything else | one metadata PATCH per legacy record, once |
The explicit path exists for the records adoption never reaches: a
lapsed record a returning customer’s reactivation must find rather than
duplicate, an airgapped record whose invoices are handled out of band,
and an internal estate on a perpetual record that by construction never
receives another paid invoice. Leaving those unadopted would make the
seam “mostly migrated” forever, which is the tiersync.go failure
exactly: a projection with no projector looks exactly like a projection
that is up to date.
The backfill performs one kind of write: a metadata-only PATCH on an
existing record. It never creates a licence, moves a term, changes a
tier, or touches an entitlement; TestBackfillNeverCreatesOrRetiersARecord.
A second run reports everything skipped and writes nothing.
It is deliberately not run at boot the way SyncTiers is. SyncTiers
projects a table this binary compiles in, so rolling the image genuinely
is the sync. A backfill allocates identity, and identity allocated
implicitly on every replica start is identity nobody decided to create.
5. Domain changes, and the window
Section titled “5. Domain changes, and the window”Paste the estate’s registration onto the first invoice carrying the new
domain. The record is found by registration and metadata.domain is
updated in place: the licence id, the invoice chain (metadata.invoice,
the audit link back to the money) and the metadata.note override
history all survive. The retired name goes to metadata.domainPrev with
an RFC3339 metadata.domainPrevUntil deadline.
While the window is open the minted file carries both names, so the
estate is never unlicensed during the cutover, and the mint lookup falls
back to metadata[domainPrev] so an estate that has not yet flipped
SHC_HOST still mints. This is what §2.4 called cheap, and it is: no
format change, no new verifier, no daemon release.
Four bounds, each held by a named test:
- a prev-domain with no until-stamp has no force; a half-written
transition reads as “not in force”, never as permanent
(
TestAHalfWrittenTransitionHasNoForce); - once the window lapses the retired name resolves to nothing and the
next mint drops it (
TestTheRetiredDomainStopsResolvingOnceTheWindowLapses); - a replay does not re-arm the window; otherwise a billing system
retrying hourly would keep the retired name alive forever
(
TestReplayingTheDomainChangeDoesNotReArmTheWindow); - a stale, out-of-order invoice cannot drag a live estate back onto a
name it has left; a paid-through date behind the record’s is refused
(
TestStaleReplayCannotDragAnEstateBackToARetiredDomain).
The exposure, stated plainly. Inside the window, proving control of
either name yields a file naming both. Accepted, not engineered away:
both names sit on ONE record with ONE invoice chain so there is no
cross-customer leak, the transition can only be started by an
authenticated POST /record, and the alternative (honouring only the
name that was proven) reintroduces exactly the self-inflicted lapse
§2.3 describes.
A domain change without a registration is treated as a brand-new
customer, because it is indistinguishable from one
(TestADomainChangeWithoutARegistrationIsANewCustomer). Inferring “same
cluster” from anything weaker would be a join with no projector.
6. Measured numbers, not adjectives
Section titled “6. Measured numbers, not adjectives”Terms and cadences (measured, read out of the tree)
| quantity | value | source |
|---|---|---|
rolling file term (defaultRollingTTL) | 35 days (840h) | brokerd/keygen.go:23 |
overage file term (overageTTL) | 35 days (840h) | brokerd/keygen.go:110 |
| domain transition window (new) | 35 days, deliberately one rolling term | brokerd/registration.go |
| reverify / refresh cron floor | every 6 hours | modules/license/crons.go (license.reverify) |
The window equals one file term on purpose: an estate that mints once inside the window is covered for both names right up to the point the window closes, and the very next mint is single-domain again.
Keygen call budget (measured, counted against the stateful mock)
| path | licence GETs before | after |
|---|---|---|
| mint, steady state (the hot path) | 2 | 2 |
| mint, mid-cutover (a miss) | 1 + decline | 3 |
/record create | 1 | 2 |
/record replay, no registration sent | 1 | 1 |
/record replay, registration sent | 1 | 2 |
| legacy adoption | 1 GET | 1 GET + 1 PATCH, once |
The customer-facing hot path (the one the 6-hourly cron drives for every
estate) did not grow. The extra lookup is reached only on a miss,
which is the one case that was previously a lost customer. Pinned as a
regression guard by TestTheSeamCostsOneExtraKeygenCallAndOnlyOnAMiss.
7. Mutation proofs
Section titled “7. Mutation proofs”Every guard was broken, watched to fail a named test, and restored.
-count=1 throughout.
| # | break | test that went red |
|---|---|---|
| 1 | delete rung 2 (domain) from the ladder | TestUnknownRegistrationNeverCreatesASecondRecordForAKnownDomain |
| 2 | honour the wire’s registration over the record’s | TestUnknownRegistrationNeverCreatesASecondRecordForAKnownDomain |
| 3 | reconcile the cross-record conflict instead of refusing | TestRegistrationPointingAtAnotherCustomersRecordIsRefused |
| 4 | re-allocate a registration on every replay | TestLegacyAdoptionCostsExactlyOneWriteThenGoesQuiet |
| 5 | backfill re-identifies already-adopted records | TestBackfillAdoptsEveryLegacyRecordAndIsFreeOnASecondRun |
| 6 | remove the stale-replay guard | TestStaleReplayCannotDragAnEstateBackToARetiredDomain |
| 7 | mint drops the transition’s second domain | TestTransitionFileCarriesBothDomainsAndVerifiesUnderEach |
| 8 | treat a missing until-stamp as permanent | TestTheRetiredDomainStopsResolvingOnceTheWindowLapses |
| 9 | let a replay re-arm the window | TestReplayingTheDomainChangeDoesNotReArmTheWindow |
| 10 | require a registration for prior proof (Alternative B) | TestLegacyRecordStillRefreshesWithoutARegistration |
| 11 | minter loses the prev-domain fallback | TestTransitionFileCarriesBothDomainsAndVerifiesUnderEach |
| 12 | arm the backfill route without the vendor token | TestBackfillRouteIsVendorOnlyAndUnregisteredUnlessArmed |
| 13 | stop recognising an unchanged replay | TestReplayOfAnUnchangedInvoiceStillWritesNothing |
8. What is still owed
Section titled “8. What is still owed”- The portal does not supply the registration yet.
shc/modules/portalis a feature-flagged skeleton that refusesX503145PTLNYIpast the flag. Until it exists, the broker allocates the registration itself on first record, ERPNext carries it forward scoped by customer and domain, and a rename is a human paste. When the portal lands it should send the cluster id asregistrationon the first/recordfor a registered cluster; a claim on a record that already carries one is ignored in favour of the record, so nothing can be rewritten from the wire. - Registration is still not load-bearing at runtime, exactly as §2.5 warns. The daemon has no registration-aware entitlement path. This change makes registration the primary key of the record; the signed file still binds to a domain, and must, for §0’s third reason.
custom_shc_registrationmust be created on Sales Invoice as an “Allow on Submit” Data field before the ERPNext script writes it back.- The app-licence plane (decision §5.3, several domains per record) is untouched here.