Skip to content

docs: unified start API design (0.9) - #259

Merged
unbalancedparentheses merged 45 commits into
mainfrom
design/unified-start
Nov 12, 2026
Merged

unbalancedparentheses merged 45 commits into
mainfrom
design/unified-start

Conversation

@unbalancedparentheses

@unbalancedparentheses unbalancedparentheses commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

This is the unified start API design for 0.9 (ROADMAP rank 5h), after three review rounds. The round-three fixes are in; each is its own commit, and section 20 of the design has the round-three resolutions table. Design only.

  • Design: docs/design/unified-start.md
  • Client mapping: docs/design/unified-start-client-mapping.md
  • Model: verification/tla/Start.tla, TLC-only in model-map.toml until the implementation adds trace validation.

Round 3

  • Kills and the startup decision (Codex 1, agy F1). A non-ready resolution and D are one critical section. The startup decision wins, its reason is final, and a later kill does nothing. A ready child that is killed before D ends Killed at once. Checked by IgnoredExitsNormal (control SplitResolutionD) and KillBeforeDIsKilled (control SkipEscalation).
  • Release and delivery (Codex 2). Name release and slot release are separate atomic points, each with its own trace event. Lookups can repeat. Delivery to the parent is its own step, separate from disposition, with a refinement rule and new trace controls.
  • Owned work (Codex 3). Generation completion now waits for owned work, not publication alone. Control GenDoneIgnoresWork.
  • Parent exit vs the scope gate (agy F2). The parent's own exit refuses new starts but does not close its scope's gate. As in OTP, a child already in started() finishes init and then gets the parent's exit. Checked by OwnerRefusalOnlyOnShutdown (control ParentExitClosesOwner).
  • Migration. A row for the stopped() change: move initialization cleanup into started() or RAII.

TLC (fede, 4 workers, nice 19, run one at a time; each ended with TLC's "No error has been found")

Config Distinct states Time
MCStart 18,810 1 s
MCStartNames 1,396,516 16 s
MCStartCap 1,386,734 19 s
MCStartTimeout 374,244 5 s
MCStartContinue 4,527,484 30 s
MCStartScope (+ liveness) 419,228 23 s
MCStartLive (liveness) 68,400 6 s
MCStartDeep (weekly) 182,156,086 29 min 47 s

All 40 negative controls (37 safety, 3 liveness) produce their counterexample on the named property.

model-sync passes, and so do the script tests.

unbalancedparentheses added a commit that referenced this pull request Nov 11, 2026
…tartError, Init::continue_with, StartOptions)
… 3: Codex 1, agy F1)

A non-ready resolution and D are one critical section, so the startup decision and its reason are final; a kill after it does nothing, a kill before it is row 2. Ready children escalate atomically on a pre-D kill. Model: atomic ResolveD, kill escalation at arrival, invariants IgnoredExitsNormal and KillBeforeDIsKilled with controls SplitResolutionD and SkipEscalation (FrozenReason became vacuous and is retired).
…ry is its own step (round 3: Codex 2)

Model: ReleaseName and ReleaseSlot, repeatable Lookup, an outbox drained by Deliver (PNotice); design 5.2 and the 16.2 mapping with the delivery refinement rule and new trace controls.
…ion alone (round 3: Codex 3)

Model: WorkDoneP/WorkDoneC; GenDone and GenDoneMeansOwnedDone require P's and every member's owned work; control GenDoneIgnoresWork.
…ose its scope gate (round 3: agy F2)

As OTP, a child in started() whose start_link parent begins exiting still finishes init (and may commit ready, trapping children run their continuation) and then gets the parent exit. Only an ancestor's or the system's shutdown closes the owner gate. Model: closedBy/oref history, invariant OwnerRefusalOnlyOnShutdown, control ParentExitClosesOwner.
@unbalancedparentheses
unbalancedparentheses marked this pull request as ready for review November 11, 2026 23:09
# Conflicts:
#	ROADMAP.md
#	verification/model-map.toml
#	verification/tla/negative_checks.py
@unbalancedparentheses
unbalancedparentheses added this pull request to the merge queue Nov 12, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Nov 12, 2026
@unbalancedparentheses
unbalancedparentheses added this pull request to the merge queue Nov 12, 2026
Merged via the queue into main with commit 4d2ad18 Nov 12, 2026
29 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant