Skip to content

Resolve #2871: Enforce exclusive PlatformShell lifecycle transitions - #2883

Merged
ayden94 merged 14 commits into
mainfrom
issue-2871-serialize-platform-shell-lifecycle
Aug 3, 2026
Merged

Resolve #2871: Enforce exclusive PlatformShell lifecycle transitions#2883
ayden94 merged 14 commits into
mainfrom
issue-2871-serialize-platform-shell-lifecycle

Conversation

@ayden94

@ayden94 ayden94 commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Summary

Make RuntimePlatformShell lifecycle transitions strictly exclusive so reentrant or overlapping start() and stop() calls fail immediately instead of waiting on one another and risking a deadlock.

Linked context: #2871

Closes #2871

Changes

  • Reject every lifecycle call made while another start() or stop() transition is active.
  • Export PlatformLifecycleConflictError with code PLATFORM_LIFECYCLE_CONFLICT and structured requested/active operation metadata.
  • Clear the active transition after both successful and failed settlement so consumers can retry explicitly.
  • Preserve dependency ordering, reverse-order cleanup, startup rollback, and normal sequential lifecycle behavior.
  • Cover all four overlap pairs, synchronous reentry, arbitrary-await reentry, failure cleanup, and retry behavior.
  • Document the strict-exclusivity contract and migration guidance in package, architecture, extension, conformance, and context docs with EN/KO parity.
  • Extend platform-consistency governance so the lifecycle contract remains discoverable and enforced.

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.
  • LSP diagnostics for changed TypeScript/JavaScript files - clean.
  • git diff --check against the previous remote PR head - passed.

Release impact

  • This PR has consumer-visible release impact and includes a changeset.
  • This PR has no consumer-visible release impact.

Major Changeset: .changeset/serialize-platform-shell-lifecycle.md for @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 major release requires explicit maintainer approval before merge.

Migration

Consumers must not call start() or stop() while another lifecycle transition is active. Await the current transition, then retry the desired operation explicitly. Overlap now rejects immediately with PlatformLifecycleConflictError; consumers can inspect code, requestedOperation, and activeOperation.

Public export documentation

  • Changed public exports include source-level summaries.
  • Exported error metadata and lifecycle operations are documented.
  • Package README examples and source documentation remain complementary.

New root exports: PlatformLifecycleOperation and PlatformLifecycleConflictError.

Behavioral contract

  • The replaced behavior includes explicit migration guidance.
  • New behavioral contracts are documented in the affected package README.
  • Intentional overlap rejection is explicitly stated.
  • Runtime invariants are covered by regression tests.

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)

  • Changed contract docs preserve English/Korean mirror parity.
  • Companion updates include discoverability, governance tooling, and regression evidence.
  • Platform conformance guidance now requires all overlap pairs and lifecycle reentry coverage.

The governed lifecycle contract is defined in docs/architecture/platform-consistency-design.md, surfaced through docs/CONTEXT.md, and enforced by tooling/governance/platform-shell-lifecycle-contract.mjs.

@ayden94 ayden94 changed the title Resolve #2871: Serialize PlatformShell lifecycle transitions Resolve #2871: Enforce exclusive PlatformShell lifecycle transitions Aug 3, 2026
@ayden94
ayden94 merged commit acd28a9 into main Aug 3, 2026
10 checks passed
@ayden94
ayden94 deleted the issue-2871-serialize-platform-shell-lifecycle branch August 3, 2026 10:29
@github-actions github-actions Bot mentioned this pull request Aug 3, 2026
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.

[audit][area:foundation] Serialize PlatformShell lifecycle transitions (P1)

1 participant