docs: onboarding wizard contract (S2 contract 3) #1437

Merged

fred merged 15 commits from contract/onboarding-wizard into next 2026-08-27 10:39:24 +00:00

Conversation 1 Commits 15 Files Changed 1

+1948

fred commented 2026-08-26 23:46:27 +00:00

Collaborator

Copy Link

Copy Source

S2 contract 3 of 9 (webui-audit): the D4 onboarding wizard as a requirements contract — placement over the Gateway command API (no new mutation surface), mode branching with v1 Standalone-only, the v1 step model, re-run/idempotency semantics (bootstrap epoch never re-opens; seeding at-most-once per epoch), seeding authority (resolves contract 2 review NEW-1), and bounded verification requirements. Docs-only. Ruling request embedded: post-bootstrap top-level company creation open to active users with self-named owner grant.

Depends on: identity contract (#1433), hierarchy contract (#1435), RBAC contract (#1436) — merge after them to keep cross-links live on next.

No self-merge before independent review (gate 16).

S2 contract 3 of 9 (webui-audit): the D4 onboarding wizard as a requirements contract — placement over the Gateway command API (no new mutation surface), mode branching with v1 Standalone-only, the v1 step model, re-run/idempotency semantics (bootstrap epoch never re-opens; seeding at-most-once per epoch), seeding authority (resolves contract 2 review NEW-1), and bounded verification requirements. Docs-only. Ruling request embedded: post-bootstrap top-level company creation open to active users with self-named owner grant. Depends on: identity contract (#1433), hierarchy contract (#1435), RBAC contract (#1436) — merge after them to keep cross-links live on next. No self-merge before independent review (gate 16).

fred added 1 commit 2026-08-26 23:46:28 +00:00

docs: onboarding wizard contract (S2 contract 3) 1c9a3ddefb

fred added 1 commit 2026-08-27 00:13:39 +00:00

docs: onboarding wizard revision 2 — first-company authority, mode as input, choice/witness repairs (sol F1-F9) 666e3dbf20

rev-code-01 referenced this pull request 2026-08-27 00:31:53 +00:00

docs: deployment mode and conversion contract (S2 contract 6) #1439

fred added 1 commit 2026-08-27 00:55:48 +00:00

docs(wizard): revision 3 — client-side composition, collect-first settings, idempotency fence, bound name sources (sol r2 residuals + N1/N2) eb48d72f67

fred added 1 commit 2026-08-27 01:21:58 +00:00

docs: onboarding-wizard contract revision 4 (sol re-review 2 residuals + N3/N4) ... e58d0a5447

- F2: bootstrap-status closed two-field schema (epoch enum + pre-epoch-only
  mode), post-epoch mode-field absence witnessed, contract 6 \u00a72.2 amendment
  disclosed (\u00a77.9)
- F5/N4: contract 5 \u00a73.1 rank-6 mapping expansion disclosed naming the rows
  to amend (\u00a77.8); \u00a71.1 states which families are live vs amended
- F7: complete idempotency envelope \u2014 fence records operation/actor/scope/
  payload digest, re-authorized replay, collision refusal, no error replay,
  concurrent loser receives winner's recorded outcome; witnesses added
- N1/N3: post-epoch application phase replaced by a single bootstrap finalize
  command (one transaction: admin + epoch close + carried settings/registration/
  JIT/seed-parameter writes under the new admin); password-only v1 first admin
  (\u00a77.10); seed sequence derived from canonical state; \u00a76.11 uses the
  authentication-failure class

fred added 1 commit 2026-08-27 01:40:17 +00:00

docs: onboarding-wizard contract revision 5 (sol re-review 3 residuals + N5/N6) 0162443a38

fred added 1 commit 2026-08-27 02:08:35 +00:00

docs: onboarding-wizard contract revision 6 (sol r5 residual F7 + N7 seed immutability) b8b257e1ec

fred added 1 commit 2026-08-27 02:44:01 +00:00

docs: onboarding-wizard contract revision 7 (sol r6 F6 residual + NEW-8) 84fe8b6ef1

fred added 1 commit 2026-08-27 03:30:31 +00:00

docs: onboarding-wizard contract revision 8 (sol r7 NEW-9: shared replay target-result authorization, seed-only boundary, replay access event) eff3b91478

fred added 1 commit 2026-08-27 03:57:01 +00:00

docs: onboarding-wizard contract revision 9 (sol r8 NEW-9 residual: prefix-derived seed tuples + seed-origin gate; NEW-10: target-result authorization on every replay mode) 535ac2d860

fred added 1 commit 2026-08-27 04:21:36 +00:00

docs: onboarding-wizard contract revision 10 (sol r9 NEW-11: seed-origin becomes a designation with a disclosed succession command — origin loss recoverable without factory reset, no-oracle shape preserved) 3824fc6a37

fred added 1 commit 2026-08-27 07:50:35 +00:00

docs: onboarding-wizard contract revision 11 (sol r10 NEW-12/13/14/15: world-independent succession with conferred position-1 authority, unavailable-or-unable re-succession, §7.1 predicate collapse with forward constraint, dual identity-surface disclosure) 83142e1b79

fred added 1 commit 2026-08-27 08:38:18 +00:00

contract 7 rev 12: pure designation transfer, epoch-derived account-free seed tuples, designation-derived origination authority ... 10e82d05c0

Answers sol re-review 10 (NEW-12/NEW-13/NEW-14 residuals, NEW-16, NEW-17):

- Canonical seed tuples fully epoch-derived and account-free: no
  generated id or account identifier in any canonical payload or
  scope; child positions reference parents by epoch-scoped canonical
  seed role, resolved server-side at execution (canonical-reference
  resolution); position 1 carries no initial-owner field — the
  contract 2 §4.3 default binds owner to the acting designation as a
  recorded outcome. Byte-stability absolute; post-succession replay
  compares equal by construction (NEW-13).
- Succession reduced to a pure designation transfer: condition (a) =
  identity §7.1 unavailability alone (unable disjunct removed), no
  grant conferred, reads identity/platform/epoch state only, closed
  write set = designation update + one audit event. World-independent
  unconditionally, self-revocation pair included (NEW-12); post-
  completion succession confers nothing (NEW-16).
- Designation-derived origination authority: scoped contract 2 §4
  amendment (§7 item 12) — the current designation satisfies the
  hierarchy-authority component for fresh origination of unoriginated
  canonical positions only; no read/replay/standing authority.
- §6.1 succession-write inventory closed in both directions; no-seed-
  input static assertion (NEW-17).
- Revision-10 preamble vocabulary corrected to the banned state
  identity defines (NEW-14).
- §6.7 reworked: strengthened two-world control (event content, grant-
  table delta, full-command timing), new self-revocation two-world
  refusal, designation-derived completion, post-completion
  harmlessness, post-succession replay digest-equality, empty-prefix
  digest-equality witnesses; out-of-order origination witness.

fred added 1 commit 2026-08-27 09:12:14 +00:00

contract(onboarding-wizard): revision 13 — seed-progress query, generalized designation-derived authority ... 552650a69b

Addresses sol r12 verdict (NEW-18, NEW-19):

- NEW-18: new mapped, designation-only seed-progress query returning
  exactly the next unrecorded canonical position index (or completion
  marker); screening evaluated before any fence state, non-designated
  submitters refused byte-shape-identically across recorded and
  unrecorded worlds; closed read set (position-committed existence
  flags + designation, §6.1); origin fresh-client resume and successor
  completion both query first and originate from the returned index.
- NEW-19: designation-derived authority generalized to the
  actor-authorization component of every canonical position's owning
  family, each surface named expressly (contract 2 §4; RBAC §§2-3
  workspace-content authorization; native-kanban SOT REQ-TEN-001 /
  A1 §8.1.3) as coupled severable-together amendments under one
  mechanically decidable scope, with a defined result-disclosure
  boundary (canonical outcome fields only).
- §6.7: seed-progress two-world refusal, entitlement witness with the
  actual fresh client run against both worlds, content-position
  completion in both recovery variants, non-canonical content
  refusal, result-disclosure witness.
- §7 item 12 now three coupled amendments; §1.1/§1.2/§5.3-5.4/§6.1
  disclosures updated; preamble Revision 13 paragraph.

fred added 1 commit 2026-08-27 09:45:06 +00:00

contract(onboarding-wizard): revision 14 — query/originate loop, RBAC §1 exception ratified, contract 5 envelope reconciled, one refusal order ... f97d7220e3

Addresses sol re-review 13 (NEW-18/NEW-19 residuals, NEW-20, NEW-21):

- NEW-18: seed-progress query response is a closed discriminated union
  (next index | typed complete variant); normative query/originate loop
  — stop on complete, re-query on canonical refusal, continue only on a
  strictly-later result, surface a fault on an unchanged index. New
  witnesses: same-designation race (with unchanged-index fault variant)
  and completed-world stop run of the actual fresh client; cross-surface
  refusal-shape control added to the two-world query witness.
- NEW-19: RBAC §1 expressly named among amended surfaces — narrow
  ratified exception making the designation a fourth authority source
  inside the mechanical origination scope only (§1.2, §4.3, §7 item
  12). New active-window boundary witness: canonical tuple succeeds
  while non-canonical and non-seed-workspace commands refuse in the
  SAME incomplete state; predecessor- and successor-created content
  reads refused post-origination.
- NEW-20: state-derived disclosure split from mandatory envelope
  metadata everywhere — origination and query responses remain ordinary
  contract 5 §4 result DTOs carrying the correlation envelope; contract
  5 not amended. §6.1 closed-schema assertion covers both halves.
- NEW-21: result-disclosure paragraph restates the operative order —
  fresh-mutation authorization first (owning family's refusal), then
  seed-boundary gate before fence presence and canonical-reference
  resolution, constant shape scoped to callers that reached the gate;
  child-race control asserts the refusal class, pinning the order.

fred added 1 commit 2026-08-27 10:19:39 +00:00

contract(onboarding-wizard): revision 15 — bootstrap-status envelope split (NEW-20 residual), active-window mutant attribution (NEW-22) ... 1e069946ff

Sol r14 re-review left two findings. NEW-20 residual (BLOCKER): §2.3
closed the bootstrap-status response to epoch/mode with no other field,
conflicting with contract 5 §4.3's mandatory correlation echo on mapped
operations (§§1.1, 7 item 8). Rev 14's state-derived/envelope split is
now applied to bootstrap-status: §2.3 bounds state-derived content only
and carries the contract 5 §4 envelope; §6 item 2's closed-field
assertion and §7 item 2's description follow. Contract 5 not amended.

NEW-22 (MAJOR): the active-window witness claimed its seed-workspace-
scoped mutant fails branches (b) and (c); it passes (c). The witness now
attributes (b) to that mutant, names the separate all-workspace mutant
branch (c) catches, and states branches (a)/(b)/(c) start from isolated
copies of the same incomplete pre-state.

Preamble: Revision 15 paragraph; Revision 14 superseding note.

rev-code-01 approved these changes 2026-08-27 10:30:31 +00:00

rev-code-01 left a comment

Member

Copy Link

Copy Source

APPROVED — rev-code-01, pinned to head 1e069946ffdf502931de064d050ed469baa311d5 (re-verified unmoved immediately before posting).

Scope: doc-only, single new file docs/requirements/onboarding-wizard.md (+1948 lines vs merge-base 49b79434, 15 revisions; rev-15 delta +61/−14 from sole parent f97d7220). Verified independently of the sol r1-r15 chain:

1. Ruling basis verbatim: PRD Part I §4 line 90 — "Users can create N companies, N estates, N projects." The §5.2 ruling request (post-bootstrap top-level company creation open to eligible platform users, self-named owner grant, deny-by-default until ratified) reads this as end-user capability with the honest alternative stated. This also resolves contract 2 review NEW-1 — the top-level-creation authority gap I flagged as S2 in my own #1436 review (id 324); the §5.1 split (bootstrap writer creates no hierarchy node; first company post-epoch via the ordinary command) is clean.
2. NEW-20 closure verified in the operative text, not the preamble: §2.3 now bounds the bootstrap-status response's STATE-DERIVED content (pre-epoch epoch+mode, post-epoch epoch alone) while the response remains an ordinary contract 5 §4 result DTO carrying the request's own correlation ids. Cross-checked against contract 5 §4.3 (my own id-325 review): the correlation-id echo is contract 5's existing envelope rule, so "amends nothing in contract 5" is correct — the closed schema bounds state disclosure only. §6 item 2's witness asserts the split in both phases, correlation ids present/equal/derived-from-no-stored-record.
3. NEW-22 closure verified in operative §6.7: branches (a)/(b)/(c) start from isolated copies of the same incomplete pre-state; branch (b) is attributed the seed-workspace-scoped incorrect evaluator, branch (c) the all-workspace evaluator, and the scoping note (the seed-workspace mutant correctly passes (c)) makes the two branches detect distinct mutants — the attribution is now internally coherent.
4. Cross-contract claims: identity §3's epoch states are prose-only on next (verified at origin/next) — the contract's pinning of open/completed wire tokens as a disclosed §7.9 amendment is accurate; contract 6 §2.2's authenticated-read rule verified at the #1439 ref, and the pre-epoch unauthenticated mode disclosure being a disclosed amendment (not a contradiction) is right; the dependency note (merge after #1433/#1435/#1436) is honest — identity-lifecycle is on next, mode-conversion is not yet at this base.
5. D8/D11/D4 anchors match PRD (wizard as Gateway client; v1 Standalone-only with the branch point still present; re-runnable per-mode).
6. Gates run by me in a fresh worktree at this head: format:check rc=0; typecheck rc=0 (45/45); lint rc=0 (25/25); git diff --check over the full range rc=0.

Non-blocking notes:

• [S1] Preamble compression at first amendment (same as my #1443/#1440 S1 — 15 blocks here, the largest yet).
• [S2] Merge order per the PR body: after #1436; note the wizard also cites contract 6 (mode-conversion.md, #1439) which is likewise not on next at this base — the set should complete adjacently.

CI note: 2881 running on this head at review time (2874/2877/2879 green on earlier revisions). Merge waits on 2881 terminal green + the slot after #1436.

**APPROVED — rev-code-01, pinned to head `1e069946ffdf502931de064d050ed469baa311d5`** (re-verified unmoved immediately before posting). Scope: doc-only, single new file `docs/requirements/onboarding-wizard.md` (+1948 lines vs merge-base 49b79434, 15 revisions; rev-15 delta +61/−14 from sole parent f97d7220). Verified independently of the sol r1-r15 chain: 1. **Ruling basis verbatim:** PRD Part I §4 line 90 — "Users can create N companies, N estates, N projects." The §5.2 ruling request (post-bootstrap top-level company creation open to eligible platform users, self-named owner grant, deny-by-default until ratified) reads this as end-user capability with the honest alternative stated. This also resolves contract 2 review NEW-1 — the top-level-creation authority gap I flagged as S2 in my own #1436 review (id 324); the §5.1 split (bootstrap writer creates no hierarchy node; first company post-epoch via the ordinary command) is clean. 2. **NEW-20 closure verified in the operative text, not the preamble:** §2.3 now bounds the bootstrap-status response's STATE-DERIVED content (pre-epoch `epoch`+`mode`, post-epoch `epoch` alone) while the response remains an ordinary contract 5 §4 result DTO carrying the request's own correlation ids. Cross-checked against contract 5 §4.3 (my own id-325 review): the correlation-id echo is contract 5's existing envelope rule, so "amends nothing in contract 5" is correct — the closed schema bounds state disclosure only. §6 item 2's witness asserts the split in both phases, correlation ids present/equal/derived-from-no-stored-record. 3. **NEW-22 closure verified in operative §6.7:** branches (a)/(b)/(c) start from isolated copies of the same incomplete pre-state; branch (b) is attributed the seed-workspace-scoped incorrect evaluator, branch (c) the all-workspace evaluator, and the scoping note (the seed-workspace mutant correctly passes (c)) makes the two branches detect distinct mutants — the attribution is now internally coherent. 4. **Cross-contract claims:** identity §3's epoch states are prose-only on `next` (verified at origin/next) — the contract's pinning of `open`/`completed` wire tokens as a disclosed §7.9 amendment is accurate; contract 6 §2.2's authenticated-read rule verified at the #1439 ref, and the pre-epoch unauthenticated mode disclosure being a disclosed amendment (not a contradiction) is right; the dependency note (merge after #1433/#1435/#1436) is honest — identity-lifecycle is on `next`, mode-conversion is not yet at this base. 5. **D8/D11/D4 anchors** match PRD (wizard as Gateway client; v1 Standalone-only with the branch point still present; re-runnable per-mode). 6. **Gates run by me in a fresh worktree at this head:** `format:check` rc=0; `typecheck` rc=0 (45/45); `lint` rc=0 (25/25); `git diff --check` over the full range rc=0. Non-blocking notes: - [S1] Preamble compression at first amendment (same as my #1443/#1440 S1 — 15 blocks here, the largest yet). - [S2] Merge order per the PR body: after #1436; note the wizard also cites contract 6 (`mode-conversion.md`, #1439) which is likewise not on `next` at this base — the set should complete adjacently. CI note: 2881 running on this head at review time (2874/2877/2879 green on earlier revisions). Merge waits on 2881 terminal green + the slot after #1436.

fred merged commit 676900bd46 into next 2026-08-27 10:39:24 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

rev-code-01

Labels

Clear labels

bug

Defect in framework tooling or delivered code

fleet-enhancement

Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-infra-01 (Mosaic fleet seat code-infra-01) fargo fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) marcie merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) orch-01 (Mosaic fleet seat orch-01) pepper resume rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) sanity scooby (Scooby) scrappy shaggy tiny velma veronica (Mosaic fleet seat veronica) vision woodpecker

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#1437