Absolute new LVL Version 2 # Redesign

.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  default:
+    name: Default suite (PHP ${{ matrix.php }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.4', '8.5']
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: pcntl, posix, shmop
+          coverage: none
+
+      - name: Install dependencies
+        run: composer install --no-interaction --no-progress
+
+      - name: Code style
+        run: composer cs-check
+
+      - name: Default suite (base + working)
+        run: composer test
+
+  container:
+    name: Container suite (PHP ${{ matrix.php }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.4', '8.5']
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+
+      - name: Build test image (cached; pcntl/posix/shmop/swoole)
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
+        with:
+          context: .
+          file: tests/docker/Dockerfile
+          build-args: PHP_VERSION=${{ matrix.php }}
+          tags: wt-test:${{ matrix.php }}
+          load: true
+          cache-from: type=gha,scope=wt-${{ matrix.php }}
+          cache-to: type=gha,mode=max,scope=wt-${{ matrix.php }}
+
+      - name: Run default + container suites
+        run: |
+          docker run --init --rm -v "$PWD":/app -w /app wt-test:${{ matrix.php }} bash -lc '
+            composer install --no-interaction --no-progress
+            composer test
+            vendor/bin/phpunit --testsuite container
+          '

CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+_Nothing yet._
+
+## [2.0.0] - 2026-07-03
+
+A ground-up redesign. `Thread` keeps its familiar Java-like API but is now a thin
+facade over small, composable primitives you can build a pool/scheduler on.
+
+### Added
+- **`Engine` abstraction** bound once via `Thread::bindEngine()`:
+  - `AdaptiveEngine` — self-configuring default (detects CLI/FPM binary, Swoole
+    runtime, and `WINTER_THREAD_SECRET`);
+  - `ManualEngine` — explicit, immutable withers for full control.
+- **Parent-side primitives** for framework authors: `Launcher` / `CliLauncher`,
+  `ProcessHandle`, and the `LaunchSpec` DTO — drive processes without the `Thread`
+  facade.
+- **Pluggable payload transports**: `PipeTransport`, `TempFileTransport` (Swoole-safe),
+  and `ShmTransport` (System V shared memory; needs `ext-shmop`). The engine
+  auto-selects a Swoole-safe transport under an active Swoole runtime.
+- **Child-side `Runner`** (`AdaptiveRunner`), driven by the `wRunner` bootstrap and
+  deliberately independent of the parent `Engine`.
+- **Non-blocking lifecycle**: `reap()`, `detach()`, `getExitCode()`, and a
+  zombie-safe destructor — the basis for polling many workers in one loop.
+- **Detached mode** (`start(detached: true)`): `fork` + `setsid` for zombie-free
+  fire-and-forget under a long-lived parent.
+- **Signed payloads** via `opis/closure` (HMAC), with the secret propagated to the
+  child through the environment (never argv).
+- Full documentation set under [`docs/`](docs/README.md) and a two-tier test suite
+  (default + container) with CI across PHP 8.4 / 8.5.
+
+### Changed
+- **Requires PHP >= 8.4** (`readonly` classes, first-class callable syntax).
+- Deserialization now goes **exclusively** through `opis/closure` — native
+  `unserialize()` is never used.
+- CLI arguments (binary/runner paths, metadata, per-run args, shm key) are uniformly
+  escaped with `escapeshellarg()`.
+
+### Security
+- Signing secret is transmitted via the owner-only environment, never on the command
+  line.
+- An ambient `WINTER_THREAD_SECRET` in the parent environment is neutralized for the
+  child when the engine is unsigned, preventing spurious "failed to deserialize"
+  rejections.
+
+[Unreleased]: https://github.com/flytachi/winter-thread/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/flytachi/winter-thread/releases/tag/v2.0.0

CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to Winter Thread
+
+Thanks for helping improve Winter Thread! This guide covers local setup, the test
+tiers, and the conventions the project follows.
+
+## Requirements
+
+- **PHP >= 8.4** with `ext-pcntl` and `ext-posix` (and `ext-shmop` if you touch the
+  shared-memory transport).
+- Composer.
+- A POSIX OS (Linux or macOS) — the engine relies on signals, `setsid`, and
+  `/proc`/`ps`. Windows is not supported.
+
+## Setup
+
+```bash
+git clone https://github.com/flytachi/winter-thread
+cd winter-thread
+composer install
+```
+
+## Running the tests
+
+The suite has **two tiers** (see [docs/15 — Testing](docs/15-testing.md)).
+
+**Default tier** — runs on any machine; tests needing an absent extension self-skip:
+
+```bash
+composer test            # base (unit) + working (end-to-end)
+composer test-base       # unit-level class correctness only
+composer test-working    # real end-to-end scenarios only
+composer test-detail     # testdox (human-readable) output
+```
+
+**Container tier** — heavy, environment-specific checks (leak / timing / Swoole /
+load), run inside Docker across PHP versions:
+
+```bash
+tests/run-container.sh              # default versions: 8.4 8.5
+tests/run-container.sh 8.4          # a single version
+```
+
+## Code style
+
+PSR-12, enforced by `phpcs`:
+
+```bash
+composer cs-check   # report violations (src/)
+composer cs-fix     # auto-fix what it can
+```
+
+All `src/` files must declare `strict_types=1`. CI runs `cs-check` + the default
+suite on a PHP 8.4 / 8.5 matrix, and the container suite in Docker.
+
+## Pull requests
+
+1. **Branch** off `main`.
+2. **Add tests** for any behavior change — a bug fix gets a regression test; a
+   feature gets coverage in the appropriate tier (`tests/Base` for isolated class
+   correctness, `tests/Working` for end-to-end, `tests/Container` for
+   environment-specific).
+3. **Keep docs in sync.** The `docs/*` files are the source of truth for behavior;
+   if you change a signature or a default, update the matching doc (especially
+   [docs/14 — API Reference](docs/14-api-reference.md)) in the same PR.
+4. **Run `composer cs-check` and `composer test`** locally; both must be green.
+5. Keep changes focused; explain the *why* in the PR description.
+
+## Project layout
+
+- `src/` — the library. `Thread` is a thin facade; the real work lives in the
+  `Engine` / `Launcher` / `Runner` / `PayloadTransport` primitives. Read
+  [docs/11 — Architecture](docs/11-architecture.md) before making structural
+  changes — note that the **parent-side `Engine`** and the **child-side `Runner`**
+  are deliberately independent.
+- `wRunner` — the child bootstrap script (packaged as `bin`).
+- `tests/` — `Base` / `Working` / `Container` tiers, plus `Fixtures` and `docker`.
+- `docs/` — the documentation set.
+
+## Reporting bugs & security issues
+
+- **Bugs:** open a GitHub issue with a minimal reproduction, your PHP version, and
+  OS.
+- **Security vulnerabilities:** do **not** open a public issue — follow
+  [SECURITY.md](SECURITY.md).
+
+## License
+
+By contributing you agree that your contributions are licensed under the project's
+[MIT license](LICENSE).