Releasing a sub-organization, and recovering its first-customer invitation
Who this guide is for: RESELLER PARTNERS (a designated reseller business that provisions sub-organizations) and the operators watching them. Release is an administrator action; recovery can be done by any active seat of the reseller.
Two journeys, both built on one promise: relationships change, records never lie.
- Release — end the reseller relationship with one provisioned sub-organization, detaching it cleanly while preserving everything the customer owns.
- First-customer invite recovery — when a sub-org's one-time first-customer invitation was revoked, expired, or its code lost, re-arm the same single invitation with a fresh one-time code.
Every organization, seat, invite and contact in the runs behind this guide is synthetic. No provider, payment, or production action of any kind occurred. These journeys were exercised at their database seam — the release and recovery engine functions, run over a real ordinary (NOSUPERUSER, NOBYPASSRLS) PostgreSQL 16 cluster with FORCE RLS — which is the exact engine the partner screens drive. A later supplementary browser run also drove both journeys through the real screen (see the final section); its honest standing — including the SHA-bound journey's FAILED entry expectation — is stated there and in the evidence section.
Evidence record (kept for honesty)
(The body above is customer guidance; the receipts below are the internal record.)
Two suites of the FULL3747-PG lane, each on its own fresh dedicated throwaway PostgreSQL 16 cluster, on the combined candidate:
- Suite 6 —
partner-release.test.ts: 7/7 passed (2026-10-24T23:22:11Z → 23:22:26Z, exit 0), verbatim receipttools/zcode-integration3723/runtime/FULL3747-PG/logs/06-partner-release.tap. - Suite 7 —
first-customer-recovery.test.ts: 8/8 passed (2026-10-24T23:22:44Z → 23:22:58Z, exit 0), receiptlogs/07-first-customer.tap. - Both green again on a second independent fresh-PG cycle
(
c2-06-partner-release.tap7/7,c2-07-first-customer.tap8/8; lane ledger "CYCLES 1+2 COMPLETE AND GREEN", 2026-10-24T23:44:30Z,C:/CT-ZCODE-FULL3747/lane-pg-ledger.json; logs in the PG lane worktreeC:/CT-ZC-FULL3747, git-ignored). - Browser journey 3 — honest status: FAILED at its entry expectation, with
the substance separately proven. The SHA-bound journey
partner release and invitation recovery remain separate, explicit actionsexpected the partner screen's entry to raise the privileged authenticator prompt; the mounted candidate deliberately serves the partner ledger read (GET /v1/reseller/sub-orgs) at member-scopeanalytics:read(an API probe without the factor header answered200), so no entry prompt exists — the real elevation point is the child selection (the invitation-state read iscampaigns:write-gated). A supplementary run (SUP-J3, recorded as supplementary evidence, not the SHA-bound spec) drove the same real screen through that actual flow and passed end-to-end (see the final section). The design question is reported as defect FULL3747-B-02 (decision needed; the lane changed neither the backend nor the SHA-bound spec). Ledger:C:/CT-ZCODE-FULL3747/lane-browser-ledger.json.
Evidence standing: combined-candidate, local evidence; Chief acceptance and publication are OPEN. Earned shares referenced below are the frozen, immutable statement lineage keyed by provisioning provenance — no share is recomputed or rewritten by either journey.
Part 1 — Releasing a sub-organization
Who may release, and what is refused
Release is an admin-seat action of the releasing reseller, always with
a reason and a caller-chosen request id. The refusal matrix the run proved
— every refusal a PARTNER_RELEASE_* error with a proper status, and every
refusal leaving every original relationship byte-identical:
| Situation | Refusal |
|---|---|
| A non-admin seat tries | refused |
| The reseller's designation is disabled | refused |
| The child belongs to a different reseller | refused |
| The target was never provisioned under this reseller | refused |
| The reason is blank/whitespace | refused |
| The child still has its own descendants (a subtree) | 409 PARTNER_RELEASE_SUBTREE_NOT_EMPTY — release inner orgs first |
What a successful release changes — and what it never touches
The run released one provisioned child and verified, in storage:
- Changed: the relationship only — the child's parent link becomes empty. The child is independent.
- Preserved untouched: the child's customer data (its contacts, row-for-row identical); the provisioning provenance — the original provisioning record stays exactly as it was, because earned-share statement lineage is keyed to it; and every already-earned share.
- Revoked selectively: the unused first-customer invite capability of this relationship dies. A sibling's already-consumed capability is untouched — only the unused capability of the released relationship is withdrawn.
- No counterfeit exit: the customer's own exit path stays a separate capability — the run proved no customer-exit record was fabricated by the release.
- Attributed audit: exactly one audit event (
reseller.sub_org_released) under the releasing reseller's tenant, naming the request id.
Replay, races, and crashes
- Replaying the exact original request returns the same receipt
with
changed: false— and still exactly one release row. Idempotent. - A different request id for the same released child is refused
(
409 PARTNER_RELEASE_ORIGINAL_CONFLICT) — you cannot release twice under a new pretext. - Two concurrent releases with the same original: exactly one
transition happens; both callers receive the same receipt (one
changed: true, onechanged: false). - A crash mid-transaction rolls back completely — relationship intact, no receipt row.
Receipts are immutable and isolated
- The ordinary application role holds SELECT only on the release receipts — DELETE and UPDATE are refused; even the cluster superuser cannot UPDATE a receipt (an immutability trigger refuses it).
- Tenant isolation: another reseller's pin reads the same child as
independentwith no receipt, and lists zero releases. The release list caps at 100 rows per page (asking for 101 is a400).
Part 2 — Recovering a first-customer invitation
Each provisioned sub-org has exactly one first-customer invitation — a one-time capability with a hashed token and an expiry. Recovery re-arms that same row; it never creates a second invitation.
What is refused — and the original stays byte-identical
| Situation | Refusal |
|---|---|
| Inactive seat, or no seat at all | refused |
| The child was already released/detached | refused |
| Another reseller's invite | refused |
| A consumed invitation | refused — a claimed capability is never recoverable |
| An occupied child (it already has customer data) | refused |
| The right child but a wrong invite id | 404 FIRST_CUSTOMER_INVITE_NOT_FOUND — not a rotation |
After every refusal, the invitation row's token hash, revoked/consumed stamps were re-read unchanged.
A successful recovery, exactly
For a revoked invitation, recovery returned:
recovered: true, the same invite id, a fresh one-time token (43-character web-safe shape, new expiry ahead), the claim path (/v1/identity/first-customer), and deliverycapability-returned-once— the token is shown exactly once, at recovery, to the recovering seat;- still exactly one invitation row for the child;
- the row now hashes the new token, with revoked/consumed stamps cleared and a fresh expiry;
- the old capability is dead at the exact seam the claim path uses — the consumer lookup finds zero rows for the old token and exactly one for the new one. The old token dies at the same instant the new one is issued;
- one attributed audit event (
reseller.first_customer_invite_recovered) under the reseller's tenant.
An expired invitation re-arms the same way (state returns to
unused), and so does a live-unused one — rotating a live-unused
capability invalidates the never-shared old token too, so a possibly-leaked
token cannot outlive its replacement.
Read states, races, crashes, boundaries
- The read seam reports honest states:
revokedbefore recovery (recovery available),unusedafter,consumedflagged unrecoverable. - Concurrent recoveries serialize: still one row; both rotations commit in sequence; at the end exactly one live capability — the final hash — while the original and the intermediate token are both dead.
- A mid-transaction crash rolls the rotation back completely — the old hash and its revoked stamp intact.
- The ordinary role cannot rotate columns directly — direct UPDATEs of the token hash or expiry are refused by the grant boundary; rotation happens only through the recovery engine.
- Any active seat of the reseller (a member seat is enough — the same authority as issuing) may recover; a deactivated seat may not.
Both journeys through the real screen — supplementary proof (SUP-J3)
The browser lane's supplementary run drove both parts of this guide as a reseller lives them, in real Chromium on the same mounted candidate:
- Entry raises no factor prompt — the partner ledger view is a member-scope read (the honest recorded behavior, and the reason the SHA-bound journey 3 failed at its entry expectation; see the evidence section).
- Selecting the child raises the real prompt. The first privileged read — the invitation state behind the selected child — is factor-gated, and its refusal surfaces the product's authenticator prompt at selection time.
- With the factor held, both cards read back live state: the invitation
state, and the release state reading
linked. - Release through the screen: confirm, type the reason, submit — one
POST …/reseller/sub-orgs/{child}/release, answered 200, with the release receipt rendered. - Recovery of the released relationship is refused on screen: after the release, asking for invitation recovery answers 404 with the error rendered — the "child already released/detached" refusal of Part 2, visible to the user — and no capability input is shown at all (there is nothing to re-arm).

The screenshot is a byte-exact capture of the supplementary passing run (SHA256 and provenance in assets/ASSETS-MANIFEST.json). It is supplementary evidence — the SHA-bound journey 3 remains FAILED at its entry expectation and defect FULL3747-B-02 stays open. A small related UI fix (
46fb35c8, partner cards' read-error re-read path) lives on the browser lane's branch, not on this guide branch's base. All data is synthetic.