Resolve #2871: Enforce exclusive PlatformShell lifecycle transitions - #2883
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Make
RuntimePlatformShelllifecycle transitions strictly exclusive so reentrant or overlappingstart()andstop()calls fail immediately instead of waiting on one another and risking a deadlock.Linked context: #2871
Closes #2871
Changes
start()orstop()transition is active.PlatformLifecycleConflictErrorwith codePLATFORM_LIFECYCLE_CONFLICTand structured requested/active operation metadata.awaitreentry, failure cleanup, and retry behavior.Testing
pnpm exec vitest run -c vitest.config.ts src/platform-shell.lifecycle.test.ts src/platform-shell.test.ts src/errors.test.ts- 15 passed.pnpm --filter @fluojs/runtime test- 27 files, 298 tests passed.pnpm --filter @fluojs/runtime typecheck- passed.pnpm docs:sync-check- 42 page pairs and 10 navigation pairs passed.pnpm verify:platform-consistency-governance- passed.pnpm exec vitest run tooling/governance/verify-platform-consistency-governance.test.ts- 118 passed.pnpm verify:public-export-tsdoc- passed in changed mode.pnpm lint- exited successfully; it reported only pre-existing warnings/infos outside this PR's changed files.git diff --checkagainst the previous remote PR head - passed.Release impact
Major Changeset:
.changeset/serialize-platform-shell-lifecycle.mdfor@fluojs/runtime.This intentionally replaces the uncoordinated 2.x overlap behavior, where concurrent starts could duplicate component startup and stop during in-flight startup could return before startup settled. A
majorrelease requires explicit maintainer approval before merge.Migration
Consumers must not call
start()orstop()while another lifecycle transition is active. Await the current transition, then retry the desired operation explicitly. Overlap now rejects immediately withPlatformLifecycleConflictError; consumers can inspectcode,requestedOperation, andactiveOperation.Public export documentation
New root exports:
PlatformLifecycleOperationandPlatformLifecycleConflictError.Behavioral contract
Portable JavaScript cannot reliably distinguish an external overlapping caller from a continuation inside a lifecycle callback after arbitrary
await. Strict exclusivity therefore provides one runtime-neutral rule for both cases without queues, shared promises, callback flags, or runtime-specific async context.Platform consistency governance (SSOT)
The governed lifecycle contract is defined in
docs/architecture/platform-consistency-design.md, surfaced throughdocs/CONTEXT.md, and enforced bytooling/governance/platform-shell-lifecycle-contract.mjs.