From 3824fc6a37ab68972bb29d8462bb6594dfcefddc Mon Sep 17 00:00:00 2001 From: fred Date: Wed, 26 Aug 2026 23:21:33 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20onboarding-wizard=20contract=20revision?= =?UTF-8?q?=2010=20(sol=20r9=20NEW-11:=20seed-origin=20becomes=20a=20desig?= =?UTF-8?q?nation=20with=20a=20disclosed=20succession=20command=20?= =?UTF-8?q?=E2=80=94=20origin=20loss=20recoverable=20without=20factory=20r?= =?UTF-8?q?eset,=20no-oracle=20shape=20preserved)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/requirements/onboarding-wizard.md | 133 +++++++++++++++++++++---- 1 file changed, 114 insertions(+), 19 deletions(-) diff --git a/docs/requirements/onboarding-wizard.md b/docs/requirements/onboarding-wizard.md index 187846ee..e82de41c 100644 --- a/docs/requirements/onboarding-wizard.md +++ b/docs/requirements/onboarding-wizard.md @@ -179,6 +179,24 @@ outcome references, actor equality remaining an additional condition, never a substitute — a creator whose grants were revoked is refused, not replayed (NEW-10; §6.7 lost-target-grant witness). +Revision 10 (sol re-review 8: NEW-11): the seed-origin boundary becomes +recoverable without breaking the no-oracle result. The epoch's +seed-origin is a **designation** the finalize fixes to the first admin, +changed through exactly one disclosed command — **seed-origin +succession** (§4.3, §7 item 12): an eligible platform admin holding +target-result read authority on the committed seed prefix succeeds only +while the current origin fails identity §7.1 eligibility; refusals keep +the constant conflict shape whatever condition failed and whatever is +recorded, concurrent successions serialize on the epoch record, the +change is one audited epoch-record mutation, and recorded fence rows +immutably retain their original actor. The seed-boundary gate and the +origination rule read the epoch record's current designation, so a +banned or deleted origin no longer strands the unoriginated suffix — +the successor resumes and completes it with no factory reset and no new +epoch, restoring D4 re-runnability and §4.4's strand-nothing rule +(NEW-11; witnesses §6.7: succession recovery, origin-available refusal, +succession race). + Scope: the Gateway-backed product onboarding wizard. Out of scope: the host-local install wizard (`mosaic wizard`, which drives host install and gateway bootstrap and is not this artifact — audit REPORT.md layer 3); @@ -417,7 +435,9 @@ the named authority: epoch's §4.3 seed-origin account — as actor, naming the admin as initial `owner` in the same audited operation (contract 2 §4.3); the §4.3 seed-boundary gate reserves - origination of the canonical seed tuples to that account, while + origination of the canonical seed tuples to the epoch's current + seed-origin account — initially this admin, thereafter changed + only by §4.3 seed-origin succession — while the same command outside the canonical seed key set follows §5.2 unchanged. The initial estate, initial project, and initial workspace with seeded example data (D4, D11) follow through hierarchy @@ -551,11 +571,13 @@ collects no sensitive category, so v1 ships no custody surface. can carry a shared declaration, so no shared fence row can exist outside the seed sequence — the seed-only rule is enforced by the command layer, not by wizard convention. - - **Seed-boundary gate and origination.** The epoch has one - immutable **seed-origin account**: the account the §3.3 - finalize transaction created as the epoch's first admin - (identity §3) — provenance the epoch record fixes at finalize - and nothing changes afterwards. Every mutating submission + - **Seed-boundary gate and origination.** The epoch record holds + one **seed-origin designation**: at finalize it names the + account the §3.3 finalize transaction created as the epoch's + first admin (identity §3), and afterwards it changes through + exactly one path — the **seed-origin succession** command below + — never by any other write. The epoch's **seed-origin account** + is the account the designation currently names. Every mutating submission whose (operation, key) is in the canonical seed key set — whatever replay mode it declares — passes, after fresh-mutation authorization and before the fence table is @@ -582,14 +604,46 @@ collects no sensitive category, so v1 ships no custody surface. eligibility plus the hierarchy authority the command itself requires); a refused submission records no row (no-error replay below). The recorded actor of every shared row is - therefore the seed-origin account, authorized for the mutation - the row fences. If the seed-origin account is banned or - deleted while seed positions remain unoriginated, those - positions are unoriginatable for this epoch — an accepted - consequence of the immutable boundary; factory reset (§4.2), - which opens a new epoch with a new first admin, is the - recovery path. Recorded positions are unaffected: any admin - holding target-result read authority replays them (§6.3). + therefore the account that was the epoch's seed-origin at that + position's origination, authorized for the mutation the row + fences. Recorded positions are replayable by any admin holding + target-result read authority (§6.3). + - **Seed-origin succession.** Loss of the seed-origin account + does not strand the epoch (D4, §4.4). The designation changes + through exactly one mutating command, an amendment to identity + §3's epoch surface disclosed in §7 item 12: an eligible + platform admin — passing §5.2 fresh-mutation authorization in + full — submits succession naming itself the epoch's + seed-origin. The command succeeds only when, evaluated against + canonical state inside the succession transaction itself: + (a) the current seed-origin account fails identity §7.1 + eligibility (banned, deleted, or disabled) — succession while + the current origin remains eligible is refused — and (b) the + submitter holds §4.3 target-result read authority on every + canonical record referenced by the recorded outcomes of the + committed seed prefix (vacuously satisfied while no position + is committed). A submission failing either condition is + refused with the same single constant-shape bounded conflict + as the seed-boundary gate, byte-shape-identical whichever + condition failed and whether any seed fence exists — so + succession adds no existence oracle (witness §6.7) — executes + nothing, and appends no event. Successful succession updates + the designation in the epoch record and appends one ordinary + mutation audit event recording the prior designation, the new + designation, and the acting principal; it rewrites no fence + row and no recorded outcome — rows already recorded immutably + retain their original actor. Concurrent successions serialize + on the epoch record: exactly one submitter commits and becomes + the seed-origin, and the loser, re-evaluated against the + committed winner, fails condition (a) — the now-current origin + is eligible — and receives the constant-shape refusal. The + seed-boundary gate and the origination rule always read the + epoch record's current designation: after succession the + successor originates the remaining suffix in order under its + own full fresh-mutation authorization, and the fence rows it + originates record the successor. Factory reset (§4.2) remains + the only path to a new epoch; it is never required to complete + an interrupted seed sequence. - **No error replay.** The fence row commits only with its mutation, so only committed outcomes are ever recorded. A failed or refused submission records no fence row; a retry executes @@ -651,7 +705,11 @@ collects no sensitive category, so v1 ships no custody surface. already-committed mutations return their recorded outcomes, and only the remainder executes, without duplication and without compensating rollback of completed commands. There is no - wizard-level transaction spanning steps. + wizard-level transaction spanning steps. Loss of the seed-origin + account mid-sequence is likewise recoverable without a new epoch: + §4.3 seed-origin succession designates an eligible successor, and + the resumed run completes the remaining suffix under the successor + — interrupted runs strand nothing even across origin-account loss. ## 5. Seeding authority (resolves contract 2 review NEW-1) @@ -916,7 +974,30 @@ Binding on the implementing PRs: re-granting the creator read authority and resubmitting returns the recorded outcome — proving actor equality is never a substitute for live target-result read authority on any replay - mode; a submission that failed before commit + mode; **seed-origin succession witnesses (§4.3, NEW-11):** a + **succession recovery** — the seed-origin account commits a + proper seed prefix and is then banned (identity §7.1); an + eligible platform admin holding target-result read authority on + the committed prefix submits succession, the epoch record's + designation changes to the successor with exactly one mutation + audit event recording the prior designation, the new + designation, and the acting principal, and the successor's + resumed run replays the committed prefix (its access attributed + by §4.3 replay access events) and originates the remaining + suffix in order — the new fence rows record the successor, the + pre-succession rows immutably retain the original origin, and + the full seed set completes with no factory reset and no new + epoch; an **origin-available succession refusal** — the same + eligible admin submits succession while the current origin + remains §7.1-eligible — is refused with the single + constant-shape bounded conflict (asserted byte-shape-identical + to the collision refusal), changes no epoch record, and appends + no audit event; a **succession race** — with the origin banned, + two eligible, prefix-authorized admins submit succession + concurrently: the epoch record serializes them, exactly one + commits and becomes the designated origin with one audit event, + the loser receives the constant-shape refusal, and the seed + sequence completes exactly once under the winner; a submission that failed before commit leaves no fence row and its retry executes; two concurrent resumed runs executing the seed sequence yield exactly one seed set — per key, exactly one mutation and one mutation audit event exist, and @@ -1011,9 +1092,11 @@ contracts and are not additions: outcomes — with a shared declaration outside the key set, off its position's derived tuple, or past the next unrecorded position refused recording nothing (§4.3). Including the - **seed-boundary gate**: the epoch's immutable seed-origin - account is the first admin the finalize transaction created; - every submission on a canonical seed key must be that account + **seed-boundary gate**: the epoch's seed-origin designation + initially names the first admin the finalize transaction + created and changes only through item 12's succession command; + every submission on a canonical seed key must be the currently + designated account or hold target-result read authority on the position's recorded targets, refused otherwise with the constant-shape conflict evaluated before fence presence — so recorded and unrecorded @@ -1070,6 +1153,18 @@ contracts and are not additions: provenance for §3.4's derivation; the current company name lives on the company row and changes only through the ordinary hierarchy rename (§3.1, witnesses §6.3). +12. The **seed-origin succession command** (§4.3) — an amendment to + identity §3's epoch surface, proposed and ratified here, + severable: one mutating command that redesignates the epoch's + seed-origin to an eligible platform admin holding target-result + read authority on the committed seed prefix, valid only while + the current origin fails identity §7.1 eligibility; refusals + are the constant-shape §4.3 conflict regardless of which + condition failed, the change is one audited epoch-record write + serialized on the epoch record, and recorded fence rows are + never rewritten. Without this amendment a banned or deleted + seed-origin account strands the unoriginated seed suffix, + contradicting PRD D4's no-lock-in requirement (§4.4). ## Ruling request