Skip to content
SHC Docs

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.

answerslives in
registrationwho is this customer’s cluster, across timemetadata.registration, the record’s primary key
domain-proofmay this box receive a file bound to this name, right nowthe 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:

  1. Self-serve activation would die. shc license activate with 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.
  2. The bootstrap loop would close. The broker runs as an SHC app on a vendor estate that must be licensable without the broker.
  3. 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.go resolves 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.Domains is a list and DomainMatches is 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.

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 second
3. metadata.domainPrev (only while its window is open)
4. only then, create

Order 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.

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.


pathreacheswrites
lazy, adoption on /recordanything commercially activeone metadata PATCH per legacy record, once
explicit, POST /backfill-registrationseverything elseone 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.


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.


Terms and cadences (measured, read out of the tree)

quantityvaluesource
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 termbrokerd/registration.go
reverify / refresh cron floorevery 6 hoursmodules/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)

pathlicence GETs beforeafter
mint, steady state (the hot path)22
mint, mid-cutover (a miss)1 + decline3
/record create12
/record replay, no registration sent11
/record replay, registration sent12
legacy adoption1 GET1 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.


Every guard was broken, watched to fail a named test, and restored. -count=1 throughout.

#breaktest that went red
1delete rung 2 (domain) from the ladderTestUnknownRegistrationNeverCreatesASecondRecordForAKnownDomain
2honour the wire’s registration over the record’sTestUnknownRegistrationNeverCreatesASecondRecordForAKnownDomain
3reconcile the cross-record conflict instead of refusingTestRegistrationPointingAtAnotherCustomersRecordIsRefused
4re-allocate a registration on every replayTestLegacyAdoptionCostsExactlyOneWriteThenGoesQuiet
5backfill re-identifies already-adopted recordsTestBackfillAdoptsEveryLegacyRecordAndIsFreeOnASecondRun
6remove the stale-replay guardTestStaleReplayCannotDragAnEstateBackToARetiredDomain
7mint drops the transition’s second domainTestTransitionFileCarriesBothDomainsAndVerifiesUnderEach
8treat a missing until-stamp as permanentTestTheRetiredDomainStopsResolvingOnceTheWindowLapses
9let a replay re-arm the windowTestReplayingTheDomainChangeDoesNotReArmTheWindow
10require a registration for prior proof (Alternative B)TestLegacyRecordStillRefreshesWithoutARegistration
11minter loses the prev-domain fallbackTestTransitionFileCarriesBothDomainsAndVerifiesUnderEach
12arm the backfill route without the vendor tokenTestBackfillRouteIsVendorOnlyAndUnregisteredUnlessArmed
13stop recognising an unchanged replayTestReplayOfAnUnchangedInvoiceStillWritesNothing

  • The portal does not supply the registration yet. shc/modules/portal is a feature-flagged skeleton that refuses X503145PTLNYI past 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 as registration on the first /record for 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_registration must 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.