diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..5df49666b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,546 @@
+# CLAUDE.md - Temporal PHP SDK
+
+## Project Overview
+
+Temporal PHP SDK (`temporal/sdk`) - official PHP client library for the Temporal workflow orchestration platform. Enables building resilient, distributed workflows and activities in PHP. Requires PHP 8.1+.
+
+## Runtime в двух абзацах
+
+PHP-воркер ничего сетевого не делает во время workflow execution. Persistent gRPC к Temporal держит **RoadRunner** (Go-плагин `rrtemporal` на базе Temporal Go SDK). PHP общается с RR через локальный goridge-pipe, отдавая декларативные команды (`NewTimer`, `ExecuteActivity`, `ExecuteNexusOperation`, …) и получая в ответ events/responses. gRPC-клиент в SDK (`Temporal\Client\GRPC\ServiceClient`) есть, но используется только для **client-side API** (вне workflow): `WorkflowClient`, `ScheduleClient`, `OperatorClient`.
+
+Workflow-метод — это PHP-generator. Его «крутит» `Scope::next()` ([src/Internal/Workflow/Process/Scope.php](src/Internal/Workflow/Process/Scope.php)): смотрит `Generator::current()`, если promise — навешивает on-fulfilled, который через `defer()` поставит в loop вызов `Generator::send($result)`. Loop — это event-emitter с фиксированными слоями (`ON_TICK`, `ON_QUERY`, …), реализованный самим `WorkerFactory`. ReactPHP loop'а в SDK нет. Replay-логики в PHP тоже нет: воркер при replay'е переисполняет workflow с нуля, снова генерирует те же команды (request ID `9000+`, статический counter), а RR резолвит их мгновенно из истории — для PHP это просто «быстрые promise'ы».
+
+Подробности и file:line ссылки:
+- [docs/runtime/](docs/runtime/) — архитектура, wire-протокол PHP↔RR, корутины и replay.
+- [docs/nexus/](docs/nexus/) — Nexus spec, handler-side SDK, RR-контракт (handler + caller).
+- [docs/data-conversion/](docs/data-conversion/) — converter chain (Null/Binary/ProtoJson/Proto/Json), `EncodedValues`/`EncodedCollection`, `RawValue`, поздняя инъекция converter'а, Marshaller для DTO, integration map (codec/routes/Nexus/failures).
+- [docs/testing/](docs/testing/) — виды тестов (unit/functional/acceptance/arch), инфраструктура (bootstrap'ы, lifecycle серверов, fast/slow split), `testing/` mini-framework.
+
+## Common Commands
+
+### Testing
+
+```bash
+composer test:unit           # Unit tests (tests/Unit, suffix *TestCase.php)
+composer test:func           # Functional tests (tests/Functional, suffix *TestCase.php) — requires Temporal server
+composer test:accept         # All acceptance tests (tests/Acceptance, suffix *Test.php) — requires Temporal server
+composer test:accept-fast    # Fast acceptance tests only
+composer test:accept-slow    # Slow acceptance tests only
+composer test:arch           # Architecture constraint tests (tests/Arch)
+```
+
+Run a single test:
+```bash
+vendor/bin/phpunit --testsuite=Unit --filter=SomeTestCase
+tests/runner.php vendor/bin/phpunit --testsuite=Functional --filter=SomeTestCase
+```
+
+Unit tests don't require external services. Functional and acceptance tests require a running Temporal server (`TEMPORAL_ADDRESS=127.0.0.1:7233` by default) and RoadRunner. Bootstrap in `tests/bootstrap.php` auto-detects the suite and includes the suite-specific bootstrap (e.g. `tests/Acceptance/bootstrap.php`).
+
+**Never start Temporal or RoadRunner manually before running the test suite.** The functional and acceptance bootstraps spin up the test server and the RR worker themselves. Running `./temporal server start-dev` or `rr serve` by hand fights the bootstrap (port 7233 double-bind, stale workers) and produces misleading errors. If tests fail with server/worker issues, look at `runtime/rr.log`, `runtime/rr.err.log`, and `runtime/tests/logs/*.log` — do not try to "warm up" or "verify" the binaries by launching them yourself.
+
+`tests/runner.php` is a CI workaround script that wraps PHPUnit execution with JUnit log parsing.
+
+### Code Style
+
+```bash
+composer cs:diff    # Check code style (php-cs-fixer dry-run)
+composer cs:fix     # Fix code style
+```
+
+Config: `.php-cs-fixer.dist.php` — uses `Spiral\CodeStyle\Builder`, covers `src/` and `testing/src/`.
+
+### Static Analysis
+
+```bash
+composer psalm              # Run Psalm (error level 2, strict)
+composer psalm:baseline     # Update psalm baseline
+```
+
+Config: `psalm.xml` — error level 2, `strictBinaryOperands=true`, `findUnusedVariablesAndParams=true`, baseline in `psalm-baseline.xml`.
+
+### Code Generation
+
+```bash
+make generate-proto     # Generate protobuf PHP code
+make generate-client    # Generate gRPC client stubs
+```
+
+### Binaries
+
+```bash
+composer get:binaries   # Download Temporal server & RoadRunner binaries
+```
+
+## Project Structure
+
+```
+src/                    Main SDK source code
+  Activity/             Activity definitions, context, options
+  Workflow/             Workflow definitions (WorkflowMethod, SignalMethod, QueryMethod, UpdateMethod)
+  Client/               WorkflowClient, ScheduleClient, ServiceClient
+  Client/GRPC/          gRPC connection and transport
+  Worker/               Worker factory, RoadRunner integration
+  Interceptor/          Interceptor interfaces and pipelines
+  Plugin/               Plugin system (Worker, Client, Schedule, Connection plugins)
+  Common/               Shared DTOs (RetryOptions, SearchAttributes, etc.)
+  DataConverter/        Serialization/deserialization, type system
+  Exception/            Exception hierarchy
+  Internal/             Internal implementation (not public API)
+  Nexus/                Nexus RPC handler-side library (data model, service routing,
+                        middleware, serialization). Subdirs: Attribute/, Exception/,
+                        Handler/, Internal/, Serializer/, Validation/.
+tests/
+  Unit/                 Unit tests (*TestCase.php) — no external deps
+  Functional/           Functional tests (*TestCase.php) — needs Temporal server
+  Acceptance/           Acceptance tests (*Test.php) — full E2E
+    Extra/              SDK-specific acceptance tests
+    Harness/            Cross-SDK harness tests
+  Arch/                 Architecture constraint tests
+  Fixtures/             Test fixtures (sample workflows, activities, DTOs)
+  Nexus/                Nexus subsystem tests (Unit/ uses *Test.php suffix,
+                        plus Fixture/ and Support/). Picked up by the Unit suite.
+testing/                Testing framework (TestService, ActivityMocker, Environment)
+resources/scripts/      Code generation scripts
+```
+
+## Architecture & Conventions
+
+### Strict Types
+
+All PHP files must start with `declare(strict_types=1);`. Strong type hints and return types are required everywhere.
+
+### Naming
+
+Use full words for identifiers — no informal abbreviations.
+
+- Wrong: `$attrs`, `$impl`, `$ref`, `$opts`, `$ctx`
+- Right: `$attributes`, `$implementation`, `$reflection` (or `$reference`), `$options`, `$context`
+
+The exceptions are well-established protocol abbreviations baked into wire-level
+contracts (e.g. `RPC`, `URL`, `URI`, `ID`) and standard short variable names in
+narrow scopes (`$e` for an exception in a `catch`, `$i` for a loop counter).
+When in doubt, write the full word.
+
+### Control flow: prefer `if`-statements over short-circuit side effects
+
+Don't smuggle imperative actions into boolean expressions. Each statement
+should make either a decision (a condition guarding a block) or an action,
+not both at once.
+
+Wrong:
+
+```php
+$result === 'ok' && $handler->continue();
+$value !== null or throw new \LogicException('missing value');
+```
+
+Right:
+
+```php
+if ($result === 'ok') {
+    $handler->continue();
+}
+
+if ($value === null) {
+    throw new \LogicException('missing value');
+}
+```
+
+Reasons: the `if`-form is easier to scan, easier to step through in a debugger,
+plays nicely with code coverage tools, and doesn't rely on the reader spotting
+that the right-hand side is a side-effecting expression rather than a check.
+
+### Namespace Structure
+
+Root namespace: `Temporal\`. Mirrors directory layout:
+- `Temporal\Workflow\`, `Temporal\Activity\`, `Temporal\Client\`, `Temporal\Worker\`
+- `Temporal\Interceptor\`, `Temporal\Plugin\`, `Temporal\Internal\`
+- Tests: `Temporal\Tests\`, Testing framework: `Temporal\Testing\`
+
+### PHP 8 Attributes
+
+Workflows and activities are defined using PHP 8 attributes (not annotations):
+- Class-level: `#[WorkflowInterface]`, `#[ActivityInterface(prefix: "...")]`
+- Method-level: `#[WorkflowMethod]`, `#[ActivityMethod]`, `#[SignalMethod]`, `#[QueryMethod]`, `#[UpdateMethod]`
+
+### Key Patterns
+
+- **Facade pattern**: `Workflow` and `Activity` classes provide static context-aware access
+- **Interceptor chain**: `WorkflowInboundCallsInterceptor`, `WorkflowOutboundRequestInterceptor`, `ActivityInboundInterceptor`
+- **Plugin system**: `WorkerPluginInterface`, `ClientPluginInterface`, `ScheduleClientPluginInterface`, `ConnectionPluginInterface`
+- **Data converters**: `DataConverterInterface` with multiple implementations (Proto, JSON, Binary, Null)
+
+### Dependency Rules (ENFORCED)
+
+Namespace dependency directions — violations must be rejected:
+
+- `Internal\*` → any public namespace (implements public interfaces)
+- `Client\*` → `Common\*`, `DataConverter\*`, `Exception\*`
+- `Interceptor\*` → `Common\*`, `Workflow\*`, `Activity\*`
+- `Nexus\*` → `Common\*`, `Exception\*`, `Workflow\*` (must not reach into `Internal\*` /
+  `Client\*`). Enforced by `tests/Arch/NexusDependencyTest.php`, which carries an explicit
+  exemption list for the bridge types that legitimately cross into the worker runtime: the
+  `Nexus\Handler\Internal\*` dispatch subtree plus `Nexus\Nexus`, `Nexus\Header`,
+  `Nexus\NexusOperationContext`, and `Nexus\WorkflowHandle`. Add to that list only with a reason.
+- `Worker\*` → `Internal\*` (worker bootstraps internal machinery)
+- FORBIDDEN: Public namespaces → `Internal\*`
+- FORBIDDEN: `Activity\*` → `Workflow\*` or vice versa (peer namespaces)
+- FORBIDDEN: `DataConverter\*` → `Client\*` (lower → higher layer)
+
+### Naming (file-level)
+
+- Files: PascalCase (`WorkflowClient.php`)
+- Variables: camelCase (`$workflowClient`)
+- Methods: camelCase (`startWorkflow()`)
+- Classes: PascalCase (`WorkflowClient`)
+- Constants: UPPER_SNAKE_CASE
+
+### File Naming
+
+- Interfaces: `*Interface.php`
+- Traits: `*Trait.php`
+- Unit/Functional tests: `*TestCase.php`
+- Acceptance tests: `*Test.php`
+- Nexus subsystem unit tests: `*Test.php` (under `tests/Nexus/Unit`, picked up by the Unit suite)
+
+### Match the existing style before writing code
+
+Before adding or changing code, look at the surrounding files and match what's
+already there: naming, member ordering, visibility patterns, which language
+features are used (e.g. `readonly` properties + named arguments vs. setters,
+`match` vs. `switch`, enums vs. constants, attribute placement, nullability
+style). New code should be indistinguishable from neighbouring code.
+
+If a new pattern is genuinely needed, justify it explicitly — don't introduce
+a parallel style by accident.
+
+### Comments
+
+**Do not write comments.** This is not a soft default — it's the rule. Names,
+types, and small focused functions are the documentation. If a block needs a
+comment to be understood, the block is wrong: rename it, extract it, or split
+it until it isn't.
+
+Banned in particular:
+
+- Section labels like `// Register Workflow`, `// Feature flags`, `// Scan all
+  the test cases`. If the code below needs a label, extract a method whose
+  name *is* the label.
+- Restating the code (`// loop over users`, `// return null`).
+- Multi-line docblock essays explaining *why* a function exists, when it was
+  introduced, what experiments validated it, or which sibling class it
+  mirrors. That belongs in commit messages and PR descriptions, not in the
+  file. Comments rot; git history doesn't.
+- "Note: ", "TODO: " without an issue link, "HACK: ", or any other meta
+  narration aimed at a future reader.
+- Inline comments on enum cases / array entries explaining *why each entry is
+  there*. If an entry needs justification, either the test name carries it or
+  it doesn't belong in the list.
+
+Allowed, narrowly:
+
+- PHPDoc type annotations the type system can't express (`@param non-empty-string`,
+  `@return list<class-string>`, generic templates). These are types, not prose.
+- One short line capturing a hidden constraint a reader genuinely cannot
+  recover from the code — a workaround tied to a specific upstream bug, a
+  protocol invariant, a deliberate ordering requirement. One line. No essay.
+
+When in doubt: delete the comment. If a reviewer later asks "why?", the
+answer goes in the commit message, not back into the file.
+
+### Tests must exercise real behaviour
+
+A test exists to catch real failures — wire formats, branching logic,
+contracts between collaborators, error paths, edge cases that could
+realistically break.
+
+Tautologies are not tests. Do not write:
+
+```php
+$value = 5;
+self::assertSame(5, $value);
+
+$dto = new Foo(name: 'x');
+self::assertSame('x', $dto->name);
+```
+
+These pass by construction and catch nothing. They also don't belong in the
+codebase even as "coverage filler". If the only thing a test does is read
+back what it just wrote, delete it or replace it with something that
+actually exercises behaviour (a method call, a state transition, a
+serializer round-trip, an error path).
+
+When adding a test, ask: *what production change would make this fail?* If
+the answer is "none", the test isn't carrying its weight.
+
+**Never use `markTestIncomplete()` or `markTestSkipped()` to bypass a failing
+test when the task is to write or fix tests.** A red test that documents a
+real gap is more valuable than a green-ish "incomplete" marker that hides it.
+If the production code path the test targets is genuinely broken, fix the
+production code first or narrow the assertion to what *is* in the plan's
+scope. The only legitimate uses of skip/incomplete are external preconditions
+outside the test author's control (a missing extension, an unavailable
+third-party service, a known-flaky upstream not yet addressable) — and those
+must be paired with a one-line `// TODO(plan-or-issue-ref):` pointer to the
+unblocking work.
+
+### Exception tests: assert full messages, not fragments
+
+When testing exception messages, use `expectExceptionMessage()` with the full
+expected text — not `expectExceptionMessageMatches()` with regex fragments.
+Full-message assertions catch accidental message changes and are easier to read.
+
+Wrong:
+
+```php
+$this->expectExceptionMessageMatches('/"url"/');
+```
+
+Right:
+
+```php
+$this->expectExceptionMessage('Nexus link at index 0 has missing or empty "url"');
+```
+
+If the message contains dynamic parts that genuinely vary per invocation
+(timestamps, UUIDs), `assertStringContainsString` on the caught `$e` is
+acceptable — but for static messages, always assert the full string.
+
+## Nexus Subsystem (`src/Nexus/`)
+
+Handler-side Nexus RPC library: data model, service routing, middleware, serialization
+contract. Sits under `Temporal\Nexus\` and is wired into the Temporal worker through
+`src/Internal/Nexus/` and the `InvokeNexusOperation` / `CancelNexusOperation` routes.
+
+### Service / impl shape
+
+Services follow the same `implements`-based shape as Workflows and Activities:
+
+- A `#[Service]`-annotated **interface** declares operations as plain method
+  signatures. Sync operations carry `#[Operation]`; async operations carry
+  `#[AsyncOperation(output: '<wire-type>')]` and return a `WorkflowHandle`
+  (SDK-managed workflow run) or — for full manual control — an
+  `OperationHandlerInterface` implementation.
+- An **impl class** `implements` that interface — PHP's signature covariance
+  guarantees the operation methods match the contract. Worker registration
+  walks `getInterfaces()` to discover the contract; mirror in
+  `tests/Acceptance/App/RuntimeBuilder.php`.
+- Cancel is wired automatically. A `WorkflowHandle`-backed async op is cancelled
+  by the SDK (it decodes the operation token and cancels the backing workflow);
+  a manual `OperationHandlerInterface` carries its own `cancel()`. `ServiceHandler`
+  rejects cancel requests for sync ops with `ErrorType::NotImplemented`. There is
+  no `#[OperationCancel]` attribute.
+- Inside an impl method body, reach the surrounding dispatch state via the
+  static `Nexus::` accessors:
+  - `Nexus::getCurrentContext()` — the active `NexusContext` dispatch state
+  - `Nexus::getCurrentOperationContext()` — handler-side `OperationContext`
+    (links, headers, deadline)
+  - `Nexus::getStartDetails()` / `Nexus::getCancelDetails()` — per-call details
+  - `Nexus::getOperationContext()` — Temporal-side context (namespace,
+    task queue, workflow client)
+
+An `#[AsyncOperation]` method returns the `WorkflowHandle` directly:
+
+```php
+#[AsyncOperation(output: 'string')]
+public function hello(string $input): WorkflowHandle {
+    return WorkflowHandle::fromWorkflowMethod(MyWorkflow::class, $options, $input);
+}
+```
+
+The previous shapes (`#[ServiceImpl]`, `#[OperationImpl]`, `#[OperationCancel]`,
+`OperationInfo` returns, and `SynchronousOperationHandler`) are gone — those
+attributes and classes have been deleted. `OperationHandlerInterface` remains as
+the internal adapter contract and may also be returned from an `#[AsyncOperation]`
+method for full manual start+cancel control.
+
+### Conventions
+
+- `#[Attribute]` over annotations; backed `enum`s for wire-level values
+- `readonly` properties + named arguments instead of builders
+- Wire values (enum string values, header names) **must match the Nexus spec verbatim** —
+  they are the protocol contract, not an implementation detail
+
+### Validation policy
+
+- Service / operation names and operation tokens are validated by
+  `src/Nexus/Validation/*Validator.php` — call `::assert()` from any new constructor that
+  accepts these values
+- Validators throw `Temporal\Nexus\Exception\InvalidArgumentException` on failure
+- `LinkParser` and other strict parsers throw `HandlerException{BadRequest}` on malformed
+  input — never silently drop entries
+
+### Wire-shape canonicalization
+
+Every spec-defined Failure shape has a single canonical builder/reader pair in
+`src/Nexus/Exception/`:
+
+- `OperationErrorFailure::from()` / `::isOperationError()` / `::readState()`
+- `HandlerErrorFailure::from()` / `::isHandlerError()` / `::readErrorType()` /
+  `::readRetryableOverride()`
+
+Transport glue (worker, RoadRunner adapter) must use these — do **not** hand-roll the JSON
+shape elsewhere.
+
+### Test conventions (Nexus only)
+
+- Every test class declares `#[CoversClass(Subject::class)]`; classes touched by the test
+  declare `#[UsesClass(Other::class)]` for each one
+- Prefer `$this->expectException(...)` over `try/catch + self::fail()`
+- New code keeps the covered lines at 100% (or land an explicit waiver in the PR)
+
+## Key Dependencies
+
+- **gRPC**: `grpc/grpc` — client-server communication
+- **Protobuf**: `google/protobuf` — message serialization
+- **RoadRunner**: `spiral/roadrunner` — PHP worker process manager (required for workers)
+- **Spiral Attributes**: `spiral/attributes` — attribute reflection
+- **PHPUnit**: `phpunit/phpunit` v10.5 — testing
+- **Psalm**: `vimeo/psalm` — static analysis (level 2)
+
+Optional extensions: `ext-grpc`, `ext-protobuf` (recommended for production performance).
+
+## Git Workflow
+
+- Main branch: `master`
+- PRs target `master`
+
+<!-- rtk-instructions v2 -->
+# RTK (Rust Token Killer) - Token-Optimized Commands
+
+## Golden Rule
+
+**Always prefix commands with `rtk`**. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use.
+
+**Important**: Even in command chains with `&&`, use `rtk`:
+```bash
+# ❌ Wrong
+git add . && git commit -m "msg" && git push
+
+# ✅ Correct
+rtk git add . && rtk git commit -m "msg" && rtk git push
+```
+
+## RTK Commands by Workflow
+
+### Build & Compile (80-90% savings)
+```bash
+rtk cargo build         # Cargo build output
+rtk cargo check         # Cargo check output
+rtk cargo clippy        # Clippy warnings grouped by file (80%)
+rtk tsc                 # TypeScript errors grouped by file/code (83%)
+rtk lint                # ESLint/Biome violations grouped (84%)
+rtk prettier --check    # Files needing format only (70%)
+rtk next build          # Next.js build with route metrics (87%)
+```
+
+### Test (60-99% savings)
+```bash
+rtk cargo test          # Cargo test failures only (90%)
+rtk go test             # Go test failures only (90%)
+rtk jest                # Jest failures only (99.5%)
+rtk vitest              # Vitest failures only (99.5%)
+rtk playwright test     # Playwright failures only (94%)
+rtk pytest              # Python test failures only (90%)
+rtk rake test           # Ruby test failures only (90%)
+rtk rspec               # RSpec test failures only (60%)
+rtk test <cmd>          # Generic test wrapper - failures only
+```
+
+### Git (59-80% savings)
+```bash
+rtk git status          # Compact status
+rtk git log             # Compact log (works with all git flags)
+rtk git diff            # Compact diff (80%)
+rtk git show            # Compact show (80%)
+rtk git add             # Ultra-compact confirmations (59%)
+rtk git commit          # Ultra-compact confirmations (59%)
+rtk git push            # Ultra-compact confirmations
+rtk git pull            # Ultra-compact confirmations
+rtk git branch          # Compact branch list
+rtk git fetch           # Compact fetch
+rtk git stash           # Compact stash
+rtk git worktree        # Compact worktree
+```
+
+Note: Git passthrough works for ALL subcommands, even those not explicitly listed.
+
+### GitHub (26-87% savings)
+```bash
+rtk gh pr view <num>    # Compact PR view (87%)
+rtk gh pr checks        # Compact PR checks (79%)
+rtk gh run list         # Compact workflow runs (82%)
+rtk gh issue list       # Compact issue list (80%)
+rtk gh api              # Compact API responses (26%)
+```
+
+### JavaScript/TypeScript Tooling (70-90% savings)
+```bash
+rtk pnpm list           # Compact dependency tree (70%)
+rtk pnpm outdated       # Compact outdated packages (80%)
+rtk pnpm install        # Compact install output (90%)
+rtk npm run <script>    # Compact npm script output
+rtk npx <cmd>           # Compact npx command output
+rtk prisma              # Prisma without ASCII art (88%)
+```
+
+### Files & Search (60-75% savings)
+```bash
+rtk ls <path>           # Tree format, compact (65%)
+rtk read <file>         # Code reading with filtering (60%)
+rtk grep <pattern>      # Search grouped by file (75%)
+rtk find <pattern>      # Find grouped by directory (70%)
+```
+
+### Analysis & Debug (70-90% savings)
+```bash
+rtk err <cmd>           # Filter errors only from any command
+rtk log <file>          # Deduplicated logs with counts
+rtk json <file>         # JSON structure without values
+rtk deps                # Dependency overview
+rtk env                 # Environment variables compact
+rtk summary <cmd>       # Smart summary of command output
+rtk diff                # Ultra-compact diffs
+```
+
+### Infrastructure (85% savings)
+```bash
+rtk docker ps           # Compact container list
+rtk docker images       # Compact image list
+rtk docker logs <c>     # Deduplicated logs
+rtk kubectl get         # Compact resource list
+rtk kubectl logs        # Deduplicated pod logs
+```
+
+### Network (65-70% savings)
+```bash
+rtk curl <url>          # Compact HTTP responses (70%)
+rtk wget <url>          # Compact download output (65%)
+```
+
+### Meta Commands
+```bash
+rtk gain                # View token savings statistics
+rtk gain --history      # View command history with savings
+rtk discover            # Analyze Claude Code sessions for missed RTK usage
+rtk proxy <cmd>         # Run command without filtering (for debugging)
+rtk init                # Add RTK instructions to CLAUDE.md
+rtk init --global       # Add RTK to ~/.claude/CLAUDE.md
+```
+
+## Token Savings Overview
+
+| Category | Commands | Typical Savings |
+|----------|----------|-----------------|
+| Tests | vitest, playwright, cargo test | 90-99% |
+| Build | next, tsc, lint, prettier | 70-87% |
+| Git | status, log, diff, add, commit | 59-80% |
+| GitHub | gh pr, gh run, gh issue | 26-87% |
+| Package Managers | pnpm, npm, npx | 70-90% |
+| Files | ls, read, grep, find | 60-75% |
+| Infrastructure | docker, kubectl | 85% |
+| Network | curl, wget | 65-70% |
+
+Overall average: **60-90% token reduction** on common development operations.
+<!-- /rtk-instructions -->
diff --git a/composer.json b/composer.json
index 90f9c970a..1832786ae 100644
--- a/composer.json
+++ b/composer.json
@@ -30,6 +30,7 @@
         "internal/destroy": "^1.0",
         "internal/promise": "^3.4",
         "nesbot/carbon": "^2.72.6 || ^3.8.4",
+        "psr/clock": "^1.0",
         "psr/log": "^2.0 || ^3.0.2",
         "ramsey/uuid": "^4.7.6",
         "roadrunner-php/roadrunner-api-dto": "^1.14.0",
diff --git a/docs/attributes.md b/docs/attributes.md
new file mode 100644
index 000000000..41e6f6662
--- /dev/null
+++ b/docs/attributes.md
@@ -0,0 +1,100 @@
+# Атрибуты опций (Attributes for Options)
+
+В Temporal PHP SDK вы можете задавать параметры для Workflow и Activity с помощью атрибутов прямо в коде интерфейсов или классов. Это позволяет определить значения по умолчанию, которые будут использоваться при создании стабов, если они не переопределены явно.
+
+## Гранулярные атрибуты Activity
+
+Для настройки Activity используются гранулярные атрибуты из пространства имен `Temporal\Activity\Attribute`.
+
+### Список доступных атрибутов Activity:
+
+- `#[TaskQueue(string $name)]`
+- `#[ScheduleToCloseTimeout(int|string|DateInterval $timeout)]`
+- `#[ScheduleToStartTimeout(int|string|DateInterval $timeout)]`
+- `#[StartToCloseTimeout(int|string|DateInterval $timeout)]`
+- `#[HeartbeatTimeout(int|string|DateInterval $timeout)]`
+- `#[CancellationType(ActivityCancellationType|int $type)]`
+- `#[RetryPolicy(RetryOptions $options)]` (или именованный конструктор `RetryPolicy::new(...)`)
+- `#[ActivityPriority(Priority|int $priority)]`
+- `#[Summary(string $text)]`
+
+### Пример использования Activity:
+
+```php
+use Temporal\Activity\ActivityInterface;
+use Temporal\Activity\ActivityMethod;
+use Temporal\Activity\Attribute\ScheduleToCloseTimeout;
+use Temporal\Activity\Attribute\StartToCloseTimeout;
+use Temporal\Activity\Attribute\TaskQueue;
+use Temporal\Activity\Attribute\RetryPolicy;
+use Temporal\Common\RetryOptions;
+
+#[TaskQueue('my-task-queue')]
+#[ScheduleToCloseTimeout('10 seconds')]
+#[RetryPolicy(new RetryOptions(maximumAttempts: 5))]
+#[ActivityInterface(prefix: 'App.')]
+interface MyActivityInterface
+{
+    #[ActivityMethod]
+    #[StartToCloseTimeout('2 seconds')] // Переопределяет или дополняет опции класса
+    public function doSomething();
+}
+```
+
+В Workflow:
+```php
+// Будут использованы все опции из атрибутов
+$activity = Workflow::newActivityStub(MyActivityInterface::class);
+
+// Атрибуты будут дополнены/перекрыты опцией из кода
+$activity = Workflow::newActivityStub(
+    MyActivityInterface::class,
+    ActivityOptions::new()->withTaskQueue('override-queue')
+);
+```
+
+---
+
+## Гранулярные атрибуты Workflow
+
+Аналогично Activity, для Workflow доступны гранулярные атрибуты в пространстве имен `Temporal\Workflow\Attribute`.
+
+### Список доступных атрибутов Workflow:
+
+- `#[WorkflowId(string $id)]`
+- `#[TaskQueue(string $name)]`
+- `#[WorkflowExecutionTimeout(int|string|DateInterval $timeout)]`
+- `#[WorkflowRunTimeout(int|string|DateInterval $timeout)]`
+- `#[WorkflowTaskTimeout(int|string|DateInterval $timeout)]`
+- `#[WorkflowIdReusePolicy(IdReusePolicy|int $policy)]`
+- `#[WorkflowIdConflictPolicy(WorkflowIdConflictPolicy $policy)]`
+- `#[CronSchedule(string $expression)]`
+- `#[RetryPolicy(RetryOptions $options)]`
+- `#[WorkflowPriority(Priority|int $priority)]`
+- `#[Summary(string $text)]`
+
+### Пример использования Workflow:
+
+```php
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+use Temporal\Workflow\Attribute\TaskQueue;
+use Temporal\Workflow\Attribute\WorkflowRunTimeout;
+
+#[TaskQueue('reports-queue')]
+#[WorkflowRunTimeout('1 hour')]
+#[WorkflowInterface]
+interface MyWorkflowInterface
+{
+    #[WorkflowMethod]
+    public function execute();
+}
+```
+
+## Приоритет применения (Precedence)
+
+Опции мерджатся в следующем порядке (каждый следующий уровень перекрывает предыдущий):
+1. Родительский класс (интерфейс)
+2. Текущий класс (интерфейс)
+3. Метод
+4. Опции, переданные явно при создании стаба (`Workflow::newActivityStub` или `WorkflowClient::newWorkflowStub`)
diff --git a/docs/context-propagator.md b/docs/context-propagator.md
new file mode 100644
index 000000000..387ca011b
--- /dev/null
+++ b/docs/context-propagator.md
@@ -0,0 +1,243 @@
+# ContextPropagator (design draft)
+
+> **Status: not implemented.** This document tracks the gap between sdk-php
+> and sdk-java/sdk-go and proposes the contract before code lands.
+
+## Why we need it
+
+Temporal SDKs in Java and Go ship a `ContextPropagator` mechanism: a pluggable
+hook that captures values from the caller's runtime (typically `MDC`,
+OpenTelemetry baggage, request-scoped IDs) and re-attaches them on the worker
+side before user code runs. The wire shape is a `Map<String, Payload>` carried
+under the workflow's `header` field (the Temporal interceptor `Header`,
+distinct from Nexus operation headers).
+
+Without it, sdk-php callers cannot propagate request-scoped diagnostic context
+across workflow boundaries — every cross-service call has to thread the
+context through application code by hand.
+
+The Nexus context-propagation sample
+([`samples-php/app/src/NexusContextPropagation`](https://github.com/temporalio/samples-php/tree/master/app/src/NexusContextPropagation))
+works around the gap by logging at the Nexus service-impl boundary instead of
+inside the started handler workflow body — this design lifts that limitation.
+
+## Java/Go reference shape
+
+```java
+interface ContextPropagator {
+    String getName();
+    Object getCurrentContext();
+    void setCurrentContext(Object context);
+    Map<String, Payload> serializeContext(Object context);
+    Object deserializeContext(Map<String, Payload> context);
+}
+```
+
+Registration:
+
+- `WorkflowClientOptions.setContextPropagators(...)` — applied on outbound RPC
+  (workflow start, signal, query, update). Captures and serialises the current
+  context into the request `Header`.
+- `WorkerFactoryOptions.setContextPropagators(...)` — applied inside the
+  worker. On every workflow / activity / nexus task pickup, the worker
+  deserialises the `Header` payloads back into propagator-specific objects and
+  calls `setCurrentContext()` so that user code in that task sees the values.
+
+## Proposed PHP shape
+
+### 1. Interface
+
+```php
+namespace Temporal\Common\ContextPropagator;
+
+use Temporal\Api\Common\V1\Payload;
+
+interface ContextPropagatorInterface
+{
+    /**
+     * Stable identifier — collisions across propagators are an error;
+     * the registry uses this to dedupe.
+     */
+    public function getName(): string;
+
+    /**
+     * Snapshot whatever the propagator considers "current context". The
+     * return type is opaque (mixed) so each propagator can use whatever
+     * shape it wants — array<string,string> for MDC-style, a value object,
+     * etc.
+     */
+    public function getCurrentContext(): mixed;
+
+    /**
+     * Restore a context object captured earlier by `getCurrentContext()` /
+     * deserialised by `deserializeContext()`. Called on the worker side
+     * before each workflow / activity / nexus task body runs.
+     */
+    public function setCurrentContext(mixed $context): void;
+
+    /**
+     * Serialise `$context` to a payload map keyed by string. The map gets
+     * merged into the request `Header` on the wire.
+     *
+     * @return array<string, Payload>
+     */
+    public function serializeContext(mixed $context): array;
+
+    /**
+     * Inverse of `serializeContext`. Receives the slice of the request
+     * `Header` whose keys this propagator owns (the registry filters by
+     * `getName()` prefix).
+     *
+     * @param array<string, Payload> $context
+     */
+    public function deserializeContext(array $context): mixed;
+}
+```
+
+### 2. Client-side registration
+
+Extend `Temporal\Client\ClientOptions`:
+
+```php
+public array $contextPropagators = [];
+
+public function withContextPropagators(ContextPropagatorInterface ...$ps): self
+{
+    $self = clone $this;
+    $self->contextPropagators = $ps;
+    return $self;
+}
+```
+
+`WorkflowClient::create()` already takes `ClientOptions`, so the registry
+flows in without API changes.
+
+### 3. Worker-side registration
+
+Extend `Temporal\Worker\WorkerOptions`:
+
+```php
+public array $contextPropagators = [];
+
+public function withContextPropagators(ContextPropagatorInterface ...$ps): self
+{
+    $self = clone $this;
+    $self->contextPropagators = $ps;
+    return $self;
+}
+```
+
+`WorkerFactory::newWorker(taskQueue, options: ...)` already accepts
+`WorkerOptions`. Default — empty array — keeps current behaviour.
+
+### 4. Outbound integration (client)
+
+Two boundaries care about it:
+
+| Outbound surface | Where to hook | What to do |
+|---|---|---|
+| `StartWorkflowExecutionRequest` | `Internal/Client/WorkflowStarter::executeRequest()` | call `serializeContext()` on each propagator, merge into `request.header.fields` |
+| `SignalWorkflowExecutionRequest`, `QueryWorkflowRequest`, `UpdateWorkflowExecutionRequest` | corresponding methods on `WorkflowStub` | same |
+| `Workflow::executeNexusOperation()` (caller workflow → server) | already passes a `HeaderInterface` through `ExecuteNexusOperation` request | propagator output merged into it |
+
+The merge rule: propagator payloads under their own keys; nothing collides
+with existing user headers. Order — propagator iteration order, last-write
+wins on key collision.
+
+### 5. Inbound integration (worker)
+
+Three task types need restoration:
+
+- **Workflow task**: in `Internal/Workflow/WorkflowDefinition::initialize()` (or
+  whichever runs before the workflow method body), iterate propagators and
+  call `setCurrentContext(deserializeContext(slice_of_header))`.
+- **Activity task**: in `ActivityWorker` dispatcher, same.
+- **Nexus operation task**: trickier — see next section.
+
+Cleanup is implicit because each PHP worker process handles tasks
+sequentially; the next `setCurrentContext` call overwrites stale state. For
+robustness we should still call `setCurrentContext(null)` (or a sentinel) at
+task end so a static/global-backed propagator doesn't leak between tasks.
+
+### 6. Nexus-specific wrinkle
+
+Nexus operations carry **two header maps** simultaneously:
+
+- `commonpb.Header` — Temporal interceptor header, payload-typed values. Same
+  thing workflows and activities use. ContextPropagator hooks into this.
+- `nexus.Header` — raw HTTP-style strings (`x-nexus-*`). Distinct concept,
+  travels on the Nexus wire to the handler's `OperationContext::$headers`.
+
+Java's `MDCContextPropagator` only deals with the **first**. The
+`NexusMDCContextInterceptor` is a separate piece that reads MDC at outbound
+time and writes the same value to the **second** map for handlers that don't
+share the propagator.
+
+For PHP we mirror the split:
+
+- `ContextPropagatorInterface` handles the workflow-style `Header` end-to-end.
+  This means caller workflow → started handler workflow body restoration
+  Just Works once both ends register the same propagator.
+- The Nexus operation headers (raw strings) stay a manual interceptor concern
+  — the existing `WorkflowOutboundCallsInterceptor::executeNexusOperation()` +
+  `OperationContext::$headers` paths are sufficient. No SDK change there.
+
+So with ContextPropagator landed, the
+[NexusContextPropagation sample](https://github.com/temporalio/samples-php/tree/master/app/src/NexusContextPropagation)
+can be simplified:
+
+```php
+// Caller workflow body
+$propagator->getCurrentContext()['x-caller-workflow-id'] = $workflowId;
+yield $sampleNexusService->hello($input);  // ContextPropagator captures
+// the workflow header automatically, no need for the explicit Nexus
+// outbound interceptor for this case.
+
+// Handler workflow body
+$id = $propagator->getCurrentContext()['x-caller-workflow-id'];
+// Available because the propagator was registered on the handler worker
+// and ran before the workflow method.
+```
+
+### 7. Wire format
+
+Already stable — it's `commonpb.Header`. PHP marshalling of `Header` already
+handles `Map<String, Payload>` round-trip via `EncodedCollection`. The
+outbound piece just needs to call propagators before the `Header` is
+finalised; the inbound piece already gets the deserialised header on
+`WorkflowInfo` / `ActivityInfo`.
+
+### 8. RR boundary
+
+No changes required: RR already forwards `commonpb.Header` between PHP and Go
+both ways. The Go SDK on the other side does **not** need any of this — the
+PHP worker is what runs `setCurrentContext()` for PHP user code.
+
+### 9. Test surface
+
+- Unit: each propagator's `serialize/deserialize` round-trips an arbitrary
+  context value through a fake `Header`.
+- Integration (functional): start a workflow with a registered propagator on
+  the client, assert the workflow body sees the restored context. Repeat for
+  signal / query / update.
+- Acceptance: one Nexus end-to-end test verifying a value set on the caller
+  worker shows up inside the handler workflow body without any Nexus header
+  plumbing.
+
+## Implementation phases
+
+1. **Phase A — interface + registry**: add `ContextPropagatorInterface`, plumb
+   through `ClientOptions` and `WorkerOptions`. No behaviour change yet.
+2. **Phase B — outbound on workflow start**: serialise into start-request
+   header; functional test for the start path.
+3. **Phase C — inbound on workflow task**: deserialise + restore. Functional
+   test for round-trip.
+4. **Phase D — signal/query/update + activities**: same plumbing on the
+   smaller surfaces.
+5. **Phase E — Nexus integration**: ensure propagator output rides on the
+   ExecuteNexusOperation `Header`; verify handler workflow body sees the
+   restored context. Update the
+   [NexusContextPropagation sample](https://github.com/temporalio/samples-php/tree/master/app/src/NexusContextPropagation)
+   to use the propagator instead of the static `MDC` workaround.
+
+Each phase is independently mergeable and each carries its own test layer.
diff --git a/docs/data-conversion/README.md b/docs/data-conversion/README.md
new file mode 100644
index 000000000..5e56a8962
--- /dev/null
+++ b/docs/data-conversion/README.md
@@ -0,0 +1,53 @@
+# Data conversion и payloads
+
+Через [src/DataConverter/](../../src/DataConverter/) проходят **все** аргументы и результаты workflow'ов, activity'ей, query/signal/update, Nexus operations, а также `details` в failure'ах и `Memo`/`SearchAttributes` в start-options. Понимание этой подсистемы нужно прежде чем разговор про любую сериализацию вообще.
+
+## Содержание
+
+| Документ | О чём |
+|---|---|
+| [Архитектура](architecture.md) | Слои, цепочка `PayloadConverter`'ов по умолчанию, `EncodedValues` vs `EncodedCollection`, `Type`, `RawValue`, `Bytes` |
+| [Marshaller](marshaller.md) | Как `JsonConverter` сериализует DTO: `Marshaller` + `AttributeMapper` + регистр типов, `#[Marshal]`, `EncodedCollectionType`, обратный путь `ProtoToArrayConverter` |
+| [Интеграция](integration.md) | Где `DataConverter` создаётся и инжектится, поздняя инъекция через `setDataConverter`, codec wire-boundary, таблица routes, Nexus payload, failures |
+| [Serialization context](serialization-context.md) | `SerializationContext` для converter'ов: подпись/шифрование payload по `workflowId`; где проставляется; расхождения с Java/Go (memo, SA, codec) |
+
+## Quick reference
+
+```php
+// Дефолтная цепочка (порядок имеет значение).
+$converter = DataConverter::createDefault();
+//   1. NullConverter        binary/null
+//   2. BinaryConverter      binary/plain     (Bytes)
+//   3. ProtoJsonConverter   json/protobuf    (proto Message — приоритет!)
+//   4. ProtoConverter       binary/protobuf  (proto Message)
+//   5. JsonConverter        json/plain       (всё остальное → Marshaller)
+
+// Один payload.
+$payload = $converter->toPayload($value);
+$value   = $converter->fromPayload($payload, MyDto::class);
+
+// Список payload'ов (args/return).
+$values = EncodedValues::fromValues([$arg1, $arg2]);     // workflow-side: без converter
+$values = EncodedValues::fromPayloads($payloads, $conv); // wire-side: с converter
+$arg    = $values->getValue(0, MyDto::class);            // ленивая декодировка
+
+// Assoc-коллекция (Header / Memo / SearchAttributes).
+$header = Header::fromValues(['x-tenant' => 'acme']);
+$memo   = EncodedCollection::fromPayloadCollection($proto->getFields(), $conv);
+
+// Bypass: payload идёт через все слои нетронутым.
+$raw = new RawValue(new Payload(['data' => '...']));
+```
+
+## Главные принципы
+
+- **`ValuesInterface` — канон.** Тип параметров/возврата для аргументов и результатов — `ValuesInterface`. `EncodedValues` используется только как factory в момент конструирования (зафиксировано в `feedback_values_interface_canon`).
+- **Поздняя инъекция converter'а.** `EncodedValues::fromValues($args)` без converter'а — допустимая полу-инициализация. Converter подставляется ниже по стеку (codec encoder, `WorkflowStarter`, `FailureConverter`) перед `toPayloads()`. См. [интеграцию](integration.md#late-injection).
+- **`RawValue` — публичный escape hatch.** Не internal. `RawValue` идёт unmodified через любые слои включая wire — нужно когда payload должен пройти насквозь без декодирования.
+- **Marshaller — отдельная подсистема.** `JsonConverter` использует её для DTO ↔ JSON; те же самые `Marshaller` и `MarshallerInterface` дополнительно работают с `options` от RR (workflow/activity options приходят уже-десериализованным JSON-array, не payload-каналом). См. [marshaller.md](marshaller.md).
+
+## Связанное
+
+- [Wire-протокол PHP↔RR](../runtime/worker-rr-protocol.md) — где decoder вызывает `EncodedValues::fromPayloads()` и encoder сериализует обратно.
+- [Nexus handler-side SDK](../nexus/handler-side-sdk.md) — handler принимает один payload, обёрнутый в `ValuesInterface` для единообразия.
+- [Plugins](../plugins.md) — `WorkerFactoryPluginContext`/`ClientPluginContext` позволяют плагину подменить converter.
diff --git a/docs/data-conversion/architecture.md b/docs/data-conversion/architecture.md
new file mode 100644
index 000000000..af0b909f6
--- /dev/null
+++ b/docs/data-conversion/architecture.md
@@ -0,0 +1,109 @@
+# Архитектура data-conversion подсистемы
+
+Слои подсистемы и контракты — то, что должно быть в голове прежде чем смотреть на любой код, который сериализует или десериализует payload.
+
+## Слои
+
+```
+       wire bytes (Payload protobuf)
+                ↓
+    PayloadConverterInterface[]      ← Null, Binary, ProtoJson, Proto, Json
+                ↓
+    DataConverterInterface           ← chain (encoding → converter)
+                ↓
+    EncodedValues / EncodedCollection / RawValue
+                ↓
+    PHP value (scalar / DTO / proto Message / Bytes / RawValue / EncodedCollection)
+```
+
+## Контракты
+
+| Интерфейс | Файл | Зачем |
+|---|---|---|
+| `DataConverterInterface` | [src/DataConverter/DataConverterInterface.php](../../src/DataConverter/DataConverterInterface.php) | `fromPayload(Payload, type)` / `toPayload(value)` — высокоуровневая обёртка над цепочкой |
+| `PayloadConverterInterface` | [src/DataConverter/PayloadConverterInterface.php](../../src/DataConverter/PayloadConverterInterface.php) | Низкоуровневый converter одного encoding'а: `getEncodingType()`, `toPayload()`, `fromPayload()` |
+| `ValuesInterface` | [src/DataConverter/ValuesInterface.php](../../src/DataConverter/ValuesInterface.php) | **Канон** для типизации параметров/возврата — `getValue(int, type)`, `count()`, `toPayloads()` |
+
+Базовый класс [Converter](../../src/DataConverter/Converter.php) выставляет `metadata.encoding` на исходящий `Payload`.
+
+## Цепочка по умолчанию
+
+[`DataConverter::createDefault()`](../../src/DataConverter/DataConverter.php:34) собирает массив, проиндексированный по encoding-string ([EncodingKeys](../../src/DataConverter/EncodingKeys.php)):
+
+| order | converter | encoding | matches when... |
+|---|---|---|---|
+| 1 | [NullConverter](../../src/DataConverter/NullConverter.php) | `binary/null` | `$value === null` |
+| 2 | [BinaryConverter](../../src/DataConverter/BinaryConverter.php) | `binary/plain` | `$value instanceof Bytes` |
+| 3 | [ProtoJsonConverter](../../src/DataConverter/ProtoJsonConverter.php) | `json/protobuf` | `$value instanceof Google\Protobuf\Internal\Message` |
+| 4 | [ProtoConverter](../../src/DataConverter/ProtoConverter.php) | `binary/protobuf` | `$value instanceof Google\Protobuf\Internal\Message` |
+| 5 | [JsonConverter](../../src/DataConverter/JsonConverter.php) | `json/plain` | всё остальное |
+
+### Как работает диспатч
+
+- **toPayload** ([DataConverter.php:79](../../src/DataConverter/DataConverter.php:79)) пробегает converter'ы по порядку, берёт первый, кто вернул не-null. Каждый converter сам решает, может ли он сериализовать значение, через `instanceof`-проверку и возвращает `null`, если не может.
+- **fromPayload** ([DataConverter.php:48](../../src/DataConverter/DataConverter.php:48)) сначала смотрит `metadata.encoding` payload'а и матчит на конкретный converter по encoding-ключу. Плюс короткие фастпасы для `void/null/true/false` через target-type.
+
+> **Тонкость с порядком.** ProtoJson стоит **раньше** Proto — по умолчанию любой `Google\Protobuf\Internal\Message` уйдёт в `json/protobuf`, а не в `binary/protobuf`. Если нужен binary — собирай `DataConverter` руками с переставленным порядком.
+
+> **`EncodingKeys::METADATA_ENCODING_RAW_VALUE = 'binary'`** ([EncodingKeys.php:20](../../src/DataConverter/EncodingKeys.php:20)) — задекларирован, но никем не используется. Не путать с `binary/plain` (BinaryConverter) и `binary/protobuf` (ProtoConverter).
+
+## RawValue: bypass через все слои
+
+[`RawValue`](../../src/DataConverter/RawValue.php) — это публичный escape hatch:
+
+- `toPayload` отдаёт inner payload как есть ([DataConverter.php:81](../../src/DataConverter/DataConverter.php:81)).
+- `fromPayload` вернёт `RawValue`, если target-type запрошен `RawValue::class` ([DataConverter.php:52](../../src/DataConverter/DataConverter.php:52)).
+
+Acceptance-тест [tests/Acceptance/Extra/DataConverter/RawValueTest.php](../../tests/Acceptance/Extra/DataConverter/RawValueTest.php) подтверждает контракт: workflow создаёт `RawValue(new Payload(['data' => 'hello world']))`, прокидывает через activity и получает обратно тот же payload. Это легальный канал передачи "нерасшифрованного" payload через workflow/activity-границу.
+
+## Bytes: typed wrapper для `binary/plain`
+
+[`Bytes`](../../src/DataConverter/Bytes.php) — отдельный typed wrapper для бинарных payload'ов. Не `string`-as-bytes — именно `Bytes` instance. `BinaryConverter::fromPayload` требует `$type === Bytes::class` и рефьюзит остальное ([BinaryConverter.php:41-46](../../src/DataConverter/BinaryConverter.php:41)).
+
+## Type-сообщения
+
+[`Type`](../../src/DataConverter/Type.php) — DTO, описывающий целевой тип. Конструируется из любой формы: `string | ReflectionClass | ReflectionType | ReturnType | self`. Свойства: `name`, `allowsNull`, `isArrayOf`.
+
+```php
+Type::create($x);              // нормализатор любой входной формы
+Type::arrayOf(SomeDto::class); // коллекция DTO
+$type->isClass();              // class_exists($name)
+$type->allowsNull();           // для void/null путей
+```
+
+`@psalm-type TType = string|\ReflectionClass|\ReflectionType|Type|null` — это форма, которая везде ходит как параметр `getValue`/`fromPayload`.
+
+## EncodedValues vs EncodedCollection
+
+| | [EncodedValues](../../src/DataConverter/EncodedValues.php) | [EncodedCollection](../../src/DataConverter/EncodedCollection.php) |
+|---|---|---|
+| Ключи | целые (positional) | произвольные `array-key` (assoc) |
+| Используется для | args/return workflow/activity/query/signal/update/Nexus, heartbeat details, failure details | Header / Memo / SearchAttributes |
+| State | либо `payloads` (Traversable&ArrayAccess&Countable), либо `values` (raw PHP) | оба сосуществуют — `values` overrides `payloads` per-key |
+| Ленивость | `getValue(i, $type)` декодирует только нужный | `getValue(name, type)` тоже ленивый |
+| `setDataConverter` | поздняя инъекция (см. [интеграцию](integration.md#late-injection)) | то же |
+
+Обе сделаны как `private __construct` + статические фабрики:
+
+```php
+EncodedValues::empty();
+EncodedValues::fromValues([$arg1, $arg2]);
+EncodedValues::fromPayloads($payloads, $converter);
+EncodedValues::fromPayloadCollection($iter, $converter);
+```
+
+У `EncodedValues` ещё:
+
+- **`sliceValues(converter, values, offset, len)`** ([EncodedValues.php:63](../../src/DataConverter/EncodedValues.php:63)) — split payloads. Используется в `InvokeActivity` для отщепления `heartbeatDetails` от args, и в `StartWorkflow` для отщепления `lastCompletionResult`.
+- **`decodePromise(promise, type)`** ([EncodedValues.php:82](../../src/DataConverter/EncodedValues.php:82)) — оборачивает promise так, чтобы при разрешении `ValuesInterface::getValue(0, type)` декодировал результат. Используется во всех stub'ах: `ActivityStub`, `ChildWorkflowStub`, `NexusOperationStub`, `SideEffect`.
+
+Обе знают void-семантику: `getValue(0, $voidType)` на пустых payloads вернёт `null` ([EncodedValues.php:185](../../src/DataConverter/EncodedValues.php:185)). `isVoidType` принимает `null`, строки `void/null/mixed`, `Type::allowsNull()`, `ReturnType::nullable`, `ReflectionNamedType/UnionType::allowsNull()`.
+
+## Header как EncodedCollection
+
+[`Temporal\Interceptor\Header`](../../src/Interceptor/Header.php) — это `final class Header extends EncodedCollection implements HeaderInterface`. Метод `toHeader(): ProtoHeader` собирает proto-Header из `toPayloadArray()`. Это и есть тот самый "header conversion path" — и в обратную сторону EncodedCollection умеет специализироваться на `Header/Memo/SearchAttributes/Payloads` через [EncodedCollectionType](../../src/Internal/Marshaller/Type/EncodedCollectionType.php) (см. [marshaller.md](marshaller.md#encodedcollectiontype)).
+
+## См. также
+
+- [Marshaller](marshaller.md) — как `JsonConverter` ходит в DTO через рефлексию.
+- [Интеграция](integration.md) — где converter реально вызывается на путях workflow/activity/Nexus/client.
diff --git a/docs/data-conversion/integration.md b/docs/data-conversion/integration.md
new file mode 100644
index 000000000..9e817c050
--- /dev/null
+++ b/docs/data-conversion/integration.md
@@ -0,0 +1,123 @@
+# Интеграция: где converter реально вызывается
+
+Карта мест, где `DataConverter` / `EncodedValues` / `EncodedCollection` создаются и инжектятся в системе. Без этого разговор про сериализацию повисает в воздухе — converter сам по себе ничего не делает, важен путь от его конструирования до реального `toPayload`/`fromPayload`-вызова.
+
+## Где DataConverter создаётся
+
+| Место | Как |
+|---|---|
+| [WorkerFactory ctor](../../src/WorkerFactory.php:120) | required ctor arg + `WorkerFactoryPluginContext.dataConverter` для override плагинами |
+| [WorkerFactory::create](../../src/WorkerFactory.php:153) | static factory, default `DataConverter::createDefault()` |
+| [WorkflowClient ctor](../../src/Client/WorkflowClient.php:81) | optional ctor arg + `ClientPluginContext` override; default → createDefault |
+| [ScheduleClient ctor](../../src/Client/ScheduleClient.php:58) | то же что у WorkflowClient |
+| [ScheduleHandle](../../src/Client/Schedule/ScheduleHandle.php:38), [UpdateHandle](../../src/Client/Update/UpdateHandle.php:32) | required ctor arg, инжектится из родительского клиента |
+| [JsonCodec / ProtoCodec](../../src/WorkerFactory.php:367) | конструируются в `WorkerFactory` из `$this->converter` после плагинного override |
+| [NexusTaskHandler](../../src/Internal/Nexus/NexusTaskHandler.php:58) | required ctor arg |
+| [ActivityInvocationCache](../../src/Worker/ActivityInvocationCache/RoadRunnerActivityInvocationCache.php:30) | optional, default → createDefault (для testing) |
+
+`WorkerFactory` дополнительно создаёт [`Marshaller`](../../src/WorkerFactory.php:350) (`new Marshaller(new AttributeMapperFactory($reader))`) и кладёт его в `ServiceContainer`, откуда его берут все routes.
+
+## Wire-граница: codec ↔ router
+
+Decoder ([JsonCodec/Decoder.php](../../src/Worker/Transport/Codec/JsonCodec/Decoder.php)) принимает массив-команду от RR и:
+
+1. base64-декодит `payloads` → `Payloads` proto.
+2. base64-декодит `header` → `Header` proto.
+3. Заворачивает через `EncodedValues::fromPayloads($payloads, $dataConverter)` и `Header::fromPayloadCollection($headers->getFields(), $dataConverter)` ([Decoder.php:64-66](../../src/Worker/Transport/Codec/JsonCodec/Decoder.php:64)).
+4. Конструирует `ServerRequest` (или `SuccessResponse` / `FailureResponse`).
+
+Encoder ([JsonCodec/Encoder.php](../../src/Worker/Transport/Codec/JsonCodec/Encoder.php)) — обратный путь. Тонкость: **converter инжектится в payloads через `setDataConverter()`** прямо перед сериализацией ([Encoder.php:37, 41, 71](../../src/Worker/Transport/Codec/JsonCodec/Encoder.php:37)).
+
+`ProtoCodec` параллелен; codec выбирается через `$_SERVER['RR_CODEC']` в [WorkerFactory.php:367](../../src/WorkerFactory.php:367).
+
+## <a id="late-injection"></a>Поздняя инъекция converter'а
+
+`EncodedValues::fromValues($args)` без converter'а — это допустимая полу-инициализация: state-машина "values without converter". Converter добавляется позже, когда payloads реально нужны:
+
+| Где инжектится | Файл |
+|---|---|
+| Workflow → wire (codec encoder) | [JsonCodec/Encoder.php:37, 71](../../src/Worker/Transport/Codec/JsonCodec/Encoder.php:37) |
+| Client → server (start request) | [WorkflowStarter.php:177, 409](../../src/Internal/Client/WorkflowStarter.php:177) |
+| Update args (start update) | [WorkflowStub.php:291](../../src/Internal/Client/WorkflowStub.php:291) |
+| Schedule memo / SA | [ScheduleClient.php:116-117](../../src/Client/ScheduleClient.php:116) |
+| Schedule action | [ScheduleMapper.php:35-38](../../src/Internal/Mapper/ScheduleMapper.php:35) |
+| Failure details | [TemporalFailure.php:80](../../src/Exception/Failure/TemporalFailure.php:80) (override'ы в `ApplicationFailure`/`CanceledFailure`/`TimeoutFailure`) |
+
+`getValue()` на values-без-converter не падает, **если индекс уже есть в `$values`-массиве** ([EncodedValues.php:125](../../src/DataConverter/EncodedValues.php:125)) — converter нужен только когда лезут в `payloads[]`.
+
+## Routes (worker-side)
+
+Каждый route десериализует входной `payloads` через `EncodedValues` (декодеру оно уже передано codec'ом) и сериализует результат через `EncodedValues::fromValues()`.
+
+| Route | Вход (`payloads`) | Выход (`resolver->resolve`) |
+|---|---|---|
+| [StartWorkflow](../../src/Internal/Transport/Router/StartWorkflow.php:47) | wf args + (опц.) `lastCompletionResult` — `sliceValues` | `EncodedValues::fromValues([null])` (start ack) |
+| [InvokeActivity](../../src/Internal/Transport/Router/InvokeActivity.php:52) | activity args + (опц.) `heartbeatDetails` — `sliceValues` | `EncodedValues::fromValues([$result])` |
+| [InvokeQuery](../../src/Internal/Transport/Router/InvokeQuery.php:91) | query args | `EncodedValues::fromValues([$result])` |
+| [InvokeSignal](../../src/Internal/Transport/Router/InvokeSignal.php) | signal args | `EncodedValues::fromValues([null])` |
+| [InvokeUpdate](../../src/Internal/Transport/Router/InvokeUpdate.php:53) | update args через `UpdateInput` | `EncodedValues::fromValues([$value])` через `UpdateResponse` |
+| [CancelNexusOperation](../../src/Internal/Transport/Router/CancelNexusOperation.php) | token | `EncodedValues::fromValues([null])` |
+
+Workflow input создаётся в [Input](../../src/Internal/Workflow/Input.php) — DTO с тремя полями (`info: WorkflowInfo`, `input: ValuesInterface`, `header: Header`). Marshaller'ом распаковывается из `options['info']`, а `input`/`header` присваиваются из request'а руками ([StartWorkflow.php:65-70](../../src/Internal/Transport/Router/StartWorkflow.php:65)).
+
+`StartWorkflow` отдельно конвертирует `Memo` и `SearchAttributes` через `EncodedCollection::fromPayloadCollection` ([StartWorkflow.php:122](../../src/Internal/Transport/Router/StartWorkflow.php:122)) — payload-коллекция из proto разворачивается в `EncodedCollection` с лениво-декодируемыми value'ами.
+
+## Workflow stubs (caller-side)
+
+| Stub | Файл | Что делает |
+|---|---|---|
+| `ActivityStub` | [ActivityStub.php:65](../../src/Internal/Workflow/ActivityStub.php:65) | `EncodedValues::fromValues($args)` → `ExecuteActivity` request, `decodePromise()` на response |
+| `ChildWorkflowStub` | [ChildWorkflowStub.php](../../src/Internal/Workflow/ChildWorkflowStub.php) | Аналогично через `ExecuteChildWorkflow` |
+| `NexusOperationStub` | [NexusOperationStub.php:73](../../src/Internal/Workflow/NexusOperationStub.php:73) | `EncodedValues::fromValues($args)` → `ExecuteNexusOperation` request |
+| `ExternalWorkflowStub` | [ExternalWorkflowStub.php](../../src/Internal/Workflow/ExternalWorkflowStub.php) | Сигналы внешнему workflow |
+| `WorkflowContext::sideEffect()` | [WorkflowContext.php:285](../../src/Internal/Workflow/WorkflowContext.php:285) | Оборачивает значение в `EncodedValues::fromValues([$value])` для записи в history |
+
+Все они создают `EncodedValues` без converter'а — он подставляется ниже, в codec encoder'е.
+
+## Nexus
+
+Nexus payload — **один**, не список. Всё равно заворачивается в `ValuesInterface` для единообразия с остальной частью SDK.
+
+Caller-side (workflow → RR):
+- [`NexusOperationStub::start()`](../../src/Internal/Workflow/NexusOperationStub.php:73) пакует `args: EncodedValues::fromValues($args)` в `ExecuteNexusOperation`.
+
+Handler-side (RR → handler):
+- [`NexusTaskHandler::buildInputFromPayload()`](../../src/Internal/Nexus/NexusTaskHandler.php:310) принимает один `Payload` от RR → `Payloads{[$payload]}` → `EncodedValues::fromPayloads(...)`.
+- [`ServiceHandler::startOperation()`](../../src/Nexus/Handler/Internal/ServiceHandler.php:103) декодирует input через `$input->getValue(0, $definition->inputType)` где `$definition->inputType` извлечён из `#[Operation]/#[AsyncOperation]` атрибута. На ошибке десериализации — `HandlerException(BadRequest)`.
+- [`ServiceHandler::encodeResult()`](../../src/Nexus/Handler/Internal/ServiceHandler.php:231) — **прямой** `dataConverter->toPayload($result)` (не через `EncodedValues::fromValues()`), потом `Payloads{[$payload]}` обратно в `EncodedValues`. На ошибке — `HandlerException(Internal)`.
+- [`NexusTaskHandler::startOperationDirect()`](../../src/Internal/Nexus/NexusTaskHandler.php:223) — путь без proto `Response`-обёртки (для прямого RR-вызова): для async ставит `payload.data = token`, `payload.metadata` `[KIND_KEY => KIND_ASYNC, LINKS_KEY => json]`. Это тот wire-shape, который зафиксирован в `project_nexus_caller_wire_design`.
+
+## Failures
+
+`details`/`heartbeatDetails` в failure'ах — это `ValuesInterface`, и для них действует то же правило поздней инъекции converter'а:
+
+- [`TemporalFailure::setDataConverter`](../../src/Exception/Failure/TemporalFailure.php:80) — пустой no-op в базе.
+- Override'ится в [ApplicationFailure](../../src/Exception/Failure/ApplicationFailure.php:99), [CanceledFailure](../../src/Exception/Failure/CanceledFailure.php:33), [TimeoutFailure](../../src/Exception/Failure/TimeoutFailure.php:48) — пробрасывает converter в `details`/`lastHeartbeatDetails`.
+- [`FailureConverter::mapExceptionToFailure`](../../src/Exception/Failure/FailureConverter.php:55) сначала вызывает `e->setDataConverter`, потом дёргает `details->toPayloads()`.
+
+Получение failure'а на client-side — [`FailureConverter::mapFailureToException`](../../src/Exception/Failure/FailureConverter.php:43) — обратный путь: разворачивает proto Failure в SDK-исключение и кладёт converter внутрь, чтобы `getDetails()` мог декодировать на ленивом доступе.
+
+## Client-side: декодирование response'ов
+
+[`ResponseToResultMapper::mapUpdateWorkflowResponse`](../../src/Internal/Client/ResponseToResultMapper.php:55) — пример client-side декодирования: payload'ы из `UpdateWorkflowExecutionResponse` оборачиваются в `EncodedValues::fromPayloads($success, $this->converter)`. Дальше caller вызовет `getValue(0, $type)` с нужным типом.
+
+Аналогично `WorkflowStub::getResult()` декодирует workflow result через `EncodedValues::fromPayloads()`.
+
+## Plugin override
+
+Плагины могут подменить converter в трёх контекстах:
+
+| Контекст | Метод |
+|---|---|
+| [`WorkerFactoryPluginContext`](../../src/Plugin/WorkerFactoryPluginContext.php:32) | `setDataConverter(?DataConverterInterface)` — применяется в [WorkerFactory ctor](../../src/WorkerFactory.php:148) до создания codec'а |
+| [`ClientPluginContext`](../../src/Plugin/ClientPluginContext.php:49) | то же для `WorkflowClient` |
+| [`ScheduleClientPluginContext`](../../src/Plugin/ScheduleClientPluginContext.php:45) | то же для `ScheduleClient` |
+
+Это единственный поддерживаемый способ глобально подменить converter — например, навесить шифрование payload'ов через chain decorator.
+
+## См. также
+
+- [Архитектура](architecture.md) — converter chain и контракты.
+- [Marshaller](marshaller.md) — DTO ↔ array через рефлексию.
+- [Wire-протокол PHP↔RR](../runtime/worker-rr-protocol.md) — что codec делает с payload'ом.
+- [Plugins](../plugins.md) — как подменить converter глобально.
diff --git a/docs/data-conversion/marshaller.md b/docs/data-conversion/marshaller.md
new file mode 100644
index 000000000..3c59aa0d4
--- /dev/null
+++ b/docs/data-conversion/marshaller.md
@@ -0,0 +1,123 @@
+# Marshaller
+
+`JsonConverter` — **не** простой `json_encode`-обёртка. Для объектов он делегирует в [src/Internal/Marshaller/](../../src/Internal/Marshaller/) — самостоятельную подсистему DTO ↔ array на рефлексии и `Spiral\Attributes`.
+
+## Когда `JsonConverter` идёт в `Marshaller`
+
+[`JsonConverter::toPayload()`](../../src/DataConverter/JsonConverter.php:53) обрабатывает объекты так:
+
+| Тип | Что делает |
+|---|---|
+| `\stdClass` | as-is, потом `json_encode` |
+| `UuidInterface` | `->toString()` |
+| `\DateTimeInterface` | RFC3339 |
+| **остальное** | `Marshaller::marshal($value)` → array → `json_encode` |
+
+На входе `fromPayload` ([JsonConverter.php:75](../../src/DataConverter/JsonConverter.php:75)) — обратная схема: для `class-string` target-type'а (не `string/int/array/...`) идёт `Marshaller::unmarshal($hashmap, $reflection->newInstanceWithoutConstructor())`.
+
+`Marshaller` создаётся в конструкторе `JsonConverter` дефолтным методом [`createDefaultMarshaller()`](../../src/DataConverter/JsonConverter.php:178):
+
+```php
+new Marshaller(new AttributeMapperFactory(self::createDefaultReader()));
+```
+
+`createDefaultReader()` использует `Doctrine\Common\Annotations\Reader` если он доступен (composite `SelectiveReader([new AnnotationReader(), new AttributeReader()])`), иначе только `AttributeReader`.
+
+## Marshaller: что он делает
+
+[`Marshaller`](../../src/Internal/Marshaller/Marshaller.php) — рефлексия + кэш мапперов на класс.
+
+| Метод | Что делает |
+|---|---|
+| `marshal(object): array` | Идёт по `mapper->getGetters()`, собирает hashmap |
+| `unmarshal(array, object): object` | Идёт по `mapper->getSetters()`, заполняет существующий instance |
+
+Mapper для класса собирается лениво и кэшируется в `$mappers[$class]`. Для `\stdClass` — fast-path без mapper'а.
+
+## AttributeMapper: getter/setter на свойство
+
+[`AttributeMapper`](../../src/Internal/Marshaller/Mapper/AttributeMapper.php) для каждого свойства класса собирает пару `Closure` getter/setter. Логика выбора `TypeInterface` для свойства:
+
+1. **`#[Marshal(...)]` атрибут** ([Marshal.php](../../src/Internal/Marshaller/Meta/Marshal.php)) — `name`, `type`, `of`, `nullable`. Можно навесить несколько (берётся первый по порядку).
+2. **`TypeFactory::makeRule()`** ([TypeFactory.php:89](../../src/Internal/Marshaller/TypeFactory.php:89)) — пробегает встроенные `RuleFactoryInterface` и возвращает `MarshallingRule`.
+3. **`TypeFactory::detect()`** — смотрит `\ReflectionType` свойства и матчит через `DetectableTypeInterface::match`.
+
+## Регистр встроенных типов
+
+Порядок матчинга (важен — первый совпавший побеждает) в [TypeFactory.php:127](../../src/Internal/Marshaller/TypeFactory.php:127):
+
+```
+EnumType → EnumValueType → DateTimeType → DateIntervalType
+→ UuidType → ArrayType → EncodedCollectionType → ObjectType
+```
+
+`ObjectType` стоит последним как catch-all для не-builtin классов.
+
+## EncodedCollectionType
+
+[`EncodedCollectionType`](../../src/Internal/Marshaller/Type/EncodedCollectionType.php) — особенный. Это тот мост, через который `EncodedCollection` свойства DTO становятся proto-сообщениями.
+
+При serialize ([EncodedCollectionType.php:78](../../src/Internal/Marshaller/Type/EncodedCollectionType.php:78)) умеет специализироваться на target-классе через `marshalTo`:
+
+```php
+match ($this->marshalTo) {
+    SearchAttributes::class => (new SearchAttributes())->setIndexedFields($payloads),
+    Memo::class             => (new Memo())->setFields($payloads),
+    Payloads::class         => (new Payloads())->setPayloads($payloads),
+    Header::class           => (new Header())->setFields($payloads),
+    default                 => throw ...,
+};
+```
+
+Это и есть header/memo conversion path: DTO с `EncodedCollection`-свойством получает корректный proto-message при сериализации.
+
+При parse ([EncodedCollectionType.php:55](../../src/Internal/Marshaller/Type/EncodedCollectionType.php:55)) принимает `null` (→ empty), `array` (→ `fromValues`), или уже-готовый `EncodedCollection` (passthrough).
+
+## Marshal атрибут
+
+[`Marshal`](../../src/Internal/Marshaller/Meta/Marshal.php) extends `MarshallingRule`. Применяется к свойству и переопределяет авто-detection:
+
+```php
+class WorkflowInfo
+{
+    #[Marshal(name: 'TaskQueue')]
+    public string $taskQueue;
+
+    #[Marshal(name: 'Memo', of: Memo::class)]
+    public ?EncodedCollection $memo = null;
+}
+```
+
+`Marshal` — `IS_REPEATABLE`: можно навесить несколько rule'ов на одно свойство (полезно для нескольких возможных wire-имён вроде `UserName` / `user_name`). Первый — приоритетный для marshalling, остальные — fallback'и для unmarshalling.
+
+## Обратный путь: ProtoToArrayConverter
+
+[`ProtoToArrayConverter`](../../src/Internal/Marshaller/ProtoToArrayConverter.php) — конвертит proto-Message в обычный hashmap-array, рекурсивно. При этом известные сообщения разворачиваются в SDK-типы:
+
+| proto-Message | → |
+|---|---|
+| `Timestamp` | `\DateTimeImmutable` |
+| `Duration` | `\DateInterval` |
+| `SearchAttributes` | `EncodedCollection::fromPayloadCollection($input->getIndexedFields(), $converter)` |
+| `Memo` | `EncodedCollection::fromPayloadCollection($input->getFields(), $converter)` |
+| `Payloads` | `EncodedValues::fromPayloadCollection($input->getPayloads(), $converter)` |
+| `Header` | `Header::fromPayloadCollection($input->getFields(), $converter)` |
+| `ScheduleAction`, `UserMetadata` | специальные мапперы |
+| остальное | рекурсивный walk через `\ReflectionClass` |
+
+Используется на client-side, когда сервер вернул workflow-result/heartbeat/schedule-state с проторованными полями, и их надо отдать пользовательскому коду в виде PHP-объектов с `EncodedCollection`-свойствами.
+
+## Где Marshaller инжектится глобально
+
+[`WorkerFactory::createMarshaller()`](../../src/WorkerFactory.php:350) собирает один `Marshaller` на воркер-фабрику и кладёт в `ServiceContainer` ([WorkerFactory.php:358](../../src/WorkerFactory.php:358)). Все routes ([InvokeActivity](../../src/Internal/Transport/Router/InvokeActivity.php:75), [StartWorkflow](../../src/Internal/Transport/Router/StartWorkflow.php:65), …) берут его оттуда:
+
+```php
+$context = $this->services->marshaller->unmarshal($options, $context);
+```
+
+> **Тонкость.** Это **другой канал** сериализации — не payload-канал. `options` приходят от RR в виде уже-десериализованного JSON-array (workflow info, activity options, heartbeat thresholds и т.д.) и заполняют DTO-поля контекста. Payload-канал (args/return) идёт через `EncodedValues` → `DataConverter` → `JsonConverter` → `Marshaller`. То есть `Marshaller` стоит на пересечении обоих каналов.
+
+## См. также
+
+- [Архитектура](architecture.md) — общая картина converter chain.
+- [Интеграция](integration.md) — где `JsonConverter` и `Marshaller` реально вызываются.
diff --git a/docs/data-conversion/serialization-context.md b/docs/data-conversion/serialization-context.md
new file mode 100644
index 000000000..b869345fd
--- /dev/null
+++ b/docs/data-conversion/serialization-context.md
@@ -0,0 +1,37 @@
+# Serialization context
+
+Контекст сериализации даёт кастомному `PayloadConverter`'у знать, **в рамках какого workflow/activity** (де)сериализуется payload — чтобы, например, подписать/зашифровать его ключом, производным от `workflowId` (защита от replay). Фича-паритет с Java ([PR#1695](https://github.com/temporalio/sdk-java/pull/1695)) и Go ([#1352](https://github.com/temporalio/sdk-go/issues/1352)); spec — [features#434](https://github.com/temporalio/features/issues/434), тикет — [#587](https://github.com/temporalio/sdk-php/issues/587).
+
+## Контракт
+
+- [`SerializationContext`](../../src/DataConverter/SerializationContext.php) — маркер. Подтипы:
+  - [`WorkflowSerializationContext`](../../src/DataConverter/WorkflowSerializationContext.php) — `{namespace, workflowId}`.
+  - [`ActivitySerializationContext`](../../src/DataConverter/ActivitySerializationContext.php) — `+ {workflowType?, activityType?, taskQueue?, isLocal}`.
+  - [`HasWorkflowSerializationContext`](../../src/DataConverter/HasWorkflowSerializationContext.php) — общий геттер `getNamespace()`/`getWorkflowId()` (workflowId может быть `null` для standalone-activity).
+- [`SerializationContextAwareInterface::withSerializationContext()`](../../src/DataConverter/SerializationContextAwareInterface.php) — converter opt-in. `DataConverter` реализует и переоборачивает context-aware sub-converter'ы; non-aware остаются как есть.
+- [`SerializationContextBinder::bind($converter, $context)`](../../src/DataConverter/SerializationContextBinder.php) — `$context === null` или non-aware converter → возвращает converter без изменений.
+- `ValuesInterface`/`EncodedValues`/`EncodedCollection` несут `set/getSerializationContext()`; контекст применяется лениво в `toPayloads()`/`getValue()` через мемоизированный bound-converter (инвалидируется в `setDataConverter`/`setSerializationContext`).
+
+## Где контекст проставляется
+
+Worker-side и client-side, симметрично encode/decode: workflow in/out, side effect, continue-as-new, activity in/out/failure/heartbeat (+ retry-input), child workflow, signal (internal/external/client/with-start), query, update (worker+client+with-start), async-completion client (все overload'ы), `describe()` pending-activity, **schedule action input + memo**, client result/failure/cancel. Wire-корреляция request→response контекста — в [`Internal/Transport/Client.php`](../../src/Internal/Transport/Client.php).
+
+Schedule action: контекст ставится на **запись** ([`ScheduleMapper::toMessage`](../../src/Internal/Mapper/ScheduleMapper.php)) и на **чтение** ([`ScheduleHandle::describe`](../../src/Client/Schedule/ScheduleHandle.php)) — для `input` и `memo`, по `action.workflowId`. `searchAttributes`/`header` остаются plain JSON.
+
+## Сознательные расхождения с Java/Go
+
+- **`SearchAttributes` и `header` никогда не контекстуализируются** — как в Java/Go, это plain JSON. `EncodedCollection` (общий контейнер для memo/SA/header) несёт context-плумбинг, но он **инертен пока контекст явно не задан**; для SA/header его не задают.
+- **Workflow-runtime memo (start memo, `upsertMemo`, continue-as-new memo) НЕ контекстуализируется.** Эти memo кодирует RoadRunner (`rrtemporal`, Go), а не PHP, поэтому проставить контекст можно было бы только на decode-стороне — что создало бы asymmetry с записями из `upsertMemo` (закодированы без контекста). Контекстуализируется только **schedule action memo** (полностью PHP, write+read симметричны). Полный memo-паритет требует изменений в roadrunner-temporal.
+- **Нет пользовательского `PayloadCodec`** (шифрование/сжатие живёт в RoadRunner, не в PHP) и **нет подключаемого `FailureConverter`** (он `final`/static; контекст доходит до failure-details через `TemporalFailure::setSerializationContext` → self-binding `EncodedValues`). Оба — те же границы, что и у memo.
+- **nil-return** у `withSerializationContext` исключён типом `: static` (TypeError вместо Go-паники).
+
+## Известные паритет-гэпы (требуют отдельной работы)
+
+- **Child workflow без явного `workflowId`** — родитель кодирует аргументы child без контекста (id ещё не известен), а worker child'а декодирует с контекстом (реальный execution id) → asymmetry для context-aware converter'а. Java избегает этого, генерируя child workflowId на клиенте через `Workflow.randomUUID()` = `nameUUIDFromBytes(runId + ':' + counter)` — детерминированно, **без history-маркера**. PHP может сделать так же, но это требует **новой replay-safe инфраструктуры детерминированных id** (у PHP `uuid()` — это sideEffect/маркер) и меняет назначение id для ВСЕХ child workflow → отдельное изменение с replay-тестами, не в рамках этого ревью. Обход: задавать явный `withWorkflowId()` для child при использовании context-aware converter'а.
+- **Async activity completion** (`ActivityCompletionClient`) — PHP best-effort проставляет частичный контекст (by-id: namespace+workflowId; by-token: namespace), но не знает `activityType`/`taskQueue`, поэтому converter, завязанный на эти поля, не сойдётся с worker-side контекстом. Java по умолчанию контекст null и даёт `withContext(ActivitySerializationContext)` для явной передачи полного контекста. PHP-паритет — добавить `withContext` API (follow-up); текущее поведение корректно для namespace-keyed converter'ов.
+- **Start `UserMetadata` (summary/details) и built-in `__temporal_workflow_metadata` query** — Java контекстуализирует; PHP пока нет. Низкий приоритет (SDK-метаданные), и требует симметрии encode+decode, иначе повторяется memo-asymmetry.
+
+## Тесты
+
+- Unit: [`SerializationContextBinderTestCase`](../../tests/Unit/DataConverter/SerializationContextBinderTestCase.php), [`DataConverterSerializationContextTestCase`](../../tests/Unit/DataConverter/DataConverterSerializationContextTestCase.php), [`EncodedValuesSerializationContextTestCase`](../../tests/Unit/DataConverter/EncodedValuesSerializationContextTestCase.php), [`EncodedCollectionSerializationContextTestCase`](../../tests/Unit/DataConverter/EncodedCollectionSerializationContextTestCase.php), [`SerializationContextSigningTestCase`](../../tests/Unit/DataConverter/SerializationContextSigningTestCase.php) (mismatch-fails-decode = Go `SigningMismatchFailsDecode`).
+- Acceptance: [`SerializationContextTest`](../../tests/Acceptance/Extra/DataConverter/SerializationContextTest.php) — E2E подпись workflow/activity/child/side-effect/signal/query/update/continue-as-new/heartbeat/failure-details + schedule action input/memo.
diff --git a/docs/interceptors/exception-handling.md b/docs/interceptors/exception-handling.md
new file mode 100644
index 000000000..2dd7e02d6
--- /dev/null
+++ b/docs/interceptors/exception-handling.md
@@ -0,0 +1,96 @@
+# Exception Handling in Interceptors
+
+Начиная с версии 2.16.0, Temporal PHP SDK поддерживает перехват исключений через новые методы в интерфейсах интерцепторов.
+
+## Обзор
+
+Теперь вы можете наблюдать и обрабатывать исключения, возникающие во время выполнения workflow и activity, реализуя следующие методы:
+- `WorkflowInboundCallsInterceptor::handleWorkflowException()`
+- `ActivityInboundInterceptor::handleActivityException()`
+
+Эти методы вызываются **перед** тем, как исключение будет проброшено дальше, что позволяет вам:
+- Логировать исключения с полным контекстом
+- Отправлять данные в системы отслеживания ошибок (Sentry, Bugsnag и т.д.)
+- Собирать метрики
+- Отправлять уведомления
+
+## Базовое использование
+
+### Workflow Exception Interceptor
+
+```php
+use Temporal\Interceptor\WorkflowInboundCallsInterceptor;
+use Temporal\Interceptor\Trait\WorkflowInboundCallsInterceptorTrait;
+use Temporal\Interceptor\WorkflowInbound\WorkflowInput;
+use Temporal\Workflow;
+use Throwable;
+
+class LoggingWorkflowInterceptor implements WorkflowInboundCallsInterceptor
+{
+    use WorkflowInboundCallsInterceptorTrait;
+
+    public function handleWorkflowException(Throwable $exception, WorkflowInput $input): void
+    {
+        $info = Workflow::getInfo();
+        
+        error_log(sprintf(
+            '[Workflow Exception] %s в %s (ID: %s, RunID: %s): %s',
+            $exception::class,
+            $info->type->name,
+            $info->execution->getID(),
+            $info->execution->getRunID(),
+            $exception->getMessage()
+        ));
+    }
+}
+```
+
+### Activity Exception Interceptor
+
+```php
+use Temporal\Interceptor\ActivityInboundInterceptor;
+use Temporal\Interceptor\Trait\ActivityInboundInterceptorTrait;
+use Temporal\Interceptor\ActivityInbound\ActivityInput;
+use Temporal\Activity;
+use Throwable;
+
+class LoggingActivityInterceptor implements ActivityInboundInterceptor
+{
+    use ActivityInboundInterceptorTrait;
+
+    public function handleActivityException(Throwable $exception, ActivityInput $input): void
+    {
+        $info = Activity::getInfo();
+        
+        error_log(sprintf(
+            '[Activity Exception] %s в %s (ID: %s): %s',
+            $exception::class,
+            $info->type->name,
+            $info->id,
+            $exception->getMessage()
+        ));
+    }
+}
+```
+
+## Важные примечания
+
+1. **Не выбрасывайте исключения**: Методы `handleException` НЕ должны выбрасывать исключения. Оборачивайте всю логику в try-catch внутри метода.
+2. **Производительность**: Старайтесь делать обработку быстрой — она вызывается синхронно в потоке выполнения.
+3. **Оригинальное исключение всегда пробрасывается**: Ваш обработчик не предотвращает распространение исключения.
+4. **Множественные интерцепторы**: Если вы зарегистрируете несколько интерцепторов, все они будут вызваны по очереди.
+
+## Доступный контекст
+
+### Workflow Context (через `Workflow::getInfo()`)
+- `type->name` - имя класса Workflow
+- `execution->getID()` - Workflow ID
+- `execution->getRunID()` - Current Run ID
+- `taskQueue` - имя Task Queue
+- `attempt` - номер попытки выполнения
+
+### Activity Context (через `Activity::getInfo()`)
+- `type->name` - имя метода Activity
+- `id` - Activity ID
+- `workflowExecution->getID()` - ID родительского workflow
+- `attempt` - номер попытки выполнения
diff --git a/docs/nexus/README.md b/docs/nexus/README.md
new file mode 100644
index 000000000..c75d90d0d
--- /dev/null
+++ b/docs/nexus/README.md
@@ -0,0 +1,23 @@
+# Nexus в PHP SDK
+
+Документация по Nexus RPC — как канонической HTTP-спеке, так и её PHP-реализации в Temporal SDK.
+
+## Содержание
+
+| Документ | О чём |
+|---|---|
+| [Каноническая спека](spec.md) | Wire-протокол (Start/Cancel), Failure schema, OperationError vs HandlerError, headers, OperationState |
+| [Handler-side SDK](handler-side-sdk.md) | `#[Service]`, `#[Operation]`, `#[AsyncOperation]`, `Nexus::` accessors, `ServiceHandler`, `WorkflowHandle` |
+| [RR-интеграция](rr-integration.md) | Маршруты `InvokeNexusOperation`/`CancelNexusOperation`/`CancelNexusOperationMethod`, `_rr_nexus_*` reserved metadata, caller-side `ExecuteNexusOperation` |
+
+## Внешние источники
+
+- [nexus-rpc/api](https://github.com/nexus-rpc/api) — каноническая HTTP-спека.
+- [nexus-rpc/sdk-go](https://github.com/nexus-rpc/sdk-go) — reference SDK (Go).
+
+Handler-side SDK для PHP инлайнится прямо в этот репозиторий под `src/Nexus/` (`Temporal\Nexus\*`) — отдельного `nexus-rpc-sdk-php` репозитория больше нет.
+
+## Связанное
+
+- [Архитектура runtime'а](../runtime/architecture.md) — общий контекст PHP↔RR.
+- [Wire-протокол PHP↔RR](../runtime/worker-rr-protocol.md) — транспорт, на котором лежит Nexus-pipe.
diff --git a/docs/nexus/handler-side-sdk.md b/docs/nexus/handler-side-sdk.md
new file mode 100644
index 000000000..b69bf54ce
--- /dev/null
+++ b/docs/nexus/handler-side-sdk.md
@@ -0,0 +1,168 @@
+# Nexus handler-side SDK в PHP
+
+Как [спека Nexus](spec.md) выглядит в коде. Описывает как user-facing API под `Temporal\Nexus\`, так и внутренний дispatch под `Temporal\Internal\Nexus\`.
+
+## Декларация сервиса
+
+Service — это **класс с `#[Service]`** и методами, помеченными `#[Operation]` (sync) или `#[AsyncOperation]` (async):
+
+```php
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\WorkflowHandle;
+
+#[Service]
+final class MyService
+{
+    #[Operation]
+    public function greet(string $name): string
+    {
+        return "hello, {$name}";
+    }
+
+    #[AsyncOperation(output: 'string')]
+    public function longJob(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(MyWorkflow::class, $options, $input);
+    }
+}
+```
+
+Async-метод возвращает `WorkflowHandle` — SDK сам стартует backing-workflow и минтит
+operation token. Отмена автоматическая: SDK декодирует токен и отменяет backing-workflow
+(отдельный `#[OperationCancel]`-метод не нужен — атрибут удалён). Для полного ручного
+контроля метод может вернуть `OperationHandlerInterface` — тогда он сам несёт `start` + `cancel`.
+
+> Это текущая модель (после удаления `#[ServiceImpl]` / `#[OperationImpl]` /
+> `#[OperationCancel]` / `SynchronousOperationHandler`). Старые атрибуты и классы удалены.
+
+## Static-accessor `Nexus::`
+
+Внутри метода-обработчика контекст dispatch'а доступен через статический фасад [src/Nexus/Nexus.php](../../src/Nexus/Nexus.php):
+
+| Метод | Что возвращает |
+|---|---|
+| `Nexus::getCurrentContext()` | `NexusContext` — активное состояние dispatch'а |
+| `Nexus::getCurrentOperationContext()` | `OperationContext` (handler-side: links, headers, deadline) |
+| `Nexus::getStartDetails()` | `OperationStartDetails` (requestId, callback, links) — только для start-метода |
+| `Nexus::getCancelDetails()` | `OperationCancelDetails` (operationToken) — только для cancel-метода |
+| `Nexus::getOperationContext()` | `NexusOperationContext` (Temporal-side: namespace, taskQueue, workflowClient) |
+
+`getOperationContext()` пробрасывает `WorkflowClient`, который воркер отдаёт в
+`NexusTaskHandler` (см. [src/WorkerFactory.php](../../src/WorkerFactory.php)) — handler
+через него может стартовать workflow, signal'ить и т.д.
+
+## `OperationStartResult` — sealed union
+
+[src/Nexus/Handler/OperationStartResult.php](../../src/Nexus/Handler/OperationStartResult.php):
+
+```php
+abstract readonly class OperationStartResult
+{
+    protected function __construct() {}
+
+    public static function sync(mixed $value = null): SyncOperationStartResult { ... }
+    public static function async(OperationInfo $info): AsyncOperationStartResult { ... }
+}
+```
+
+Конструкторы наследников помечены `@internal` — конструировать только через фабрики `::sync()` / `::async()`. Это калька с Go-шной `HandlerStartOperationResult[Sync|Async]` пары, но PHP-идиоматично через abstract readonly + final readonly.
+
+Для метода с `#[AsyncOperation]` тип возврата — `WorkflowHandle` (а не `OperationStartResult`); SDK сам стартует backing-workflow через `WorkflowRunStarter` и обернёт результат в `AsyncOperationStartResult`.
+
+## `OperationContext` — почти immutable
+
+[src/Nexus/Handler/OperationContext.php](../../src/Nexus/Handler/OperationContext.php). Содержит `service`, `operation`, нормализованные headers (lowercased keys), `deadline?`, `serviceDefinition?`, `LinkCollection $links`, `MethodCanceller?`, `ClockInterface`.
+
+**Тонкости:**
+
+- `LinkCollection $links` — **shared mutable**. Это сделано специально: middleware могут добавлять links, и они должны оставаться видимыми после `withServiceDefinition()`-копирования контекста. Все остальные поля immutable.
+- Если `deadline` задан, но `methodCanceller` не передан — он создаётся автоматически из deadline'а. Когда deadline истечёт, `MethodCanceller` сработает и зарегистрированные listener'ы получат сигнал.
+- `isMethodCancelled()` — это RR-уровневая отмена (deadline, shutdown, остановка handler'а воркером), **не** Nexus-spec'овая отмена операции (вторая идёт через `cancelOperation` — автоматически для `WorkflowHandle`-операций либо через `cancel()` ручного `OperationHandlerInterface`).
+- `headers` нормализуются к lowercase keys в конструкторе.
+
+## `OperationStartDetails` / `OperationCancelDetails`
+
+[src/Nexus/Handler/OperationStartDetails.php](../../src/Nexus/Handler/OperationStartDetails.php):
+
+```php
+final readonly class OperationStartDetails
+{
+    public function __construct(
+        public string $requestId,                // обязательный, непустой
+        public ?string $callbackUrl = null,
+        public array $callbackHeaders = [],      // префикс Nexus-Callback- уже стрипнут транспортом
+        public array $links = [],                // Link[]
+    ) { /* validation */ }
+}
+```
+
+[src/Nexus/Handler/OperationCancelDetails.php](../../src/Nexus/Handler/OperationCancelDetails.php):
+
+```php
+final readonly class OperationCancelDetails
+{
+    public function __construct(public string $operationToken) {
+        OperationTokenValidator::assert($operationToken);
+    }
+}
+```
+
+Оба VO валидируют поля в конструкторе через [src/Nexus/Validation/](../../src/Nexus/Validation/) — `OperationTokenValidator`, `ServiceNameValidator`, `OperationNameValidator`, `PrintableAsciiValidator`. Все они кидают `Temporal\Nexus\Exception\InvalidArgumentException`.
+
+## Внутренний dispatch: `ServiceHandler`
+
+[src/Nexus/Handler/Internal/ServiceHandler.php](../../src/Nexus/Handler/Internal/ServiceHandler.php) — приватная middle-tier между транспортом и user-методом. Делает:
+
+1. Резолв `(service, operation) → NexusServiceInstance + OperationHandlerInterface` через таблицу инстансов. Если service неизвестен — `HandlerException(NotFound)` (`'Unrecognized service ...'`). Если операция неизвестна — `HandlerException(NotFound)`.
+2. Применяет middleware-цепочку (внешний middleware применяется к итоговому handler'у первым).
+3. Десериализует input через DataConverter; ошибка → `HandlerException(BadRequest)`.
+4. Зовёт user-метод.
+5. Для sync-результата сериализует output через DataConverter; ошибка → `HandlerException(Internal)`.
+6. **Sync-операции не отменяемы**: если `cancelOperation` пришёл на операцию, у которой `$definition->async === false`, бросает `HandlerException(NotImplemented)` с сообщением `'Operation %s/%s is synchronous and cannot be cancelled'`.
+
+## Failure converter
+
+[src/Nexus/Internal/Failure/NexusFailureConverter.php](../../src/Nexus/Internal/Failure/NexusFailureConverter.php) — единственное место, которое конвертирует PHP-исключения (`OperationException`, `HandlerException`) в proto-Failure объект для wire'а:
+
+- `operationExceptionToProto()` — для `424 Failed Dependency` (terminal failed/canceled);
+- `handlerExceptionToProto()` — для `4xx/5xx` (handler error c retry-семантикой).
+
+Транспортная glue (`NexusTaskHandler`) использует только эти два метода — JSON-формат failure'а нигде больше не собирается вручную.
+
+## Temporal-side контекст и `WorkflowClient`
+
+Temporal-side поля (`namespace`, `taskQueue`, `workflowClient`) приходят в
+`NexusTaskHandler` от воркера и складываются в [src/Internal/Nexus/NexusContext.php](../../src/Internal/Nexus/NexusContext.php);
+`Nexus::getOperationContext()` отдаёт их как `NexusOperationContext`. `WorkflowClient`
+создаётся в [src/WorkerFactory.php](../../src/WorkerFactory.php) и передаётся в
+`NexusTaskHandler` (см. [src/Nexus/Nexus.php](../../src/Nexus/Nexus.php) — `getWorkflowClient()`).
+Через него handler-методы запускают workflow'ы и делают cross-workflow операции. Без
+`WorkflowClient` `Nexus::getWorkflowClient()` бросит `\LogicException` — handler сможет
+работать только в рамках чистой Nexus-семантики (sync-операции без обращения к workflow API).
+
+## `MethodCanceller`
+
+[src/Nexus/Handler/MethodCanceller.php](../../src/Nexus/Handler/MethodCanceller.php). RR-уровневый cooperative interrupt:
+- может быть создан с `deadline` — тогда сам сработает по истечении;
+- срабатывает извне через `cancel($reason)`;
+- listener'ы (`MethodCancellationListenerInterface`) получают callback при срабатывании;
+- если listener регистрируется **после** срабатывания, он вызывается синхронно тут же (см. [OperationContext.php:84](../../src/Nexus/Handler/OperationContext.php:84)).
+
+Handler должен **поллить** `OperationContext::isMethodCancelled()` или регистрировать listener'ы. PHP не умеет асинхронно прерывать чужой stack frame — отмена кооперативная.
+
+## Тонкости
+
+- **Cancel sync-операции** — `NotImplemented`. Это отражает фундаментальное свойство sync-операций: они уже завершились к моменту, когда handler отвечает; отменять нечего.
+- **`callbackHeaders` приходят в handler без префикса `Nexus-Callback-`** — стрипает транспорт, не handler. Это спецификационное поведение.
+- **Разделение `OperationContext` / `NexusOperationContext`** — первый чисто handler-side (Nexus-spec поля), второй Temporal-side (namespace + taskQueue + workflow API). Не смешивать.
+- **`Link::$type` / `Link::$uri`** — обязательные поля; парсер `LinkParser` строгий, малформированные ссылки → `HandlerException(BadRequest)`, никаких silent-drop'ов.
+- **Validators throwing'ом контролируют граница** — service/operation names валидируются на каждом конструкторе, не где-то «в конце».
+- **`ServiceHandler` принимает middleware** в конструкторе как массив `OperationMiddlewareInterface[]`. Применяются reverse-order (последний в массиве — внутренний).
+
+## См. также
+
+- [Nexus spec](spec.md) — каноническая HTTP-спека.
+- [RR-интеграция](rr-integration.md) — что приходит от RR в `NexusTaskHandler` и обратно.
+- [Архитектура runtime'а](../runtime/architecture.md) — общий контекст PHP↔RR.
diff --git a/docs/nexus/rr-integration.md b/docs/nexus/rr-integration.md
new file mode 100644
index 000000000..fb41bfe1f
--- /dev/null
+++ b/docs/nexus/rr-integration.md
@@ -0,0 +1,165 @@
+# Интеграция Nexus с RoadRunner
+
+Что должен делать RR, чтобы Nexus заработал в Temporal-окружении PHP-воркера. Описывает обе стороны: handler-side (RR доставляет Nexus-задание PHP) и caller-side (workflow вызывает Nexus-операцию).
+
+## Двунаправленный контракт
+
+```
+Handler-side: RR ──▶ PHP — RR доставляет входящие Nexus-задания
+              PHP ──▶ RR — PHP возвращает start-result или cancel-confirm
+
+Caller-side:  PHP ──▶ RR — workflow декларирует Nexus-вызов
+              RR ──▶ PHP — RR возвращает started-сигнал и completion
+```
+
+## RR → PHP (handler-side)
+
+Воркер регистрирует Nexus-сервисы; RR доставляет ему задания и собирает ответы.
+
+### Маршрут `InvokeNexusOperation`
+
+[src/Internal/Transport/Router/InvokeNexusOperation.php](../../src/Internal/Transport/Router/InvokeNexusOperation.php).
+
+**Что RR должен прислать в `options`:**
+
+| Ключ | Тип | Что это |
+|---|---|---|
+| `service` | string | Nexus service name |
+| `operation` | string | Nexus operation name |
+| `requestId` | string | spec'овый Start-RequestId. Если пусто — PHP сгенерит fallback (для совместимости с не-Nexus HTTP-клиентами) |
+| `callback` | string\|null | URL для async-completion callback |
+| `callbackHeaders` | map<string,string> | Headers с уже стрипнутым префиксом `Nexus-Callback-` |
+| `headers` | map<string,string> | Request headers (включая `Operation-Timeout` / `Request-Timeout` — из них вычисляется deadline) |
+| `links` | array | `Nexus-Link` из start-запроса (uri+type) |
+| `invocationId` | uint64 | RR-internal ID для cooperative interrupt; 0 = back-compat fallback |
+
+Плюс `payload` с input'ом операции в формате Temporal `Payload`.
+
+**Что воркер возвращает RR — типизированная reply-команда `NexusOperationStarted`:**
+
+Route — это thin adapter над каноническим
+[`NexusTaskHandler::handleStartOperation(Request)`](../../src/Internal/Nexus/NexusTaskHandler.php).
+Он строит `Temporal\Api\Nexus\V1\Request` из JSON `options` + `payloads`, зовёт
+канонический хендлер, и переводит `Response.StartOperation.Variant` в типизированный
+reply [`NexusOperationStarted`](../../src/Worker/Transport/Command/Client/NexusOperationStarted.php).
+Encoder сериализует его как `Message.command = "NexusOperationStarted"` + JSON `options` +
+опциональный `payloads`.
+
+| Исход | `Message.command` | `options` JSON | `payloads` | `failure` |
+|---|---|---|---|---|
+| Sync success | `NexusOperationStarted` | `{async: false, links?}` | `[result_payload]` | — |
+| Async success | `NexusOperationStarted` | `{async: true, token, links?}` | — | — |
+| `OperationException` (Failed/Canceled) | — | — | — | `failurepb.Failure` с `ApplicationFailureInfo.Type = "nexus.OperationError.{failed\|canceled}"` (через `FailureConverter::mapExceptionToFailure`, ветка `NexusOperationException`); recursive `cause` сохраняется |
+| `HandlerException` / generic `\Throwable` | — | — | — | `failurepb.Failure` с `NexusHandlerFailureInfo` (через `FailureConverter::mapExceptionToFailure`, ветка `NexusHandlerException`) |
+
+Никаких payload-metadata маркеров (`_rr_nexus_kind`, `_rr_nexus_links` и пр.) — control-plane (sync/async, links) живёт в `options`, payload data — это чистый результат. Go-сторона декодирует `Message.command = "NexusOperationStarted"` в `internal.NexusOperationStarted{Async, Token, Links}` DTO.
+
+#### Контракт preservation cause-chain (handler → caller)
+
+`roadrunner-temporal/aggregatedpool/nexus.go::nexusErrorFromFailure` оборачивает PHP-присланный `failurepb.Failure` через `temporal.GetDefaultFailureConverter().FailureToError(f)`. Полученный go-error реализует `failureHolder` и держит исходный proto verbatim — поэтому SDK-Go `ErrorToFailure(...)` short-circuit'ит к нему обратно (`sdk-go/internal/failure_converter.go:71-75`), и **рекурсивная cause-цепочка с типами и `ApplicationFailureInfo.Details` (Payloads) восстанавливается на server-side без потерь**. Аналог тому, что уже делал activity-путь в `aggregatedpool/activity.go::Activity.execute` (`temporal.GetDefaultFailureConverter().FailureToError(retPld.Failure)`).
+
+Для `OperationException` плагин также выставляет `Message: f.GetMessage()` на `*nexus.OperationError` — иначе SDK-Go упаковывал бы внешний wrap с пустым message'ом (`sdk-go/internal/internal_nexus_task_handler.go:259`).
+
+Caller-side цепочка (подтверждено дампом workflow history):
+
+```
+NexusOperationFailure                                               ← server-injected wrapper
+ └── ApplicationFailure(type='nexus.OperationError.{failed|canceled}', message, …)  ← оригинал из PHP
+      └── … (рекурсивный cause из user-кода, если есть)
+```
+
+SDK-Go в `internal_nexus_task_handler.go:258-265` строит промежуточный `ApplicationError(type='OperationError', …)` wrap при упаковке ответа, но **сервер срезает этот уровень** при формировании `NexusOperationFailedEvent.failure.cause` — caller workflow видит оригинальный PHP-`ApplicationFailure` напрямую как `$e->getPrevious()`. Каноничный паттерн `AppFailureCallerWorkflow::run` в `tests/Acceptance/Extra/Nexus/SyncFailure/SyncFailureTest.php`.
+
+### Маршрут `CancelNexusOperation`
+
+[src/Internal/Transport/Router/CancelNexusOperation.php](../../src/Internal/Transport/Router/CancelNexusOperation.php).
+
+**Options:** `{service, operation, operationToken}`. Response: пустой Payload.
+
+Это spec'овый cancel-by-token. RR получил `POST /{service}/{operation}/cancel?token=...` от внешнего caller'а и пробросил его в PHP. PHP резолвит cancel-рутину операции — автоматически для `WorkflowHandle`-операций (SDK декодирует токен и отменяет backing-workflow) либо через `cancel()` ручного `OperationHandlerInterface`.
+
+**Sync-операции не отменяемы**: `ServiceHandler` бросит `HandlerException(NotImplemented)` если операция помечена `#[Operation]`, а не `#[AsyncOperation]`. Сообщение: `'Operation %s/%s is synchronous and cannot be cancelled'`.
+
+### Маршрут `CancelNexusOperationMethod`
+
+[src/Internal/Transport/Router/CancelNexusOperationMethod.php](../../src/Internal/Transport/Router/CancelNexusOperationMethod.php).
+
+**Options:** `{invocationId: uint64, reason: string}`. Late cancel (handler уже завершился) = no-op.
+
+Это **не Nexus-cancel**. Это RR-уровневый «прерви этот PHP-вызов» — для deadline'ов / shutdown'ов / транспортных отмен. Воркер устанавливает флаг в `OperationContext::isMethodCancelled()`. Handler должен поллить или регистрировать listener.
+
+**Зачем две разные cancel-точки:**
+- Nexus-cancel идёт по `(service, operation, token)` и работает на уровне operation state machine. Идемпотентен.
+- Method-cancel идёт по RR-internal `invocationId` и работает на уровне PHP-call cooperative interrupt'а. Без него нельзя реализовать deadline'ы или сложно остановить worker во время handler'а.
+
+### Расширение `GetWorkerInfo`
+
+[src/Internal/Transport/Router/GetWorkerInfo.php:80](../../src/Internal/Transport/Router/GetWorkerInfo.php:80) — воркер сверх обычной анкеты отдаёт массив:
+
+```php
+'NexusServices' => [
+    ['name' => 'my.service.v1', 'operations' => ['greet', 'longJob', ...]],
+    ...
+]
+```
+
+Без этого RR не знает, какие service'ы и операции воркер реально хостит, и не сможет зарегистрировать их в Temporal-сервере во время handshake'а.
+
+## PHP → RR (caller-side)
+
+Workflow внутри своего метода может позвать Nexus-операцию — и тогда контракт работает в обратную сторону.
+
+### Запрос `ExecuteNexusOperation`
+
+[src/Internal/Transport/Request/ExecuteNexusOperation.php](../../src/Internal/Transport/Request/ExecuteNexusOperation.php).
+
+**Поля:** `endpoint, service, operation, options, nexusHeaders` + args (input).
+
+> ⚠️ **Тонкость**: пустой `nexusHeaders` форсится в `\stdClass()` — не PHP-array. Иначе JSON-encode даст `[]`, а Go-сторона декодит как `map[string]string` и упадёт.
+
+RR не делает gRPC к Nexus endpoint'у напрямую. RR трансферит этот вызов в Temporal Go SDK API (`workflow.NewNexusClient(endpoint, service).ExecuteOperation(...)`), а тот формирует команду `ScheduleNexusOperationCommand` в текущем `WorkflowTaskCompletedRequest`. **Сетевую часть делает Temporal-сервер** через свой Nexus-gateway.
+
+### Запрос `GetNexusOperationStarted`
+
+[src/Internal/Transport/Request/GetNexusOperationStarted.php](../../src/Internal/Transport/Request/GetNexusOperationStarted.php).
+
+**Поля:** `{id: <ID исходного ExecuteNexusOperation>}`.
+
+Long-poll за start-envelope: RR держит запрос как listener, при срабатывании started-callback'а отдаёт PHP один Payload с JSON `NexusStartEnvelope = {async: bool, token?: string}`.
+
+**Зачем отдельный listener:** Nexus-Start может вернуть токен **до** completion'а (handler ack'нул start, но операция ещё работает). Workflow может захотеть отменить async-операцию между started и completion — для этого ему нужен started-факт. Полный аналог [src/Internal/Transport/Request/GetChildWorkflowExecution.php](../../src/Internal/Transport/Request/GetChildWorkflowExecution.php) для child workflow.
+
+### Completion — обычный future
+
+Когда операция действительно завершилась (sync сразу или async через callback), RR резолвит то самое `ExecuteNexusOperation`-future стандартным путём — `SuccessResponse` с тем же id, что и оригинальный запрос. Никакой отдельной «verbь-команды» для completion'а нет.
+
+## Чек-лист для RR-side имплементации
+
+| Что RR обязан делать | Зачем | Что ломается без этого |
+|---|---|---|
+| Парсить `NexusServices` из `GetWorkerInfo` | Регистрация на Temporal-сервере | Сервер не знает, что воркер хостит Nexus |
+| Эмитить `InvokeNexusOperation` task с полными options + payload | Spec-compliant Start | Handler не получит requestId/callback/headers/links |
+| Декодить `Message.command = "NexusOperationStarted"` reply с JSON `options` `{async, token?, links?}` | Различить sync vs async и пробросить handler-emitted links | Sync vs async не различимы; links теряются |
+| Эмитить `CancelNexusOperation` task по `(service, operation, token)` | Spec-овый cancel | Caller'ы не смогут отменять async-операции |
+| Эмитить `CancelNexusOperationMethod` с `invocationId` | Cooperative deadline/shutdown | Handler нельзя прерывать локально, deadline'ы не работают |
+| Принимать `ExecuteNexusOperation` команду от PHP в WorkflowTaskCompleted | Caller-side workflow → Nexus | Workflow не сможет звать Nexus |
+| Резолвить `GetNexusOperationStarted` listener при started-callback | Workflow видит started до completion | Отмена async-операций из workflow невозможна до завершения |
+| Резолвить `ExecuteNexusOperation` future при completion | Стандартный completion-path | Future never resolves |
+| Эмитить ненулевой `invocationId` | Связь method-cancel'а с in-flight handler'ом | Method-cancel — no-op (back-compat ветка) |
+
+## Тонкости и ловушки
+
+- **`invocationId = 0` — back-compat ветка.** Pre-Nexus RR-плагины не присылали это поле. PHP трактует 0 как «cooperative cancel недоступен», просто не регистрирует canceller. Современные RR-builds всегда присылают ненулевой `invocationId`.
+- **Cancel sync-операции — `NotImplemented`.** Это не баг, это spec-совместимое поведение. Sync операция уже завершилась к моменту, когда handler ответил.
+- **Никаких payload-metadata маркеров.** Прежняя схема со sync/async и links через `_rr_nexus_*` ключи в payload metadata удалена. Control-plane живёт в типизированном `NexusOperationStarted` reply (`options` JSON), payload data — чистый результат.
+- **`callbackHeaders` уже без префикса `Nexus-Callback-`.** Стрипает RR (per spec), не PHP.
+- **`OperationStartDetails::$requestId` обязателен и непустой.** Если RR не прислал его — PHP сгенерит fallback (`bin2hex(random_bytes(8))`). В нормальном Nexus-трафике он всегда есть; fallback — для странных HTTP-клиентов.
+- **Deadline вычисляется из header'ов, не из RR-options.** `OperationTimeout` / `RequestTimeout` парсятся в [NexusTaskHandler::deadlineFromHeaders()](../../src/Internal/Nexus/NexusTaskHandler.php) — case-insensitive, malformed → `null`.
+- **`nexusHeaders` ≠ `header`** в `ExecuteNexusOperation`. Первое — raw-string Nexus headers, для wire'а; второе — Temporal interceptor-header с типизированными payload-значениями. Их нельзя смешивать.
+- **Один canonical handler-путь.** `NexusTaskHandler` экспонирует только `handleStartOperation(Request): Response` и `handleCancelOperation(Request): Response` — те же сигнатуры, что у sibling SDK (sdk-go, sdk-java, sdk-typescript). Прежний `*Direct` bridge удалён.
+
+## См. также
+
+- [Nexus spec](spec.md) — что именно RR должен соблюдать на wire-уровне.
+- [PHP handler-side SDK](handler-side-sdk.md) — как user-метод связан с маршрутами.
+- [Wire-протокол PHP↔RR](../runtime/worker-rr-protocol.md) — общий транспорт.
diff --git a/docs/nexus/spec.md b/docs/nexus/spec.md
new file mode 100644
index 000000000..6d91f4ea1
--- /dev/null
+++ b/docs/nexus/spec.md
@@ -0,0 +1,168 @@
+# Nexus RPC: каноническая спецификация
+
+Краткая выжимка из [nexus-rpc/api/SPEC.md](https://github.com/nexus-rpc/api/blob/main/SPEC.md) — того, что важно держать в голове при работе с PHP-handler-side SDK и RR-интеграцией.
+
+## Что такое Nexus
+
+Тонкий слой поверх HTTP для system-to-system RPC. Долгие операции моделируются поверх синхронных HTTP-вызовов через дискриминированный union «sync result vs async token».
+
+**Caller** зовёт **handler**. Handler отвечает либо результатом сразу (синхронный режим), либо токеном для продолжения (асинхронный режим). Caller не определяет режим заранее; он просто передаёт callback URL, и handler уведомит, когда завершит асинхронную операцию.
+
+## Адресация операции
+
+```
+endpoint URL  +  service name  +  operation name  +  operation token
+```
+
+- `service` / `operation` — непустые строки, любые валидные URL-encoded символы.
+- `operation token` — не пустой, только printable ASCII (валидные значения HTTP-заголовка). Его выдаёт handler в ответ на StartOperation.
+
+## Только два эндпоинта
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| `POST` | `/{service}/{operation}` | StartOperation |
+| `POST` | `/{service}/{operation}/cancel` | CancelOperation |
+
+Никаких отдельных «get token», «poll status», «fetch result» в спеке нет (есть deprecated GetResult/GetInfo, но в современной модели они избыточны: результат прилетает на callback).
+
+## StartOperation — sealed union по статусу ответа
+
+| Status | Что значит | Body |
+|---|---|---|
+| `200 OK` + `Nexus-Operation-State: succeeded` | Sync success | Сериализованный результат |
+| `201 Created` | Started, async | JSON `OperationInfo {token, state}` |
+| `424 Failed Dependency` | Operation failed/canceled (terminal) | JSON `Failure` (`metadata.type=nexus.OperationError`, `details.state=failed\|canceled`) |
+| `4xx` / `5xx` | Handler error | JSON `Failure` (`metadata.type=nexus.HandlerError`, `details.type=BAD_REQUEST\|...`) |
+
+**Один ответ. Sync XOR async.** Не бывает «сначала токен, потом результат отдельным StartOperation-вызовом».
+
+## CancelOperation
+
+`POST /{service}/{operation}/cancel`. Токен передаётся либо через query-param `?token=...`, либо через заголовок `Nexus-Operation-Token`. Ответ: `202 Accepted`, body пустой.
+
+**Cancel идемпотентен.** Повтор по уже терминальной операции должен возвращать успех. `HandlerError` бросается только на routing/permission/transport ошибки, **не** на «уже отменено» / «уже завершено».
+
+## OperationState (wire-values, lowercase)
+
+```
+running | succeeded | failed | canceled
+```
+
+В PHP — [src/Nexus/OperationState.php](../../src/Nexus/OperationState.php). Эти строки — часть протокола; менять их = ломать совместимость.
+
+## Failure schema (рекурсивная)
+
+```yaml
+type: object
+properties:
+  message: string
+  stackTrace: string?
+  metadata: map<string, string>?
+  details: any?            # JSON-сериализуемые structured details
+  cause: $ref              # вложенный Failure
+```
+
+Две предопределённые формы (различаются по `metadata.type`):
+
+### `OperationError`
+```json
+{
+  "metadata": {"type": "nexus.OperationError"},
+  "message": "...",
+  "details": {"state": "canceled" | "failed"}
+}
+```
+Терминальный outcome операции.
+
+### `HandlerError`
+```json
+{
+  "metadata": {"type": "nexus.HandlerError"},
+  "message": "...",
+  "details": {"type": "BAD_REQUEST | ...", "retryableOverride": false}
+}
+```
+Ошибка обработки запроса. У каждого `type` есть default retry-семантика, переопределяемая через `retryableOverride`.
+
+## Predefined HandlerError types
+
+| Имя | HTTP | Retry default |
+|---|---|---|
+| `BAD_REQUEST` | 400 | no |
+| `UNAUTHENTICATED` | 401 | no |
+| `UNAUTHORIZED` | 403 | no |
+| `NOT_FOUND` | 404 | no |
+| `REQUEST_TIMEOUT` | 408 | yes |
+| `CONFLICT` | 409 | no |
+| `RESOURCE_EXHAUSTED` | 429 | yes |
+| `INTERNAL` | 500 | yes |
+| `NOT_IMPLEMENTED` | 501 | no |
+| `UNAVAILABLE` | 503 | yes |
+| `UPSTREAM_TIMEOUT` | 520 | yes |
+
+Маппинг туда-обратно — [src/Nexus/Exception/ErrorType.php](../../src/Nexus/Exception/ErrorType.php) (`httpStatus()` / `fromHttpStatus()`).
+
+## Канонические заголовки
+
+| Заголовок | На каком этапе | Назначение |
+|---|---|---|
+| `Nexus-Callback-*` | Start request | Префикс стрипается транспортом, остальное прикладывается к callback POST |
+| `Nexus-Link: <url>; type="..."` | Start request, response, callback | Ассоциация с ресурсами (двусторонняя) |
+| `Operation-Timeout: <num>(ms\|s\|m)` | Start request | Сколько caller готов ждать |
+| `Request-Timeout` | Любой запрос | HTTP-уровневый таймаут |
+| `Nexus-Operation-Token` | Cancel request, callback POST | Token-by-header alternative |
+| `Nexus-Operation-State` | Sync success response, callback POST | Терминальный/промежуточный state |
+| `Nexus-Operation-Start-Time` | Callback POST | RFC 5322 timestamp начала |
+| `Nexus-Operation-Close-Time` | Callback POST | RFC 3339 timestamp завершения |
+
+## Callback POST (для async-операций)
+
+Когда async-операция завершилась, handler делает `POST <callback-url>` с:
+- `Nexus-Operation-Token`, `Nexus-Operation-Start-Time`, `Nexus-Operation-Close-Time`, `Nexus-Operation-State`
+- любыми `Nexus-Callback-*` headers, переданными при Start (без префикса);
+- любыми `Nexus-Link` headers;
+- body: либо результат + `Content-*` headers, либо JSON `Failure` с `Content-Type: application/json`.
+
+Caller отвечает `200 OK` с пустым body на успешный приём.
+
+## Content types
+
+Не опинионирован. Типичные:
+- `application/json` — для JSON;
+- `application/octet-stream` — для byte-buffer'ов;
+- пустой — для `null` payload'а;
+- `application/x-protobuf; message-type=com.example.MyMessage` — binary proto;
+- `application/json; format=protobuf; message-type=...` — JSON-сериализованный proto.
+
+## Reference SDK shape (Go)
+
+[`sdk-go/nexus/handler.go`](../../../../go/pkg/mod/github.com/nexus-rpc/sdk-go@v0.6.0/nexus/handler.go) даёт каноническую модель handler'а:
+
+```go
+type Handler interface {
+    StartOperation(ctx, service, operation string, *LazyValue, StartOperationOptions)
+        (HandlerStartOperationResult[any], error)
+    CancelOperation(ctx, service, operation, token string, CancelOperationOptions) error
+}
+
+// Sealed union:
+type HandlerStartOperationResult[T any] interface { /* sealed */ }
+type HandlerStartOperationResultSync[T any] struct { Value T }
+type HandlerStartOperationResultAsync struct { OperationToken string }
+```
+
+PHP-шейп [src/Nexus/Handler/](../../src/Nexus/Handler/) повторяет эту модель идиоматично через abstract-readonly-class + final-readonly-наследников; см. [handler-side-sdk.md](handler-side-sdk.md).
+
+## Что важно держать в голове
+
+1. Wire-значения (state-string, error-type-string, имена заголовков) — это **протокол**, не деталь реализации.
+2. Start — один ответ, sync ИЛИ async. Если на стороне сервера тебе хочется «вернуть и token, и result» — это бага в спеке твоего сервиса.
+3. Cancel идемпотентен. «Уже отменено» — успех, не ошибка.
+4. Async-результат доставляется на callback URL. **Получение результата по токену — это уже Temporal-уровень**, не Nexus spec. На PHP-handler-side `WorkflowRunOperation` решает это поверх Nexus-async модели.
+5. `OperationError` ≠ `HandlerError`. Первое — терминальное состояние операции; второе — ошибка обработки запроса с retry-семантикой.
+
+## См. также
+
+- [PHP handler-side SDK](handler-side-sdk.md) — как Nexus-API выглядит в PHP-коде.
+- [RR-интеграция](rr-integration.md) — что нужно от RR, чтобы Nexus заработал в Temporal-окружении.
diff --git a/docs/plugins.md b/docs/plugins.md
new file mode 100644
index 000000000..fb2432919
--- /dev/null
+++ b/docs/plugins.md
@@ -0,0 +1,496 @@
+# Плагины (Plugins)
+
+Плагины — это механизм расширения Temporal PHP SDK, позволяющий модифицировать поведение клиентов, воркеров и соединений без изменения прикладного кода. В отличие от интерцепторов, которые работают на уровне отдельных вызовов, плагины конфигурируют инфраструктуру SDK целиком: подключение, сериализацию, опции воркеров, пайплайн интерцепторов и жизненный цикл фабрики.
+
+## Обзор
+
+Система плагинов предоставляет 4 уровня интеграции:
+
+| Уровень | Интерфейс | Что настраивает |
+|---------|-----------|-----------------|
+| Соединение | `ConnectionPluginInterface` | gRPC-клиент (API-ключи, метаданные, TLS) |
+| Клиент | `ClientPluginInterface` | `WorkflowClient` (namespace, конвертеры, интерцепторы) |
+| Schedule-клиент | `ScheduleClientPluginInterface` | `ScheduleClient` (namespace, конвертеры) |
+| Воркер | `WorkerPluginInterface` | `WorkerFactory` и воркеры (опции, интерцепторы, жизненный цикл) |
+
+Плагин может реализовывать один или несколько интерфейсов. Один плагин, реализующий `ClientPluginInterface` и `WorkerPluginInterface`, автоматически пропагируется из клиента в фабрику воркеров.
+
+## Быстрый старт
+
+Минимальный плагин, добавляющий интерцептор к `WorkflowClient`:
+
+```php
+use Temporal\Plugin\ClientPluginInterface;
+use Temporal\Plugin\ClientPluginContext;
+use Temporal\Interceptor\WorkflowClientCallsInterceptor;
+use Temporal\Interceptor\Trait\WorkflowClientCallsInterceptorTrait;
+use Temporal\Interceptor\WorkflowClient\StartInput;
+use Temporal\Workflow\WorkflowExecution;
+
+class LoggingPlugin implements ClientPluginInterface
+{
+    public function getName(): string
+    {
+        return 'my-app.logging';
+    }
+
+    public function configureClient(ClientPluginContext $context): void
+    {
+        $context->addInterceptor(new LoggingInterceptor());
+    }
+}
+
+class LoggingInterceptor implements WorkflowClientCallsInterceptor
+{
+    use WorkflowClientCallsInterceptorTrait;
+
+    public function start(StartInput $input, callable $next): WorkflowExecution
+    {
+        echo "Starting workflow: {$input->workflowType}\n";
+        return $next($input);
+    }
+}
+```
+
+Подключение:
+
+```php
+use Temporal\Client\WorkflowClient;
+use Temporal\Plugin\PluginRegistry;
+
+$client = WorkflowClient::create(
+    serviceClient: $serviceClient,
+    pluginRegistry: new PluginRegistry([new LoggingPlugin()]),
+);
+```
+
+## Интерфейсы плагинов
+
+### `PluginInterface`
+
+Базовый интерфейс. Единственное требование — уникальное имя для дедупликации.
+
+```php
+interface PluginInterface
+{
+    public function getName(): string;
+}
+```
+
+Рекомендуемая конвенция именования: обратная доменная нотация (`my-org.tracing`, `acme.cloud-auth`).
+
+### `ConnectionPluginInterface`
+
+Конфигурирует gRPC-соединение. Вызывается **первым**, до клиентских плагинов.
+
+```php
+interface ConnectionPluginInterface
+{
+    public function getName(): string;
+    public function configureServiceClient(ConnectionPluginContext $context): void;
+}
+```
+
+Пример — автоматическая установка API-ключа:
+
+```php
+class CloudAuthPlugin implements ConnectionPluginInterface
+{
+    public function __construct(
+        private readonly string $apiKey,
+    ) {}
+
+    public function getName(): string
+    {
+        return 'temporal.cloud-auth';
+    }
+
+    public function configureServiceClient(ConnectionPluginContext $context): void
+    {
+        $context->setServiceClient(
+            $context->getServiceClient()->withAuthKey($this->apiKey),
+        );
+    }
+}
+```
+
+### `ClientPluginInterface`
+
+Конфигурирует `WorkflowClient`: namespace, `DataConverter`, интерцепторы.
+
+```php
+interface ClientPluginInterface extends PluginInterface
+{
+    public function configureClient(ClientPluginContext $context): void;
+}
+```
+
+### `ScheduleClientPluginInterface`
+
+Конфигурирует `ScheduleClient`. Автоматически пропагируется из `WorkflowClient`, если плагин реализует оба интерфейса.
+
+```php
+interface ScheduleClientPluginInterface extends PluginInterface
+{
+    public function configureScheduleClient(ScheduleClientPluginContext $context): void;
+}
+```
+
+### `WorkerPluginInterface`
+
+Самый мощный интерфейс с 4 хуками:
+
+```php
+interface WorkerPluginInterface extends PluginInterface
+{
+    public function configureWorkerFactory(WorkerFactoryPluginContext $context): void;
+    public function configureWorker(WorkerPluginContext $context): void;
+    public function initializeWorker(WorkerInterface $worker): void;
+    public function run(WorkerFactoryInterface $factory, callable $next): int;
+}
+```
+
+| Метод | Когда вызывается | Что можно делать |
+|-------|------------------|------------------|
+| `configureWorkerFactory` | При создании `WorkerFactory` | Изменить `DataConverter` для всех воркеров |
+| `configureWorker` | При вызове `newWorker()`, до создания воркера | Изменить `WorkerOptions`, добавить интерцепторы |
+| `initializeWorker` | После создания воркера | Зарегистрировать Workflow/Activity |
+| `run` | При вызове `WorkerFactory::run()` | Обернуть жизненный цикл (ресурсы, мониторинг) |
+
+### `TemporalPluginInterface`
+
+Объединяет все 4 интерфейса. Удобен для плагинов, работающих на всех уровнях:
+
+```php
+interface TemporalPluginInterface extends
+    ConnectionPluginInterface,
+    ClientPluginInterface,
+    ScheduleClientPluginInterface,
+    WorkerPluginInterface
+{
+}
+```
+
+## AbstractPlugin
+
+Базовый класс с no-op реализациями всех методов. Рекомендуется для плагинов, которым нужно несколько хуков:
+
+```php
+use Temporal\Plugin\AbstractPlugin;
+use Temporal\Plugin\ClientPluginContext;
+use Temporal\Plugin\WorkerPluginContext;
+
+class MyPlugin extends AbstractPlugin
+{
+    public function __construct()
+    {
+        parent::__construct('my-org.my-plugin');
+    }
+
+    public function configureClient(ClientPluginContext $context): void
+    {
+        // Только нужные хуки, остальные — no-op
+    }
+
+    public function configureWorker(WorkerPluginContext $context): void
+    {
+        // ...
+    }
+}
+```
+
+## Трейты
+
+Для выборочной реализации отдельных интерфейсов используйте трейты с no-op методами:
+
+| Трейт | Для интерфейса | No-op методы |
+|-------|----------------|-------------|
+| `ConnectionPluginTrait` | `ConnectionPluginInterface` | `configureServiceClient()` |
+| `ClientPluginTrait` | `ClientPluginInterface` | `configureClient()` |
+| `ScheduleClientPluginTrait` | `ScheduleClientPluginInterface` | `configureScheduleClient()` |
+| `WorkerPluginTrait` | `WorkerPluginInterface` | `configureWorkerFactory()`, `configureWorker()`, `initializeWorker()`, `run()` |
+
+Пример — плагин только для клиента и воркера:
+
+```php
+use Temporal\Plugin\ClientPluginInterface;
+use Temporal\Plugin\ClientPluginTrait;
+use Temporal\Plugin\WorkerPluginInterface;
+use Temporal\Plugin\WorkerPluginTrait;
+
+class MyComboPlugin implements ClientPluginInterface, WorkerPluginInterface
+{
+    use ClientPluginTrait;  // no-op configureClient()
+    use WorkerPluginTrait;  // no-op для всех 4 методов
+
+    public function getName(): string
+    {
+        return 'my-combo';
+    }
+
+    // Переопределяем только нужные методы
+    public function configureClient(ClientPluginContext $context): void
+    {
+        $context->addInterceptor(new MyInterceptor());
+    }
+}
+```
+
+## Контексты
+
+Каждый хук получает контекст — mutable-объект с fluent API для модификации конфигурации.
+
+### `ConnectionPluginContext`
+
+```php
+$context->getServiceClient(): ServiceClientInterface;
+$context->setServiceClient(ServiceClientInterface $client): self;
+```
+
+### `ClientPluginContext`
+
+```php
+$context->getClientOptions(): ClientOptions;
+$context->setClientOptions(ClientOptions $options): self;
+
+$context->getDataConverter(): ?DataConverterInterface;
+$context->setDataConverter(?DataConverterInterface $converter): self;
+
+$context->getInterceptors(): array;
+$context->setInterceptors(array $interceptors): self;
+$context->addInterceptor(Interceptor $interceptor): self;
+```
+
+### `WorkerFactoryPluginContext`
+
+```php
+$context->getDataConverter(): ?DataConverterInterface;
+$context->setDataConverter(?DataConverterInterface $converter): self;
+```
+
+### `WorkerPluginContext`
+
+```php
+$context->getTaskQueue(): string;  // только чтение
+
+$context->getWorkerOptions(): WorkerOptions;
+$context->setWorkerOptions(WorkerOptions $options): self;
+
+$context->getExceptionInterceptor(): ?ExceptionInterceptorInterface;
+$context->setExceptionInterceptor(?ExceptionInterceptorInterface $interceptor): self;
+
+$context->getInterceptors(): array;
+$context->setInterceptors(array $interceptors): self;
+$context->addInterceptor(Interceptor $interceptor): self;
+```
+
+### `ScheduleClientPluginContext`
+
+```php
+$context->getClientOptions(): ClientOptions;
+$context->setClientOptions(ClientOptions $options): self;
+
+$context->getDataConverter(): ?DataConverterInterface;
+$context->setDataConverter(?DataConverterInterface $converter): self;
+```
+
+## Жизненный цикл
+
+Плагины вызываются в порядке регистрации. Полный жизненный цикл:
+
+```
+WorkflowClient::__construct()
+│
+├─ 1. ConnectionPluginInterface::configureServiceClient()
+│     Настройка gRPC-соединения (API-ключи, метаданные)
+│
+├─ 2. ClientPluginInterface::configureClient()
+│     Настройка клиента (namespace, конвертеры, интерцепторы)
+│
+WorkerFactory::__construct()
+│
+├─ 3. Merge: плагины из клиента ($client->getWorkerPlugins()) добавляются в фабрику
+│
+├─ 4. WorkerPluginInterface::configureWorkerFactory()
+│     Настройка фабрики (DataConverter для всех воркеров)
+│
+WorkerFactory::newWorker()  ← вызывается для каждого воркера
+│
+├─ 5. WorkerPluginInterface::configureWorker()
+│     Настройка воркера (WorkerOptions, интерцепторы)
+│
+├─ 6. Создание Worker
+│
+├─ 7. WorkerPluginInterface::initializeWorker()
+│     Пост-инициализация (регистрация Workflow/Activity)
+│
+WorkerFactory::run()
+│
+└─ 8. WorkerPluginInterface::run()
+      Chain-of-responsibility обёртка жизненного цикла
+```
+
+## Пропагация плагинов
+
+Плагины автоматически передаются между компонентами SDK:
+
+### Client → WorkerFactory
+
+Плагины, реализующие `WorkerPluginInterface`, автоматически пропагируются из `WorkflowClient` в `WorkerFactory`:
+
+```php
+$registry = new PluginRegistry([new MyFullPlugin()]);
+
+// Плагин регистрируется на клиенте
+$client = WorkflowClient::create($serviceClient, pluginRegistry: $registry);
+
+// Плагин автоматически пропагируется в фабрику
+$factory = WorkerFactory::create(client: $client);
+// MyFullPlugin::configureWorkerFactory() вызван автоматически
+```
+
+### Client → ScheduleClient
+
+Плагины, реализующие `ScheduleClientPluginInterface`, доступны через `$client->getScheduleClientPlugins()`.
+
+### Объединение плагинов из разных источников
+
+Фабрика может получать плагины из нескольких источников. Порядок: сначала плагины фабрики, затем — плагины из клиента:
+
+```php
+$client = WorkflowClient::create($serviceClient, pluginRegistry: new PluginRegistry([$clientPlugin]));
+
+$factory = WorkerFactory::create(
+    pluginRegistry: new PluginRegistry([$factoryPlugin]),
+    client: $client,
+);
+// Порядок: $factoryPlugin → $clientPlugin
+```
+
+Дубликаты имён приводят к исключению `RuntimeException`.
+
+## PluginRegistry
+
+`PluginRegistry` управляет коллекцией плагинов с дедупликацией по имени.
+
+```php
+use Temporal\Plugin\PluginRegistry;
+
+// Создание с начальным набором
+$registry = new PluginRegistry([$plugin1, $plugin2]);
+
+// Добавление одного плагина
+$registry->add($plugin3);
+
+// Слияние нескольких плагинов
+$registry->merge([$plugin4, $plugin5]);
+
+// Получение плагинов по интерфейсу
+$clientPlugins = $registry->getPlugins(ClientPluginInterface::class);
+$workerPlugins = $registry->getPlugins(WorkerPluginInterface::class);
+```
+
+Дубликаты:
+
+```php
+$registry = new PluginRegistry([new MyPlugin(), new MyPlugin()]);
+// RuntimeException: Duplicate plugin "my-plugin": a plugin with this name is already registered.
+```
+
+## Run hook
+
+Метод `run()` в `WorkerPluginInterface` использует паттерн chain-of-responsibility. Первый зарегистрированный плагин является внешней обёрткой.
+
+### Управление ресурсами (try/finally)
+
+```php
+public function run(WorkerFactoryInterface $factory, callable $next): int
+{
+    $connection = ConnectionPool::create();
+    try {
+        return $next($factory); // вызов следующего плагина или основного цикла
+    } finally {
+        $connection->close(); // гарантированная очистка
+    }
+}
+```
+
+### Порядок вызова
+
+При двух плагинах (A, B зарегистрированы в этом порядке):
+
+```
+A::run() before
+  B::run() before
+    --- основной цикл ---
+  B::run() after (finally)
+A::run() after (finally)
+```
+
+### Прерывание цепочки
+
+Плагин может не вызывать `$next()`, прерывая выполнение:
+
+```php
+public function run(WorkerFactoryInterface $factory, callable $next): int
+{
+    if (!$this->isReady()) {
+        return 1; // Прервать без запуска основного цикла
+    }
+
+    return $next($factory);
+}
+```
+
+## Полный пример
+
+Плагин для аутентификации через Temporal Cloud — настраивает API-ключ на уровне соединения и namespace на уровне клиента:
+
+```php
+use Temporal\Plugin\AbstractPlugin;
+use Temporal\Plugin\ConnectionPluginContext;
+use Temporal\Plugin\ClientPluginContext;
+use Temporal\Client\ClientOptions;
+
+class TemporalCloudPlugin extends AbstractPlugin
+{
+    public function __construct(
+        private readonly string $apiKey,
+        private readonly string $namespace,
+    ) {
+        parent::__construct('temporal.cloud');
+    }
+
+    public function configureServiceClient(ConnectionPluginContext $context): void
+    {
+        $context->setServiceClient(
+            $context->getServiceClient()->withAuthKey($this->apiKey),
+        );
+    }
+
+    public function configureClient(ClientPluginContext $context): void
+    {
+        $context->setClientOptions(
+            (new ClientOptions())->withNamespace($this->namespace),
+        );
+    }
+}
+```
+
+Использование:
+
+```php
+use Temporal\Client\GRPC\ServiceClient;
+use Temporal\Client\WorkflowClient;
+use Temporal\Plugin\PluginRegistry;
+
+$plugin = new TemporalCloudPlugin(
+    apiKey: 'my-api-key',
+    namespace: 'my-namespace.a1b2c',
+);
+
+$client = WorkflowClient::create(
+    serviceClient: ServiceClient::createSSL('my-namespace.a1b2c.tmprl.cloud:7233'),
+    pluginRegistry: new PluginRegistry([$plugin]),
+);
+```
diff --git a/docs/runtime/README.md b/docs/runtime/README.md
new file mode 100644
index 000000000..309d428c0
--- /dev/null
+++ b/docs/runtime/README.md
@@ -0,0 +1,18 @@
+# Runtime PHP-воркера
+
+Документы про то, как PHP SDK исполняет workflows — от facade `Workflow::timer()` до gRPC-вызова `RespondWorkflowTaskCompleted` к Temporal-серверу.
+
+## Содержание
+
+| Документ | О чём |
+|---|---|
+| [Архитектура](architecture.md) | Три процесса (Temporal — RR — PHP), зачем нужен RR, где gRPC-клиент в PHP всё-таки используется |
+| [Wire-протокол PHP↔RR](worker-rr-protocol.md) | Shared queue, codec (proto/json), TickInfo, request ID, главный цикл `dispatch()` |
+| [Workflow и корутины](workflow-coroutines.md) | `Scope::next()` как движок генератора, event-loop без ReactPHP, replay-семантика |
+| [Fiber mode](fibers.md) | `@experimental` режим без `yield`/`\Generator`: `\Fiber`-мост поверх Generator-протокола, public API map, gotchas |
+
+## Связанное
+
+- [Nexus subsystem](../nexus/) — отдельная подсистема со своим RR-контрактом.
+- [Plugins](../plugins.md) — расширение SDK.
+- [Interceptors](../interceptors/) — middleware для client/worker calls.
diff --git a/docs/runtime/architecture.md b/docs/runtime/architecture.md
new file mode 100644
index 000000000..0baac2e11
--- /dev/null
+++ b/docs/runtime/architecture.md
@@ -0,0 +1,65 @@
+# Архитектура runtime'а PHP-воркера
+
+Высокоуровневое описание того, как PHP SDK исполняет workflows и activities, и почему между PHP-кодом и Temporal-сервером существует процесс RoadRunner.
+
+## Три процесса, две границы
+
+```
+┌─────────────────┐         ┌─────────────────────┐         ┌──────────────────┐
+│  Temporal       │ ◀─gRPC─▶│  RoadRunner         │ ◀─pipe─▶│  PHP worker      │
+│  server         │  (TCP)  │  + rrtemporal (Go)  │ goridge │  (short-lived)   │
+└─────────────────┘         └─────────────────────┘         └──────────────────┘
+```
+
+- **Temporal-сервер** говорит на gRPC. Держит history workflows, очереди тасков, таймеры.
+- **RoadRunner** — Go-процесс с плагином `rrtemporal`. Держит **persistent gRPC** к Temporal, делает long-poll на task-queue'и (`PollWorkflowTaskQueue`, `PollActivityTaskQueue`, `PollNexusTaskQueue`). Внутри использует Temporal Go SDK.
+- **PHP-воркер** — short-lived процесс, ничего сетевого не делает напрямую. Общается **только** с RR через локальный goridge-pipe (TCP/unix).
+
+Граница между PHP и RR — это [Spiral Goridge](https://github.com/spiral/goridge). Не gRPC. Передаются proto-Message'ы (или JSON, см. `RR_CODEC` env var) внутри goridge-payload'а.
+
+## Где gRPC-клиент в PHP всё-таки используется
+
+В SDK **есть** полноценный gRPC-клиент: [src/Client/GRPC/ServiceClient.php](../../src/Client/GRPC/ServiceClient.php). Но он применяется только **вне workflow execution**:
+
+| Use case | Использует ServiceClient? | Использует RR? |
+|---|---|---|
+| `WorkflowClient::start()`, `signal()`, `query()`, `describe()` | Да, напрямую | Нет |
+| `ScheduleClient`, `OperatorClient` | Да, напрямую | Нет |
+| Внутри workflow-метода (`Workflow::executeActivity()`, `Workflow::timer()`, …) | **Нет** | Да |
+| Worker poll-loop (получение task'ов от Temporal) | Нет | Да, RR делает poll |
+| Внутри Nexus-handler'а (`Nexus::getOperationContext()->getWorkflowClient()`) | Да, через client-side API | Нет |
+
+**Принципиальная причина:** workflow обязан быть детерминированным. Прямой сетевой вызов из workflow-метода (`gRPC.call()`) сломает replay — на повторе значение может прийти другое. Поэтому workflow-команды декларативны: workflow только **записывает** намерение в очередь, а сетевой вызов делает RR в правильный момент.
+
+## Что доставляется через RR
+
+| Направление | Что |
+|---|---|
+| RR → PHP | `StartWorkflow`, `InvokeActivity`, `InvokeQuery`, `InvokeSignal`, `InvokeUpdate`, `InvokeNexusOperation`, `CancelNexusOperation`, `CancelNexusOperationMethod`, `DestroyWorkflow`, `GetWorkerInfo`, … |
+| PHP → RR | `NewTimer`, `ExecuteActivity`, `ExecuteChildWorkflow`, `ExecuteNexusOperation`, `GetNexusOperationStarted`, `CompleteWorkflow`, `Panic`, `SideEffect`, `UpsertSearchAttributes`, … (всё в [src/Internal/Transport/Request/](../../src/Internal/Transport/Request/)) |
+
+Все эти сообщения — это **команды** в логическом смысле. Один pingpong PHP↔RR соответствует одному WorkflowTask на Temporal-стороне: PHP получает batch событий, выполняет workflow до следующей точки suspension, возвращает batch команд.
+
+## Главный цикл воркера
+
+[src/WorkerFactory.php:271](../../src/WorkerFactory.php:271):
+
+```php
+public function run(?HostConnectionInterface $host = null): int
+{
+    $host ??= RoadRunner::create();
+    // ...
+    while ($msg = $host->waitBatch()) {
+        $host->send($this->dispatch($msg->messages, $msg->context));
+    }
+    return 0;
+}
+```
+
+— блокирующий receive из goridge, обработка batch'а, send обратно. Цикл блокируется в `waitBatch()` пока RR не пришлёт следующее задание.
+
+## См. также
+
+- [Wire-протокол PHP↔RR](worker-rr-protocol.md) — внутренности `dispatch()`, codec, queue, request-ID.
+- [Workflow и корутины](workflow-coroutines.md) — как генератор обрабатывается, replay-семантика.
+- [Nexus subsystem](../nexus/) — отдельная подсистема со своим RR-контрактом.
diff --git a/docs/runtime/fibers.md b/docs/runtime/fibers.md
new file mode 100644
index 000000000..705d06f62
--- /dev/null
+++ b/docs/runtime/fibers.md
@@ -0,0 +1,377 @@
+# Fiber-mode workflow runtime
+
+How `\Temporal\Experiments\Fibers\Workflow` lets you write workflow bodies without `yield` / `\Generator`, while the underlying `Scope::next()` event loop keeps driving the same protocol.
+
+> **Status:** `@experimental`. Public API stability not promised. Generator mode ([workflow-coroutines.md](workflow-coroutines.md)) remains the primary path.
+
+## TL;DR
+
+Generator-mode workflow body:
+
+```php
+#[WorkflowMethod]
+public function run(): \Generator
+{
+    yield Workflow::timer(5);
+    $result = yield Workflow::executeActivity('echo', [$input]);
+    return $result;
+}
+```
+
+Same workflow in Fiber mode:
+
+```php
+use Temporal\Experiments\Fibers\Workflow;
+
+#[WorkflowMethod]
+public function run(): mixed
+{
+    Workflow::timer(5);
+    return Workflow::executeActivity('echo', [$input]);
+}
+```
+
+**Three-step migration:**
+1. `use Temporal\Workflow;` → `use Temporal\Experiments\Fibers\Workflow;`
+2. Delete every `yield` before a `Workflow::*` call.
+3. Drop `: \Generator` from workflow / signal / update / handler return types.
+
+Workflow attributes (`#[WorkflowInterface]`, `#[WorkflowMethod]`, `#[SignalMethod]`, `#[QueryMethod]`, `#[UpdateMethod]`) stay in the standard `Temporal\Workflow\…` namespace — they are not duplicated.
+
+## The bridge: every handler runs inside a Fiber
+
+The headline trick is in [src/Internal/Workflow/Process/Scope.php:480](../../src/Internal/Workflow/Process/Scope.php:480):
+
+```php
+private function createFiberHandler(callable $handler, ScopeContext $scopeContext): \Closure
+{
+    return static function (ValuesInterface $values) use ($handler, $scopeContext): mixed {
+        $fiber = new \Fiber(static function () use ($handler, $values, $scopeContext): mixed {
+            $scopeContext->setFiberMode(true);
+            Workflow::setCurrentContext($scopeContext);
+            return $handler($values);
+        });
+
+        try {
+            $suspendedValue = $fiber->start();
+        } catch (\Throwable $e) {
+            $scopeContext->setFiberMode(false);
+            throw $e;
+        }
+
+        if ($fiber->isTerminated()) {
+            $scopeContext->setFiberMode(false);
+            return $fiber->getReturn();
+        }
+
+        return (static function (\Fiber $fiber, mixed $suspendedValue, ScopeContext $scopeContext): \Generator {
+            $value = $suspendedValue;
+            try {
+                while (!$fiber->isTerminated()) {
+                    try {
+                        $sent = yield $value;
+                        $value = $fiber->resume($sent);
+                    } catch (\Throwable $e) {
+                        $value = $fiber->throw($e);
+                        if ($fiber->isTerminated()) {
+                            break;
+                        }
+                    }
+                }
+                return $fiber->getReturn();
+            } finally {
+                $scopeContext->setFiberMode(false);
+            }
+        })($fiber, $suspendedValue, $scopeContext);
+    };
+}
+```
+
+**Two branches matter.** The user-handler return type decides which path runs:
+
+| User wrote | `$handler($values)` returns | Bridge does |
+|---|---|---|
+| Fiber body (no `yield`, no `\Generator`) | the return value | Fiber suspends from inside `FiberHelper::await()`. Bridge wraps `$fiber` in a forwarding Generator and returns it. `Scope::next()` sees a Generator, treats it like every other coroutine. |
+| Generator body (has `yield`) | the user's `\Generator` object | Fiber terminates immediately; bridge returns `$fiber->getReturn()` (the Generator object). `Scope::next()` sees a Generator and runs it natively — Fiber overhead is one start/return, then untouched. |
+
+Every workflow handler, signal handler, update handler, query handler, and `Workflow::async()` task goes through `createFiberHandler` — Generator mode is just the Fiber bridge with one degenerate iteration.
+
+### The forwarding Generator
+
+When the Fiber suspends, the bridge wraps it in an inner Generator (the `(static function ...)` returning `\Generator`). That bridge Generator:
+- `yield`s whatever the Fiber suspended with (a `PromiseInterface` from `Workflow::timer(...)` etc.)
+- when `Scope::next()` sends back the resolved value, calls `$fiber->resume($sent)` to wake the Fiber
+- catches thrown values from `Scope::next()` and re-throws them inside the Fiber via `$fiber->throw($e)`
+
+To the rest of the runtime, the Fiber body is **indistinguishable** from a Generator body. No new dispatch loop, no new wire protocol, no separate event layer.
+
+## `ScopeContext::$fiberMode` — the state flag
+
+A boolean on `ScopeContext` that gates `FiberHelper::await()` behavior. Set sites (the **only** legitimate ones):
+
+| Site | Action | Why |
+|---|---|---|
+| `Scope::createFiberHandler` inner closure | `setFiberMode(true)` right before `$handler($values)` | Mark this Fiber as suspend-capable. |
+| `Scope::createFiberHandler` `try/catch` on `$fiber->start()` | `setFiberMode(false)` on throw | Restore flag if the body crashed before the bridge took over. |
+| `Scope::createFiberHandler` after `$fiber->isTerminated()` (sync completion) | `setFiberMode(false)` | The Fiber returned without suspending — Generator path effectively. |
+| Bridge Generator `try/finally` | `setFiberMode(false)` | Final reset when the Fiber finishes (normally or via exception). |
+| `Scope::destroy()` | `?->setFiberMode(false)` | Last-resort cleanup at scope teardown. |
+| `Process::setQueryExecutor` query closure | `setFiberMode(false)` (right after `setReadonly(true)`) | Queries are synchronous — they MUST NOT suspend even if the parent Fiber is in flight. |
+
+**Never** flip `fiberMode` in `Scope::cancel()`, `Scope::next()`, `Scope::nextPromise()`, `Scope::handleError()`, or any other intermediate site. A reset there leaks into a suspended child Fiber, and the next `FiberHelper::await` throws `FiberError: Cannot suspend outside of a fiber`. The bridge's `try/finally` is the contract; everything else must respect it.
+
+## `FiberHelper::await` — the suspension primitive
+
+[src/Experiments/Fibers/FiberHelper.php](../../src/Experiments/Fibers/FiberHelper.php):
+
+```php
+public static function await(PromiseInterface $promise): mixed
+{
+    if (!self::isInFiberMode()) {
+        throw new OutOfContextException(
+            'FiberHelper::await() can be used only inside a Fiber-mode workflow scope.',
+        );
+    }
+
+    return \Fiber::suspend($promise);
+}
+
+public static function isInFiberMode(): bool
+{
+    $context = Facade::getCurrentContext();
+    return $context instanceof ScopeContext && $context->isFiberMode();
+}
+```
+
+Every Fiber-mode `Workflow::*` method that maps to a promise call (`timer`, `executeActivity`, `executeChildWorkflow`, `getVersion`, `sideEffect`, `await`, `awaitWithTimeout`, `uuid*`, `continueAsNew`) delegates to the underlying `\Temporal\Workflow::*` and wraps the resulting promise in `FiberHelper::await(...)`. The Fiber suspends with the promise as the suspension value; the bridge Generator yields that promise to `Scope::next()`; the existing event loop resolves it; the resolved value comes back through `$fiber->resume($sent)` and `\Fiber::suspend()` returns it.
+
+For a workflow author, `Workflow::executeActivity(...)` simply "returns the activity result" — exactly like calling a normal function. There is no syntactic marker that suspension happened.
+
+## Public API surface — `\Temporal\Experiments\Fibers\Workflow`
+
+`src/Experiments/Fibers/Workflow.php` is a thin facade that mirrors `\Temporal\Workflow`. Three categories:
+
+**1. Pure delegators (synchronous accessors that don't suspend):**
+`getCurrentContext`, `now`, `isReplaying`, `getInfo`, `getUpdateContext`, `getInput`, `getStackTrace`, `allHandlersFinished`, `getLogger`, `getInstance`, `getCurrentDetails`, `setCurrentDetails`, `getLastCompletionResult`, `upsertMemo`, `upsertSearchAttributes`, `upsertTypedSearchAttributes`, `registerQuery`, `registerSignal`, `registerUpdate`, `registerDynamicSignal`, `registerDynamicQuery`, `registerDynamicUpdate`.
+
+**2. Fiber-suspending wrappers (delegate to `\Temporal\Workflow` then `FiberHelper::await`):**
+`await`, `awaitWithTimeout`, `getVersion`, `sideEffect`, `timer`, `continueAsNew`, `executeChildWorkflow`, `executeActivity`, `uuid`, `uuid4`, `uuid7`.
+
+Return-type tightening vs the base:
+- `timer(): void` (no `PromiseInterface<null>`)
+- `awaitWithTimeout(): bool` (no `PromiseInterface<bool>`)
+- `getVersion(): int` (no `PromiseInterface<int>`)
+
+**3. Scope helpers and stubs:**
+- `async`, `asyncDetached` — same `CancellationScopeInterface` contract as base.
+- `newActivityStub`, `newUntypedActivityStub`, `newChildWorkflowStub`, `newUntypedChildWorkflowStub`, `newContinueAsNewStub`, `newExternalWorkflowStub`, `newUntypedExternalWorkflowStub` — wrap base stubs in `FiberProxy` / `Fiber*Stub` so call results are auto-awaited.
+- `runLocked(Mutex|BaseMutex $mutex, callable)` — Fiber-mode mutex acquisition; uses `getInner()` for `Fibers\Mutex` to delegate to base mutex semantics.
+- `gather(callable ...$tasks)` — parallel fan-out via `async()` + `Promise::all`, returns a list of results synchronously to the Fiber.
+
+**4. Escape hatches:**
+- `timerPromise($interval)` — returns the raw `PromiseInterface<null>` (the only `*Promise()` variant); needed when feeding a timer into `Promise::race` or as the deadline for `awaitWithTimeout`. For any other "I want the raw promise" case, drop down to `\Temporal\Workflow::xxx(...)` directly.
+
+### Helper types
+
+| Class | Role |
+|---|---|
+| `Temporal\Experiments\Fibers\Mutex` | Fiber-flavored `Workflow\Mutex`. Wraps a base `Workflow\Mutex`; `getInner()` returns it for boundary unwrap. |
+| `Temporal\Experiments\Fibers\FiberProxy` | Magic proxy around a typed activity/child-workflow stub. Calls are forwarded to the base stub; promise return values get `FiberHelper::await()`-ed transparently. |
+| `Temporal\Experiments\Fibers\FiberActivityStub` / `FiberChildWorkflowStub` / `FiberExternalWorkflowStub` | Untyped stub wrappers. Same auto-await pattern as `FiberProxy`. |
+| `Temporal\Experiments\Fibers\Promise` | `all`, `any`, `race` helpers that auto-await and return raw values to the Fiber. |
+
+### Public API stability invariant
+
+`Temporal\Experiments\Fibers\*` symbols MUST NOT leak into stable public API surfaces (`src/Workflow/`, `src/Internal/Workflow/`, `src/Interceptor/`). The base `\Temporal\Workflow` interfaces accept only base types. The Fiber facade unwraps experimental types at its boundary:
+
+```php
+public static function await(callable|BaseMutex|Mutex|PromiseInterface ...$conditions): mixed
+{
+    return FiberHelper::await(\Temporal\Workflow::await(...self::unwrapConditions($conditions)));
+}
+
+private static function unwrapConditions(array $conditions): array
+{
+    $unwrapped = [];
+    foreach ($conditions as $condition) {
+        $unwrapped[] = $condition instanceof Mutex ? $condition->getInner() : $condition;
+    }
+    return $unwrapped;
+}
+```
+
+This pattern is the canonical fix for every "Fiber type should be accepted but stable API can't reference it" case.
+
+## How execution actually unfolds
+
+End-to-end trace of `Workflow::executeActivity('echo', ['hi'])` from a Fiber workflow body:
+
+```
+Fiber-mode workflow body
+  └─▶ Workflow::executeActivity('echo', ['hi'])              (Fibers facade)
+        └─▶ \Temporal\Workflow::executeActivity('echo', ['hi'])
+              └─▶ pushes ExecuteActivity request to outbound queue
+              └─▶ returns PromiseInterface<mixed>
+        └─▶ FiberHelper::await($promise)
+              └─▶ checks isInFiberMode() → true
+              └─▶ \Fiber::suspend($promise)
+                    │
+                    ▼
+        bridge Generator: `yield $value` (where $value = $promise)
+                    │
+                    ▼
+        Scope::next() — current() = PromiseInterface
+              └─▶ Scope::nextPromise($promise)
+                    └─▶ $promise->then($onFulfilled, $onRejected)
+                    └─▶ next() returns; coroutine suspended
+                    │
+                    │ (batch flushes to RR, RR runs activity, RR returns result)
+                    │
+        Client::dispatch(ActivityResult) → Deferred->resolve($payloads)
+              └─▶ $onFulfilled fires
+                    └─▶ defer(fn) → loop->once(ON_TICK, fn)
+                    │
+                    ▼
+        loop tick fires the deferred callback:
+              coroutine->send($result)
+                    └─▶ bridge Generator: $sent = $result; $fiber->resume($result)
+                          └─▶ \Fiber::suspend() returns $result inside the user's body
+                                └─▶ executeActivity() returns $result to the workflow body
+              next() continues to look at the next yield
+```
+
+The Fiber-mode and Generator-mode paths converge at "bridge Generator yields a promise to `Scope::next()`". Everything below that boundary is identical — same wire protocol, same event loop, same replay mechanics.
+
+## Replay: identical to Generator mode
+
+`Fiber` carries no Temporal-specific state — it is just a PHP stack. At replay time, the worker restarts the workflow process from scratch, calls the user handler, which starts a new Fiber, which generates the same outbound commands in the same order (request IDs `9000+` via the static counter). RoadRunner resolves them from history immediately. For the Fiber, this just looks like "every promise resolves instantly" — same as Generator mode.
+
+Same caveats apply:
+- Don't use `if (Workflow::isReplaying())` to branch logic.
+- Don't capture wall-clock time outside `Workflow::now()`.
+- Don't read from external sources mid-Fiber.
+
+The only difference: a Fiber's call stack is **visible** in PHP stack traces during replay (real `\Fiber` frames), where a Generator-mode body shows up as a regular function. This matters for `Workflow::getStackTrace()` and `enhancedStackTrace` query handlers — see [Gotchas](#gotchas).
+
+## Public API map (Generator → Fiber)
+
+| Generator | Fiber |
+|---|---|
+| `yield Workflow::timer(5)` | `Workflow::timer(5)` |
+| `$r = yield Workflow::executeActivity(...)` | `$r = Workflow::executeActivity(...)` |
+| `$r = yield Workflow::executeChildWorkflow(...)` | `$r = Workflow::executeChildWorkflow(...)` |
+| `yield Workflow::await($cond)` | `Workflow::await($cond)` |
+| `yield Workflow::awaitWithTimeout(5, $cond)` | `Workflow::awaitWithTimeout(5, $cond)` |
+| `$v = yield Workflow::getVersion('a', 1, 2)` | `$v = Workflow::getVersion('a', 1, 2)` |
+| `$id = yield Workflow::uuid4()` | `$id = Workflow::uuid4()` |
+| `yield $activityStub->method()` | `$activityStub->method()` (auto-await via `FiberProxy`) |
+| `yield Promise::all($promises)` | `Promise::all($scopes)` (via `Fibers\Promise`) |
+| `yield Workflow::continueAsNew(...)` | `Workflow::continueAsNew(...)` |
+| `Workflow::async(fn() => yield ...)` | `Workflow::async(fn() => ...)` |
+| `Workflow::runLocked($mutex, fn() => yield ...)` | `Workflow::runLocked($mutex, fn() => ...)` |
+| `#[WorkflowMethod] public function run(): \Generator` | `#[WorkflowMethod] public function run(): mixed` |
+| `#[SignalMethod] public function on(...): \Generator` | `#[SignalMethod] public function on(...): void` |
+
+## Gotchas
+
+### 1. Fiber mode is opt-in **per file** — workflow type names must be unique
+
+Both `\Temporal\Workflow` and `\Temporal\Experiments\Fibers\Workflow` workflows are registered on the same worker, on the same task queue, from the same `WorkerFactory`. The worker keeps a single `ArrayRepository` keyed by workflow type name (and activity prefix). Two workflows with the same `#[WorkflowMethod(name: "MyWorkflow")]` will boot-crash:
+
+```
+OutOfBoundsException: Entry with same identifier "MyWorkflow" already has been registered
+```
+
+When mirroring a Generator workflow into a Fiber sibling, rename:
+- `#[WorkflowMethod(name: "X")]` → `#[WorkflowMethod(name: "X_Fibers")]` (or `_Fibers_X`, any consistent infix)
+- `#[ActivityInterface(prefix: 'X.')]` → `#[ActivityInterface(prefix: 'X_Fibers.')]`
+- Every `#[Stub(...)]` that references either.
+- The argument to `replayFromJSON(...)` in any test that loads history fixtures.
+
+### 2. Fiber-mode workflow body MUST NOT `yield`
+
+If the body contains `yield` anywhere, the handler returns a `\Generator` object instead of a Fiber suspension. `createFiberHandler` calls `$handler($values)` inside the Fiber; the Fiber returns the Generator and terminates; bridge returns `$fiber->getReturn()` (the Generator); `Scope::next()` runs the Generator natively. The Fiber path **never engages** — `FiberHelper::isInFiberMode()` returns `false`, sentinel asserts pass on accident, no useful coverage.
+
+Validation grep:
+
+```
+grep -nE 'yield|: \\Generator' tests/Acceptance/Extra/.../Fibers/*.php
+```
+
+Add a `isFiberMode` assertion to every Fiber acceptance test as a tripwire:
+
+```php
+public function run(): array
+{
+    return [
+        'fiberMode' => Workflow::getCurrentContext() instanceof ScopeContext
+            && Workflow::getCurrentContext()->isFiberMode(),
+        // ...
+    ];
+}
+```
+
+### 3. Query handlers are synchronous — `fiberMode` MUST be `false` inside them
+
+`Process::setQueryExecutor` clones the main scope's `ScopeContext` via `withInput(new Input(...))`. The `$fiberMode` boolean copies by value. If the main scope is mid-suspend in Fiber mode (true) when a query arrives, the query closure inherits `true`. Any `Fibers\Workflow::*` call inside the query handler then enters `FiberHelper::await()`, calls `\Fiber::suspend()` — but the query runs on the main PHP stack, not inside a Fiber. Result: `FiberError: Cannot suspend outside of a fiber`.
+
+The reset is unconditional:
+
+```php
+$context = $this->scopeContext->withInput(new Input(...));
+$context->setReadonly(true);
+$context->setFiberMode(false);   // ← required
+Workflow::setCurrentContext($context);
+return $handler($input->arguments);
+```
+
+### 4. `Scope::startScope` must save/restore Facade context — but only in Fiber mode
+
+`Scope::next()` calls `makeCurrent()` which sets `Facade::$ctx` to the current scope. When a parent Fiber calls `Workflow::async(...)` (which calls `startScope()`), the child scope's synchronous start switches `Facade::$ctx` to the child. After `startScope()` returns to the parent Fiber, the parent's `Facade::$ctx` is wrong — its next `Workflow::await(...)` registers on the child scope.
+
+Fix:
+
+```php
+public function startScope(callable $handler, bool $detached, ?string $layer = null): CancellationScopeInterface
+{
+    $fiberMode = $this->scopeContext->isFiberMode();
+    $savedContext = $fiberMode ? Facade::getCurrentContext() : null;
+    $scope = $this->createScope($detached, $layer);
+    $scope->start($handler(...), EncodedValues::empty(), false);
+    if ($fiberMode) {
+        Facade::setCurrentContext($savedContext);
+    }
+    return $scope;
+}
+```
+
+**Why gated on `$fiberMode`:** Generator workflows tolerate the context leak — the leaked child context gets fixed by the next `makeCurrent()` in `Scope::next()` when the parent resumes via tick. Fiber workflows don't: the parent's body resumes immediately after `startScope` returns, before any tick happens. Unconditional restore breaks Generator workflows that rely on the leak.
+
+### 5. `Scope::cancel()` MUST NOT reset `fiberMode`
+
+A child scope's Fiber is suspended on a Mutex/Deferred. Cancellation propagates through the scope tree. If `cancel()` calls `setFiberMode(false)` on the shared `ScopeContext`, the next time the Fiber's bridge Generator resumes and the user body hits `FiberHelper::await`, `isInFiberMode()` returns `false` → `OutOfContextException` or `FiberError`. The only legitimate `fiberMode` writers are the bridge's `try/finally`, `destroy()`, and the query closure (see #3 above).
+
+### 6. `StackRenderer::$userFrameSeen` — load-bearing, do not revert
+
+`src/Internal/Support/StackRenderer.php` has a `$userFrameSeen` flag that gates `file`/`line` exposure to the **first** user frame only. Without it, `BuiltInPrefixedHandlersTest::enhancedStackTrace` fails because the rendered stack trace exposes implementation file paths instead of user code. This flag is the **single point of regression** for Fiber stack traces — Fiber frames are real PHP frames (not abstracted by `\Generator`), so the renderer sees them and must filter correctly. Auto-review agents have reverted this flag twice; never accept a diff that removes it.
+
+### 7. `Fibers\Mutex` pre-Fiber `lock()` is a single-use no-op
+
+`Fibers\Mutex::lock()` returns a no-op resolved promise when called before the workflow's Fiber starts (i.e., when `isInFiberMode()` is false — typically inside the workflow's `__construct`). This is **intentional** and safe for the first lock only — the constructor wants to pre-lock the mutex so the first `runLocked(...)` call from inside `run()` waits. A second pre-Fiber `lock()` would silently leak a Deferred. If the pattern appears more than once before the Fiber starts, the test is wrong.
+
+### 8. `file_put_contents` / debug calls in `Process.php` corrupt RoadRunner framing
+
+Any `file_put_contents`, `var_dump`, `print_r` left in `src/Internal/Workflow/Process/*` after debugging will corrupt RR's goridge STDOUT framing — the worker's response becomes unparseable and the workflow task times out at 60s. The `Arch` test catches `trap(...)` but not `file_put_contents`. Manual grep is the only defense:
+
+```
+grep -rn 'file_put_contents\|var_dump\|print_r(' src/Internal/Workflow/Process/
+```
+
+## See also
+
+- [workflow-coroutines.md](workflow-coroutines.md) — the Generator-mode runtime that Fiber mode bridges to. **Read this first.**
+- [worker-rr-protocol.md](worker-rr-protocol.md) — wire protocol between PHP and RoadRunner. Unchanged by Fiber mode.
+- [architecture.md](architecture.md) — runtime architecture overview.
+- `src/Experiments/Fibers/` — facade source.
+- `src/Internal/Workflow/Process/Scope.php:480` — the bridge.
+- `tests/Acceptance/Extra/.../Fibers/` — Fiber-mode acceptance tests, paired with their Generator-mode siblings.
diff --git a/docs/runtime/worker-rr-protocol.md b/docs/runtime/worker-rr-protocol.md
new file mode 100644
index 000000000..217b1a1ba
--- /dev/null
+++ b/docs/runtime/worker-rr-protocol.md
@@ -0,0 +1,141 @@
+# Wire-протокол PHP ↔ RoadRunner
+
+Всё, что происходит между моментом «PHP создал команду» и моментом «RR получил её batch'ем». Описывает только PHP-сторону протокола; что делает Go-плагин внутри RR — отдельная тема.
+
+## Двунаправленный канал на одной очереди
+
+PHP-воркер держит единственную in-memory очередь `ArrayQueue` ([src/Internal/Queue/ArrayQueue.php](../../src/Internal/Queue/ArrayQueue.php)), создаваемую в [src/WorkerFactory.php:331](../../src/WorkerFactory.php:331). В неё пушатся **и outbound requests** (наши команды к RR), **и inbound responses** (наши ответы на server-requests от RR):
+
+```
+                 ┌─────────────────────────────┐
+PHP outbound ──▶ │                             │ ──▶ encoder ──▶ RR
+                 │      shared ArrayQueue      │
+PHP inbound  ──▶ │                             │
+responses        └─────────────────────────────┘
+```
+
+**Owner'ы:**
+- [src/Internal/Transport/Client.php](../../src/Internal/Transport/Client.php) — пушит в очередь outbound `RequestInterface` (например `NewTimer`), хранит таблицу `requests[id] => Deferred`.
+- [src/Internal/Transport/Server.php](../../src/Internal/Transport/Server.php) — пушит в ту же очередь ответы (`SuccessClientResponse`/`FailedClientResponse`) на server-requests, которые пришли от RR.
+
+В конце каждого `dispatch()`-вызова всё содержимое очереди **одним батчем** улетает в RR.
+
+## Главный цикл `dispatch()`
+
+[src/WorkerFactory.php:381](../../src/WorkerFactory.php:381):
+
+```php
+private function dispatch(string $messages, array $headers): string
+{
+    $commands = $this->codec->decode($messages, $headers);
+
+    foreach ($commands as $command) {
+        $this->env->update($command->getTickInfo());
+        if ($command instanceof ServerResponseInterface) {
+            $this->client->dispatch($command);     // ответ RR на наш прошлый request
+            continue;
+        }
+        $this->server->dispatch($command, $headers); // новый server-request от RR
+    }
+
+    $this->tick();                                  // прокручиваем event-loop
+
+    return $this->codec->encode($this->responses); // сливаем очередь в proto-frame
+}
+```
+
+Шаги:
+1. Декодируем batch от RR в коллекцию `CommandInterface`.
+2. Для каждой команды — либо `Client::dispatch` (резолв нашего deferred'а), либо `Server::dispatch` (запуск нашего обработчика).
+3. `tick()` — прокручиваем все отложенные callback'и (см. [workflow-coroutines.md](workflow-coroutines.md)). Здесь же выполняются workflow-coroutine'ы и наполняют очередь новыми outbound-командами.
+4. Кодируем всю очередь в proto-frame и возвращаем.
+
+`waitBatch()`/`send()` оборачивают goridge-receive и goridge-send в [src/Worker/Transport/RoadRunner.php](../../src/Worker/Transport/RoadRunner.php).
+
+## Кодек: `proto` или `json`
+
+Выбирается через env var `RR_CODEC` ([src/WorkerFactory.php:367-376](../../src/WorkerFactory.php:367)). Дефолт — JSON, но в production обычно `proto`.
+
+Proto-формат: [src/Worker/Transport/Codec/ProtoCodec/Encoder.php:35](../../src/Worker/Transport/Codec/ProtoCodec/Encoder.php:35) — каждая команда становится `RoadRunner\Temporal\DTO\V1\Message`:
+
+```protobuf
+message Message {
+    int64 id = 1;
+    string command = 2;     // имя команды, например "NewTimer"
+    string options = 3;     // JSON-строка с опциями
+    Payloads payloads = 4;  // Temporal Payloads
+    Header header = 5;      // interceptor-header
+    Failure failure = 6;
+    // + tick-метаданные:
+    string tick_time = 8;
+    int64 history_length = 9;
+    int64 history_size = 10;
+    bool replay = 11;
+    bool continue_as_new_suggested = 12;
+}
+
+message Frame {
+    repeated Message messages = 1;
+}
+```
+
+> Тонкость: пустой `options` сериализуется как `'{}'` через `\stdClass`, не `'[]'`. Go-сторона ждёт map, не array — пустой PHP-массив сломает декод. См. [src/Worker/Transport/Codec/ProtoCodec/Encoder.php:49-51](../../src/Worker/Transport/Codec/ProtoCodec/Encoder.php:49) и [src/Internal/Transport/Request/ExecuteNexusOperation.php:53](../../src/Internal/Transport/Request/ExecuteNexusOperation.php:53) — там это сделано явно для `nexusHeaders`.
+
+## Request ID — process-local автоинкремент
+
+[src/Worker/Transport/Command/Client/Request.php:30](../../src/Worker/Transport/Command/Client/Request.php:30):
+
+```php
+protected static int $lastID = 9000;
+// ...
+private function getNextID(): int
+{
+    $next = ++static::$lastID;
+    if ($next >= \PHP_INT_MAX) {
+        $next = static::$lastID = 1;
+    }
+    return $next;
+}
+```
+
+**Ньюансы:**
+- ID — `static`, общий на все request'ы внутри **одного PHP-процесса**, не per-workflow.
+- Старт с 9000, чтобы не конфликтовать с RR-internal ID-ами в тех редких случаях, когда они пересекаются.
+- Wrap при достижении `PHP_INT_MAX` — формально безопасный, но на практике недостижимый.
+- ID — это **тэг для матчинга request↔response в PHP-side таблице**, не идентификатор для Temporal-сервера. У сервера свой `event_id`/`command_id` в history.
+
+## Три ID-пространства
+
+При работе с Nexus легко запутаться — поэтому фиксируем явно:
+
+| ID | Где живёт | Назначение |
+|---|---|---|
+| `Request::$id` (9000+) | PHP, process-local | Связь PHP-side request ↔ его deferred |
+| `command_id` / `event_id` | Temporal history | Workflow-scoped позиция в истории |
+| `invocationId` | RR-internal | Идентификация in-flight handler-вызова на стороне RR (для cooperative cancel) |
+
+Эти три счётчика **не совпадают** и не должны сравниваться напрямую.
+
+## TickInfo: метаданные каждого WorkflowTask
+
+[src/Worker/Transport/Command/Server/TickInfo.php](../../src/Worker/Transport/Command/Server/TickInfo.php):
+
+```php
+final class TickInfo
+{
+    public function __construct(
+        public readonly \DateTimeInterface $time,
+        public readonly int $historyLength = 0,
+        public readonly int $historySize = 0,
+        public readonly bool $continueAsNewSuggested = false,
+        public readonly bool $isReplaying = false,
+    ) {}
+}
+```
+
+Декодер кладёт `TickInfo` в каждое декодированное сообщение ([src/Worker/Transport/Codec/ProtoCodec.php:65-71](../../src/Worker/Transport/Codec/ProtoCodec.php:65)). В `dispatch()` затем `env->update($command->getTickInfo())` записывает поля в [src/Worker/Environment/Environment.php:36](../../src/Worker/Environment/Environment.php:36) — именно отсюда читается `Workflow::isReplaying()`, `Workflow::now()`.
+
+## См. также
+
+- [Архитектура runtime'а](architecture.md) — общий контекст.
+- [Workflow и корутины](workflow-coroutines.md) — как `tick()` запускает coroutine'ы и почему replay не требует специальной логики в PHP.
diff --git a/docs/runtime/workflow-coroutines.md b/docs/runtime/workflow-coroutines.md
new file mode 100644
index 000000000..e360d62e2
--- /dev/null
+++ b/docs/runtime/workflow-coroutines.md
@@ -0,0 +1,230 @@
+# Workflow-coroutines, event-loop и replay
+
+Как PHP-генератор внутри workflow-метода приостанавливается на `yield` и просыпается, и почему replay не требует специальной обработки в PHP.
+
+> **Experimental Fiber mode:** `\Temporal\Experiments\Fibers\Workflow` позволяет писать те же workflow-методы без `yield` и `\Generator`. Под капотом каждый handler оборачивается в `\Fiber`, который мостится в Generator-протокол ниже — см. [fibers.md](fibers.md). Этот документ остаётся базой: Fiber mode — это надстройка над описанным здесь циклом.
+
+## Workflow — это PHP-generator
+
+Любой workflow-метод — это generator:
+
+```php
+#[WorkflowMethod]
+public function run(): \Generator
+{
+    yield Workflow::timer(5);
+    yield Workflow::timer(5);
+    return 'done';
+}
+```
+
+`Workflow::timer()` возвращает `PromiseInterface`. Когда `yield` отдаёт promise, **сам PHP** не знает что с ним делать — он просто приостанавливает генератор. Возобновить его можно только извне через `Generator::send($value)`.
+
+**Кто-то** должен:
+1. Получить yield'нутое значение (`$gen->current()`).
+2. Если это promise — навесить on-fulfilled, который позже сделает `$gen->send($result)`.
+3. Если promise отрезолвился — продолжить генератор.
+4. Повторить пока `$gen->valid()` не станет `false`.
+
+Этим занимается `Scope`.
+
+## `Scope` — обёртка над генератором
+
+[src/Internal/Workflow/Process/Scope.php:41](../../src/Internal/Workflow/Process/Scope.php:41).
+
+Каждый workflow-coroutine выполняется внутри `Scope`. Главный workflow-метод — корневой scope; каждый дочерний `Workflow::async()`, `signal handler`, `update handler` — отдельный дочерний scope. Scope'ы образуют дерево cancellation.
+
+Scope хранит:
+- `DeferredGenerator $coroutine` — обёртка над PHP-генератором с lazy-start семантикой ([src/Internal/Workflow/Process/DeferredGenerator.php](../../src/Internal/Workflow/Process/DeferredGenerator.php));
+- `Deferred $deferred` — promise, который резолвится результатом всего scope'а;
+- `string $layer` — какой event-layer использовать для defer'а возобновлений;
+- `bool $cancelled`, `bool $detached` — состояние scope'а.
+
+## Движок: `Scope::next()`
+
+[src/Internal/Workflow/Process/Scope.php:412](../../src/Internal/Workflow/Process/Scope.php:412):
+
+```php
+protected function next(): void
+{
+    $this->makeCurrent();
+    begin:
+    $this->context->resolveConditions();
+
+    if (!$this->coroutine->valid()) {
+        $this->onResult($this->coroutine->getReturn());
+        return;
+    }
+
+    $current = $this->coroutine->current();
+
+    switch (true) {
+        case $current instanceof Workflow\Mutex:
+            $this->nextPromise($this->context->await($current));
+            break;
+        case $current instanceof PromiseInterface:
+            $this->nextPromise($current);
+            break;
+        case $current instanceof Deferred:
+            $this->nextPromise($current->promise());
+            break;
+        case $current instanceof RequestInterface:
+            // yield Request — допустимая короткая запись для yield client->request($r)
+            $this->nextPromise($this->context->getClient()->request($current, $this->scopeContext));
+            break;
+        case $current instanceof \Generator:
+            $this->nextPromise($this->createScope(false)->attach($current));
+            break;
+        default:
+            // не-promise значение — пропускаем дальше без ожидания
+            $this->coroutine->send($current);
+            goto begin;
+    }
+}
+```
+
+**Решение `next()` зависит от типа yield'утого значения.** Promise / Deferred / Mutex — навешиваем callback и suspend'имся. Generator — заворачиваем в дочерний Scope. RequestInterface — короткая запись для «отправь и подожди». Любое другое значение — просто пропускаем.
+
+## Возобновление: `Scope::nextPromise()`
+
+[src/Internal/Workflow/Process/Scope.php:463](../../src/Internal/Workflow/Process/Scope.php:463):
+
+```php
+private function nextPromise(PromiseInterface $promise): void
+{
+    $onFulfilled = function (mixed $result): mixed {
+        $this->defer(function () use ($result): void {
+            $this->makeCurrent();
+            $this->coroutine->send($result);   // ← возобновление генератора
+            $this->next();                     // ← смотрим следующий yield
+        });
+        return $result;
+    };
+    $onRejected = function (\Throwable $e): void {
+        $this->defer(fn() => $this->handleError($e));
+    };
+    $promise->then($onFulfilled, $onRejected);
+}
+```
+
+Ключевой момент: **возобновление откладывается через `defer()`**, не выполняется синхронно в callback'е. Это нужно чтобы все callback'и из одного «батча» резолвов отработали в правильном порядке (по layer'ам).
+
+## Event-loop без ReactPHP
+
+В SDK **нет** ReactPHP-loop'а. Вместо него — простой event-emitter с фиксированным порядком слоёв.
+
+[src/WorkerFactory.php:86](../../src/WorkerFactory.php:86):
+
+```php
+class WorkerFactory implements WorkerFactoryInterface, LoopInterface
+```
+
+`WorkerFactory` сам реализует `LoopInterface` через `EventEmitterTrait` ([src/Internal/Events/EventEmitterTrait.php](../../src/Internal/Events/EventEmitterTrait.php)).
+
+`tick()` — это просто `emit()` всех слоёв по порядку:
+
+```php
+public function tick(): void
+{
+    $this->emit(LoopInterface::ON_SIGNAL);
+    $this->emit(LoopInterface::ON_CALLBACK);
+    $this->emit(LoopInterface::ON_QUERY);
+    $this->emit(LoopInterface::ON_TICK);
+    $this->emit(LoopInterface::ON_FINALLY);
+}
+```
+
+`Scope::defer()` ([src/Internal/Workflow/Process/Scope.php:550](../../src/Internal/Workflow/Process/Scope.php:550)):
+
+```php
+private function defer(\Closure $tick): void
+{
+    $this->services->loop->once($this->layer, $tick);
+    $this->services->queue->count() === 0 and $this->services->loop->tick();
+}
+```
+
+`once()` — добавить one-shot listener. Вторая строка — **если очередь outbound-команд пустая, тикнуть прямо сейчас**. Это позволяет цепочке резолвов «провалиться насквозь» в одном dispatch'е, не дожидаясь следующего batch'а от RR.
+
+## Полный путь одного `yield Workflow::timer(5)`
+
+```
+                        ┌─ Workflow::timer(5)
+                        │   = NewTimer #9001 push в очередь
+                        │   возвращает Deferred[9001]->promise()
+                        │
+yield ──▶ Scope::next() ──▶ current() = PromiseInterface
+                        │
+                        ├─ nextPromise($promise)
+                        │   $promise->then(onFulfilled, onRejected)
+                        │
+                        └─ выход из next() — coroutine suspended
+
+                        ┌────── batch уходит в RR ──────┐
+                        │       (включая NewTimer #9001) │
+                        └─────────────────────────────────┘
+
+                        ┌────── через какое-то время:    ┐
+                        │   RR пушит SuccessResponse #9001 │
+                        └─────────────────────────────────┘
+
+dispatch() ──▶ Client::dispatch(#9001) ──▶ Deferred[9001]->resolve($payloads)
+                                              │
+                                              └─▶ react-promise → onFulfilled
+                                                   └─▶ defer(fn) → loop->once(ON_TICK, fn)
+
+dispatch() ──▶ tick() ──▶ emit(ON_TICK) ──▶ fn():
+                                            coroutine->send($result)  ← generator resume
+                                            next()                    ← следующий yield
+                                                 └─▶ если новый yield — снова push, suspend
+                                                 └─▶ если return — onResult($return)
+```
+
+## Replay: PHP не знает и не должен знать
+
+При падении воркера и переисполнении workflow'а **PHP не делает ничего особенного**. Он:
+1. Запускает workflow с самого начала.
+2. Снова создаёт `NewTimer #9001`, push'ит в очередь.
+3. Снова suspend'ится на promise.
+4. Снова отдаёт batch RR'у.
+
+Разница только в **скорости ответа RR**. При replay'е RR (точнее Temporal Go SDK внутри `rrtemporal`) видит, что в history уже есть `TimerStartedEvent #9001` и `TimerFiredEvent #9001`, и **не идёт на сервер**, а сразу формирует `SuccessResponse #9001` в следующем batch'е к PHP.
+
+Для PHP это выглядит как «promise зарезолвился очень быстро». Никакого специального cache на стороне PHP нет.
+
+### Что в PHP знает про replay
+
+[src/Worker/Environment/Environment.php:36](../../src/Worker/Environment/Environment.php:36) хранит `bool $isReplaying`, обновляемый из `TickInfo` каждого пришедшего сообщения.
+
+Использования:
+
+| Место | Что делает |
+|---|---|
+| [src/Internal/Workflow/Logger.php:82](../../src/Internal/Workflow/Logger.php:82) | Глушит логи во время replay'а (`enableLoggingInReplay` по умолчанию `false`) |
+| [src/Internal/Workflow/Process/Process.php:163](../../src/Internal/Workflow/Process/Process.php:163), [:239](../../src/Internal/Workflow/Process/Process.php:239) | Передаёт в `WorkflowInfo` (read-only API для пользователя) |
+| [src/Internal/Workflow/Process/Process.php:300](../../src/Internal/Workflow/Process/Process.php:300) | Подавляет handler-state warning'и |
+| [src/Internal/Workflow/WorkflowContext.php:266](../../src/Internal/Workflow/WorkflowContext.php:266) | Не шлёт `setCurrentDetails` повторно при replay |
+| [src/Internal/Transport/Router/InvokeUpdate.php:60](../../src/Internal/Transport/Router/InvokeUpdate.php:60) | Не запускает validation handler у update'а при replay |
+
+И **всё**. `Client::request()` ([src/Internal/Transport/Client.php:81](../../src/Internal/Transport/Client.php:81)) безусловно делает `queue->push($request)` — флаг replay не проверяется.
+
+### Почему так правильно
+
+- **PHP-stateless относительно истории.** Память между tick'ами не должна сохраняться, иначе при падении воркера replay не сработает.
+- **Один кодовый путь.** В workflow-коде не нужно `if (Workflow::isReplaying())`. Алгоритм одинаков.
+- **Детерминизм проверяется автоматически.** Если код пошёл другим путём — counter `Request::$lastID` назначит другой ID, RR увидит mismatch с history, упадёт с nondeterminism error.
+
+## Тонкости
+
+- **`Request::$lastID` сбрасывается на 9000 при старте процесса воркера** — потому что это `static` поле класса. RR при replay поднимает свежий PHP-процесс, ID-нумерация повторяется bit-for-bit.
+- **`Scope` объединяет coroutine и cancellation scope** в один объект (комментарий [Scope.php:35](../../src/Internal/Workflow/Process/Scope.php:35) явно отмечает это отличие от Java SDK, где они разделены).
+- **`DeferredGenerator` подменяет завершённый generator на dummy-генератор** ([DeferredGenerator.php:176](../../src/Internal/Workflow/Process/DeferredGenerator.php:176)) — чтобы `Iterator::next()`-вызовы после завершения не падали.
+- **`yield SomeRequest`** — короткая запись, обрабатываемая в `Scope::next()` через `RequestInterface` ветку. Эквивалентно `yield $client->request($req)`.
+- **`yield $value` где `$value` — не promise** — `next()` сразу делает `send($value)` и переходит к `goto begin;`. То есть generator движется без suspension'а.
+- **`Scope::defer()` тикает loop сразу** если outbound-очередь пустая — позволяет цепочкам резолвов работать в одном dispatch'е.
+
+## См. также
+
+- [Fiber-mode runtime](fibers.md) — опциональный режим без `yield`, тот же event-loop.
+- [Wire-протокол PHP↔RR](worker-rr-protocol.md) — как именно `NewTimer` уходит в RR.
+- [Архитектура runtime'а](architecture.md) — общая картина.
diff --git a/docs/testing/README.md b/docs/testing/README.md
new file mode 100644
index 000000000..85c10ff07
--- /dev/null
+++ b/docs/testing/README.md
@@ -0,0 +1,47 @@
+# Тестирование
+
+Документация по тестам Temporal PHP SDK: какие suite'ы есть, как они запускаются, какую инфраструктуру поднимают и какой mini-фреймворк используют.
+
+## Содержание
+
+| Документ | О чём |
+|---|---|
+| [Виды тестов](test-suites.md) | Unit / Functional / Acceptance (App + Extra + Harness) / Arch — кто за что отвечает, file-naming, наши vs upstream |
+| [Инфраструктура](infrastructure.md) | Auto-bootstrap по suite, lifecycle серверов и RR, restart RR на fail, fast/slow генерация, `tests/runner.php`, `composer get:binaries` |
+| [Testing framework](framework.md) | `testing/` — `Environment`, `WorkflowTestCase`, `ActivityMocker`, `Replay`, `Downloader` |
+
+## Quick reference
+
+```bash
+# Запуск
+composer test:unit            # быстрые unit-тесты, без серверов
+composer test:func            # functional, поверх temporal-test-server (time-skip)
+composer test:accept          # все acceptance, поверх temporal start-dev
+composer test:accept-fast     # только быстрые acceptance (< 1s)
+composer test:accept-slow     # только медленные acceptance
+composer test:arch            # архитектурные правила (dump/dd проверки)
+
+# Один тест по filter
+vendor/bin/phpunit --testsuite=Unit --filter=FooTestCase
+tests/runner.php vendor/bin/phpunit --testsuite=Acceptance --filter=BarTest
+
+# Перегенерация fast/slow split (после прогона test:accept)
+php tests/phpunit-generate.php
+
+# Скачать бинарники (RR + temporal CLI + temporal-test-server)
+composer get:binaries
+```
+
+## Главные принципы
+
+- **Тесты сами поднимают и тушат серверы.** Bootstrap'ы регистрируют `register_shutdown_function`'ы; ничего вручную запускать/останавливать не надо.
+- **При фейле acceptance-теста RR перезапускается** ([tests/Acceptance/App/TestCase.php:117-122](../../tests/Acceptance/App/TestCase.php:117)). Следующий тест получает чистого воркера. Каскадных фейлов не будет.
+- **Functional ≠ Acceptance.** Functional — поверх Java time-skipping test-server'а (быстрые long-timer тесты). Acceptance — поверх реального `temporal start-dev` (нужны server-side фичи без time-skip'а).
+- **Harness не трогаем.** Эти тесты приходят от Temporal-команды для cross-SDK совместимости. Наши тесты — в `Acceptance/Extra/`.
+- **Fast/slow split — генерируется**, не задаётся вручную. После прогона `test:accept` запускаешь `phpunit-generate.php`, и `phpunit.xml.dist` обновляется.
+
+## См. также
+
+- [Архитектура runtime'а](../runtime/architecture.md) — как RR работает с PHP в general.
+- [Wire-протокол PHP↔RR](../runtime/worker-rr-protocol.md) — что передаётся между PHP и RR.
+- Корневой [tests/README.md](../../tests/README.md) — оригинальные комментарии к структуре тестов.
diff --git a/docs/testing/framework.md b/docs/testing/framework.md
new file mode 100644
index 000000000..dd9641f95
--- /dev/null
+++ b/docs/testing/framework.md
@@ -0,0 +1,93 @@
+# Testing framework — `testing/`
+
+Папка [testing/](../../testing/) — это переиспользуемый mini-SDK для написания тестов. Он же используется собственными тестами SDK через `tests/`, и его же могут использовать сторонние пакеты, тестирующие свои workflow'ы / activity'и поверх Temporal PHP SDK.
+
+Пакет публикуется как `temporal/testing`.
+
+## Содержимое
+
+```
+testing/src/
+├── Environment.php             — управление temporal-server'ами и RR
+├── Command.php                 — параметры запуска (workdir, namespace, address, TLS)
+├── Downloader.php              — скачивание temporal-test-server из Java-релизов
+├── SystemInfo.php              — определение OS/arch для выбора binary
+├── TestService.php             — низкоуровневая обёртка
+├── ActivityMocker.php          — мок активити для unit-тестов workflow'а
+├── WorkerMock.php              — фейк-воркер
+├── WorkerFactory.php           — фабрика для тестового воркера
+├── WorkflowTestCase.php        — базовый PHPUnit-класс с замоканным runtime'ом
+├── WithoutTimeSkipping.php     — отключатель time-skip'а в скоупе
+├── DeprecationCollector.php    — собирает PHP-deprecations за время теста
+├── DeprecationMessage.php      — DTO для записи deprecation'а
+├── Replay/                     — replay-тесты workflow'ов из history
+└── Support/                    — внутренние хелперы
+```
+
+## Главные кубики
+
+### `Environment` — оркестратор внешних процессов
+
+[testing/src/Environment.php](../../testing/src/Environment.php). Единый фасад для запуска/остановки `temporal start-dev`, `temporal-test-server` и RoadRunner'а. Используется и в `tests/Functional/bootstrap.php`, и в `tests/Acceptance/App/Runtime/`.
+
+Ключевые методы:
+
+| Метод | Что делает |
+|---|---|
+| `Environment::create()` | Создание |
+| `startTemporalServer(...)` | Запуск **реального** `temporal start-dev` с custom dynamic-config-флагами и search attributes |
+| `startTemporalTestServer(...)` | Запуск **Java time-skipping** test-server'а |
+| `startRoadRunner(...)` | Запуск RR с указанной командой/конфигом |
+| `stopTemporalServer()` / `stopTemporalTestServer()` / `stopRoadRunner()` | Остановки |
+| `stop()` | Останавливает всё (один shutdown handler) |
+| `isTemporalRunning()` / `isTemporalTestRunning()` / `isRoadRunnerRunning()` | Статусы |
+
+`startRoadRunner()` ([Environment.php:212](../../testing/src/Environment.php:212)) проверяет, что **temporal-сервер уже поднят** перед стартом RR — иначе RR упадёт на попытке подключения. Если ни один сервер не запущен — exception.
+
+### `Downloader` — скачивание test-server'а
+
+[testing/src/Downloader.php](../../testing/src/Downloader.php). Тянет `temporal-test-server` из релизов **Java SDK** (не из основного Temporal CLI релиза — там его нет). URL: `https://api.github.com/repos/temporalio/sdk-java/releases/...`.
+
+Архив именуется `temporal-test-server_<version>_<os>_<arch>.{zip,tar.gz}`. Файл-pattern в коде: `temporal-test-server_[^_]+_([^_]+)_([^.]+)\.(?:zip|tar.gz)$`.
+
+### `Command` — параметры запуска
+
+[testing/src/Command.php](../../testing/src/Command.php). Иммутабельный VO с workDir, namespace, temporal address, TLS-параметрами, дополнительными CLI-аргументами PHP-binary и worker-script'у. Передаётся в `Environment` и `RuntimeBuilder`.
+
+### `WorkflowTestCase` — для unit-тестов workflow'ов
+
+[testing/src/WorkflowTestCase.php](../../testing/src/WorkflowTestCase.php) — базовый класс. Используется когда тестируется чистый workflow-код (без запуска Temporal-сервера); полагается на `WorkerMock` + `ActivityMocker` для in-process симуляции. Подходит для проверки decision-логики workflow'а: «при таком input'е workflow должен вызвать activity X с такими аргументами».
+
+Это **не** замена acceptance-теста — `WorkflowTestCase` не покрывает реальные history-events, retry-policy сервера, time-skipping и т.п. Зато даёт мс-уровень на test и не требует Temporal-сервера.
+
+### `ActivityMocker`, `WorkerMock`
+
+[testing/src/ActivityMocker.php](../../testing/src/ActivityMocker.php), [testing/src/WorkerMock.php](../../testing/src/WorkerMock.php). Хелперы для in-process тестирования. Activity подменяется на closure, worker — на in-memory диспетчер.
+
+### `Replay/` — тесты на history
+
+[testing/src/Replay/](../../testing/src/Replay/) — `WorkflowReplayer` и поддерживающий код. Берёт сохранённую history workflow'а (JSON-export от Temporal сервера или CLI), прогоняет через PHP-воркер и валидирует, что ничего не сломалось.
+
+Это критично для regression-тестирования: если изменение в workflow-коде ломает детерминизм, replay-тест по старой history упадёт с nondeterminism error.
+
+### `WithoutTimeSkipping`
+
+[testing/src/WithoutTimeSkipping.php](../../testing/src/WithoutTimeSkipping.php) — RAII-обёртка: на время своей жизни в скоупе **отключает** time-skipping в `temporal-test-server`'е (для тестов, где надо проверить именно реальное ожидание). Полезно когда weak-тест-server слишком торопится.
+
+## Когда что использовать
+
+| Сценарий | Что брать |
+|---|---|
+| Юзер тестирует свой workflow, без Temporal-сервера | `WorkflowTestCase` + `ActivityMocker` |
+| Проверить что workflow не сломал детерминизм после правок | `WorkflowReplayer` (Replay/) с сохранённой history |
+| Проверить interaction'ы поверх настоящего Temporal в CI | `Environment::startTemporalTestServer` (если ОК time-skip) или `startTemporalServer` (если нужны server-side фичи) + `startRoadRunner` |
+| Проверить server-side фичи (versioning, deployment, schedule) | Только `startTemporalServer` (`temporal start-dev`) |
+
+## Зависимость от Java для `temporal-test-server`
+
+`temporal-test-server` — это **не** PHP и не Go binary. Это standalone-релиз из Java SDK с time-skipping'ом, написанный на Java и упакованный как native-binary через GraalVM. Качается отдельно от основного Temporal CLI. Это стоит держать в голове при отладке проблем с Functional-suite'ом — если test-server-binary не качается, проблема может быть в Java-релизах (rate-limit GitHub API, недоступность асссета для конкретной OS+arch).
+
+## См. также
+
+- [Виды тестов](test-suites.md) — какой test suite использует какие хелперы.
+- [Инфраструктура](infrastructure.md) — как именно `Environment` оркестрирует процессы в bootstrap'ах.
diff --git a/docs/testing/infrastructure.md b/docs/testing/infrastructure.md
new file mode 100644
index 000000000..dbcaa7ec1
--- /dev/null
+++ b/docs/testing/infrastructure.md
@@ -0,0 +1,161 @@
+# Инфраструктура тестов
+
+Как тесты сами поднимают Temporal-сервер и RoadRunner, как разделяются fast/slow и что делает `tests/runner.php`.
+
+## Auto-bootstrap по suite
+
+Корневой [tests/bootstrap.php](../../tests/bootstrap.php) определяет имя suite'а из `--testsuite=`, `--filter=` или path-аргумента в `argv`, и подключает соответствующий suite-bootstrap:
+
+```
+tests/bootstrap.php
+  ├─ tests/Unit/bootstrap.php          (нет — Unit'у bootstrap не нужен)
+  ├─ tests/Functional/bootstrap.php    → temporal-test-server + RR
+  └─ tests/Acceptance/bootstrap.php    → temporal start-dev + RR
+```
+
+Если bootstrap для suite'а не найден — просто continue, никакой инициализации.
+
+Suite-имя вычисляется так: `Acceptance-Fast` → `Acceptance` (всё после `-` отбрасывается). То есть `test:accept-fast` и `test:accept-slow` тоже подцепляют общий `Acceptance/bootstrap.php`.
+
+## Сценарий запуска
+
+### Functional
+
+[tests/Functional/bootstrap.php](../../tests/Functional/bootstrap.php) делает:
+
+1. `Environment::startTemporalTestServer()` — поднимает `temporal-test-server` (Java-binary, time-skipping).
+2. Регистрирует системные search attributes через `SearchAttributeTestInvoker`.
+3. `Environment::startRoadRunner(...)` — поднимает RR с конфигом `tests/Functional/.rr.silent.yaml` и worker-script'ом `tests/Functional/worker.php`.
+4. `register_shutdown_function(fn() => $environment->stop())` — гарантирует остановку обоих процессов при выходе.
+
+### Acceptance
+
+[tests/Acceptance/bootstrap.php](../../tests/Acceptance/bootstrap.php) делает:
+
+1. `RuntimeBuilder::init()` — выставляет error reporting, регистрирует `DeprecationCollector`, выставляет feature flags ([RuntimeBuilder.php:91-100](../../tests/Acceptance/App/RuntimeBuilder.php:91)).
+2. Создаёт `Environment::create()`.
+3. Строит `State` через `RuntimeBuilder::createEmpty()` со списком namespace'ов под `Harness` и `Extra`.
+4. Создаёт `TemporalStarter` и `RRStarter`, запускает их.
+
+`TemporalStarter::start()` ([tests/Acceptance/App/Runtime/TemporalStarter.php](../../tests/Acceptance/App/Runtime/TemporalStarter.php)) поднимает `temporal start-dev` с набором dynamic-config-флагов (включает update API, async-accepted, multi-operation, eager-start, deployment versions и др.) и pre-зарегистрированными search attributes (`foo`, `bar`, `testBool`, …).
+
+`RRStarter::start()` ([tests/Acceptance/App/Runtime/RRStarter.php](../../tests/Acceptance/App/Runtime/RRStarter.php)) собирает командную строку RR с `-w <rrConfigDir> -o temporal.namespace=... -o temporal.address=... -o server.command=...` и зовёт `Environment::startRoadRunner(...)`.
+
+## Жизненный цикл серверов
+
+| Что | Когда стартует | Когда останавливается |
+|---|---|---|
+| `temporal-test-server` (Functional) | в bootstrap'е | через `register_shutdown_function` |
+| `temporal start-dev` (Acceptance) | в bootstrap'е | через `register_shutdown_function` в `TemporalStarter::__construct` |
+| RoadRunner (Functional) | сразу после temporal-test-server | через `register_shutdown_function` |
+| RoadRunner (Acceptance) | сразу после temporal-dev | через `register_shutdown_function` в `RRStarter::__construct`, плюс **рестарт после fail'а теста** |
+
+## Restart RR на fail теста
+
+[tests/Acceptance/App/TestCase.php:117-122](../../tests/Acceptance/App/TestCase.php:117):
+
+```php
+if (!$e instanceof SkippedTest) {
+    // Restart RR if a Error occurs
+    $roadRunnerStarter = $container->get(RRStarter::class);
+    $roadRunnerStarter->stop();
+    $roadRunnerStarter->start();
+}
+```
+
+Базовый acceptance-`TestCase` оборачивает `runTest()` в try/catch. Если тест упал по любой причине **кроме `SkippedTest`** — RR полностью перезапускается. Зачем:
+
+- В случае фейла worker мог остаться в неконсистентном состоянии: workflow в подвешенном виде, неосвобождённые ресурсы, утечка состояния между тестами.
+- Перезапуск гарантирует что **следующий тест получит чистый воркер**, и фейл одного теста не каскадирует в фейлы остальных.
+- `SkippedTest` исключён, потому что skip — это не фейл выполнения, ничего не сломалось.
+
+`temporal start-dev` при этом **не** перезапускается — он живёт всё время до конца suite'а.
+
+## Разделение fast/slow
+
+`composer test:accept-fast` и `composer test:accept-slow` запускают разные подсуиты, чтобы локально не ждать долгие тесты. Список slow-файлов **не задаётся вручную**, а **генерируется** скриптом.
+
+### Команда генерации
+
+```bash
+php tests/phpunit-generate.php
+```
+
+[tests/phpunit-generate.php](../../tests/phpunit-generate.php) делает:
+
+1. Читает JUnit-логи из:
+   - `runtime/phpunit-acceptance-junit.xml`
+   - `runtime/phpunit-acceptance-fast-junit.xml`
+   - `runtime/phpunit-acceptance-slow-junit.xml`
+2. Для каждого testcase берёт `time` (длительность) и группирует по файлу — оставляет **максимум** среди методов файла.
+3. Если max-time файла ≥ `--threshold` (по умолчанию `1.0` сек) → файл попадает в `slow`, иначе в `fast`.
+4. Перезаписывает `phpunit.xml.dist` (или путь из `argv[2]`):
+   - `Acceptance-Fast` suite — `<exclude>` со slow-файлами, `<file>` с остальными;
+   - `Acceptance-Slow` suite — `<file>` со slow-файлами.
+
+То есть **процедура такая**: один раз прогнать полный `composer test:accept`, чтобы получить JUnit-логи, потом запустить `phpunit-generate.php` — и `phpunit.xml.dist` обновится. Дальше `test:accept-fast` будет быстрее.
+
+### Threshold
+
+Дефолт — 1 секунда. Можно переопределить:
+
+```bash
+php tests/phpunit-generate.php --threshold=2.5
+```
+
+## `tests/runner.php` — обёртка для CI
+
+[tests/runner.php](../../tests/runner.php) — wrapper вокруг PHPUnit, парсит JUnit-лог и обрабатывает edge-case CI: PHPUnit может вернуть exit-code `0` даже когда тест упал из-за внутренней ошибки. runner проверяет JUnit-output и форсит exit-code в случае таких ошибок.
+
+В composer-скриптах все suite'ы кроме `arch` запускаются через runner:
+
+```json
+"test:unit":   "tests/runner.php vendor/bin/phpunit --testsuite=Unit ...",
+"test:func":   "tests/runner.php vendor/bin/phpunit --testsuite=Functional ...",
+"test:accept": "tests/runner.php vendor/bin/phpunit --testsuite=Acceptance ...",
+"test:arch":   "phpunit --testsuite=Arch ..."
+```
+
+Arch без runner'а потому что не требует CI-special'а.
+
+## Конкретный тест
+
+```bash
+# Unit
+vendor/bin/phpunit --testsuite=Unit --filter=SomeTestCase
+
+# Functional (нужен сервер — runner.php подцепит bootstrap)
+tests/runner.php vendor/bin/phpunit --testsuite=Functional --filter=SomeTestCase
+
+# Acceptance
+tests/runner.php vendor/bin/phpunit --testsuite=Acceptance --filter=SomeTest
+```
+
+`bootstrap.php` сам определит suite по `--filter` или path-аргументу — поэтому если запускать тест без `--testsuite`, но с filter'ом матчащим `Temporal\Tests\Acceptance\...`, инфраструктура всё равно поднимется.
+
+## Бинарники
+
+```bash
+composer get:binaries
+```
+
+[composer.json:95-98](../../composer.json:95) — два шага:
+
+1. `dload get` (через [internal/dload](https://github.com/spiral/dload)) — качает RoadRunner и Temporal CLI / temporal-test-server.
+2. `RoadRunnerVersionChecker::postUpdate` — пост-update проверка совместимости версии RR с SDK.
+
+`temporal-test-server` качается из релизов Java SDK ([testing/src/Downloader.php:13](../../testing/src/Downloader.php:13)) по URL `https://api.github.com/repos/temporalio/sdk-java/releases/...`. Он **не** идёт в Temporal-CLI релизе, поэтому отдельный downloader.
+
+## Переменные окружения
+
+| Var | Где используется | Назначение |
+|---|---|---|
+| `TEMPORAL_ADDRESS` | bootstrap'ы и тесты | По умолчанию `127.0.0.1:7233`; для acceptance — обычно реальный сервер |
+| `RR_CODEC` | RR-конфиг и worker-script | `proto` (default) или `json` |
+| `ACTIVITY_WORKERS` | Acceptance bootstrap | Сколько worker-процессов поднять (default `2`) |
+
+## См. также
+
+- [Виды тестов](test-suites.md) — какой suite за что отвечает.
+- [Testing framework](framework.md) — `testing/` mini-SDK, на котором всё это построено.
+- [Архитектура runtime'а](../runtime/architecture.md) — как RR общается с PHP вообще.
diff --git a/docs/testing/test-suites.md b/docs/testing/test-suites.md
new file mode 100644
index 000000000..a8a6600a7
--- /dev/null
+++ b/docs/testing/test-suites.md
@@ -0,0 +1,97 @@
+# Виды тестов
+
+В проекте четыре физических test suite'а с разными требованиями к окружению и разной зоной ответственности.
+
+```
+tests/
+├── Unit/             — изолированные, без внешних зависимостей      (*TestCase.php)
+├── Functional/       — поверх temporal-test-server (Java, time-skip) (*TestCase.php)
+├── Acceptance/       — поверх реального temporal start-dev           (*Test.php)
+│   ├── App/          — runtime + общий код для acceptance'а (не тесты сами по себе)
+│   ├── Extra/        — наши тесты «всей нутрянки» SDK
+│   └── Harness/      — кросс-SDK тесты Temporal-команды
+├── Arch/             — архитектурные правила (отсутствие dump/dd, и т.п.)
+└── Nexus/            — Nexus subsystem (Unit/ под suite Unit, *Test.php)
+```
+
+## Unit — `tests/Unit/`
+
+Изолированные тесты, не требуют ни Temporal-сервера, ни RR. Запускаются на чистом PHPUnit. Тестируют чистую логику: парсеры, validator'ы, преобразователи, утилиты.
+
+- Файл-суффикс: `*TestCase.php`.
+- Bootstrap: общий `tests/bootstrap.php` (специального suite-bootstrap нет).
+- Запуск: `composer test:unit`.
+
+Подкаталог `tests/Nexus/Unit/` подцепляется тем же suite Unit'а, но его файлы нарекаются `*Test.php` — это особенность Nexus-subsystem'а.
+
+## Functional — `tests/Functional/`
+
+Тестируют сценарии, требующие настоящего Temporal-сервера, **но** с time-skipping'ом — это нужно когда тест ждёт, скажем, недельный таймер, и не хочет ждать его реально. Используется `temporal-test-server` из Java SDK distribution: он умеет «проматывать» время автоматически, когда workflow висит на таймере или sleep'е.
+
+- Файл-суффикс: `*TestCase.php`.
+- Bootstrap: [tests/Functional/bootstrap.php](../../tests/Functional/bootstrap.php) — поднимает `temporal-test-server` через `Environment::startTemporalTestServer()`, потом RR через `Environment::startRoadRunner(...)`. Закрытие — через `register_shutdown_function`.
+- Запуск: `composer test:func`.
+- Бинарник `temporal-test-server` качается из релизов Java SDK ([testing/src/Downloader.php](../../testing/src/Downloader.php)) при `composer get:binaries`.
+
+## Acceptance — `tests/Acceptance/`
+
+Полный E2E поверх **реального** `temporal start-dev` (без time-skipping'а). Используется когда тест должен проверить реальное поведение (worker versioning, deployment versions, eager workflow start, update'ы и т.п.).
+
+Делится на три подпапки с разной зоной ответственности:
+
+### `App/` — runtime, не тесты
+
+Сборка тестового runtime'а, общие хелперы и базовый `TestCase`. Это **не сами тесты**, а инфраструктура для них. Сюда попадают:
+
+- [tests/Acceptance/App/RuntimeBuilder.php](../../tests/Acceptance/App/RuntimeBuilder.php) — построение `State` (workdir, namespace, address, taskQueues), регистрация feature flags, обнаружение feature-классов.
+- [tests/Acceptance/App/Runtime/TemporalStarter.php](../../tests/Acceptance/App/Runtime/TemporalStarter.php) и [RRStarter.php](../../tests/Acceptance/App/Runtime/RRStarter.php) — запуск/остановка `temporal start-dev` и RR.
+- [tests/Acceptance/App/TestCase.php](../../tests/Acceptance/App/TestCase.php) — базовый класс с error-handling'ом, history-pretty-print'ом и **RR-restart'ом на падении теста**.
+
+### `Extra/` — наши acceptance тесты
+
+Тесты, которые мы пишем, чтобы проверить «всю нутрянку» SDK: интеграцию workflow / activity / signal / update / query / child-workflow / continue-as-new / schedule / data-converter / interceptor / plugin / nexus / versioning / deployment.
+
+- Файл-суффикс: `*Test.php`.
+- Запуск: `composer test:accept` (всё), `composer test:accept-fast`, `composer test:accept-slow` — см. [infrastructure.md](infrastructure.md#разделение-fastslow).
+
+### `Harness/` — cross-SDK тесты команды
+
+Тесты, написанные Temporal-командой (с координацией между SDK на разных языках). Проверяют выполнение спецификации фичи: «такой-то workflow с такими-то signal'ами должен дать такую-то history». Эти тесты **обычно не трогаем**.
+
+- Файл-суффикс: `*Test.php`.
+- При обновлении harness'ов — синхронизировать с upstream-репозиторием Temporal-команды, не редактировать локально.
+
+## Arch — `tests/Arch/`
+
+Архитектурные ограничения на код: запрет случайно оставленных `dump()`, `dd()`, `var_dump()`, `print_r()`, проверки структуры пакетов и подобное. Не требуют Temporal-сервера или RR.
+
+- Запуск: `composer test:arch`.
+- Дёргать вручную обычно не нужно — это CI-уровень. Хотя можно прогнать локально перед PR.
+- Запускается **без** `tests/runner.php`: в [composer.json](../../composer.json) команда — `phpunit --testsuite=Arch`, без runner-обёртки. Suite не нуждается в JUnit-парсинге CI-failure'ов.
+
+## Сводная таблица
+
+| Suite | Где | Сервер | RR | Время | Пишем сами? |
+|---|---|---|---|---|---|
+| Unit | `tests/Unit` | — | — | мс | да |
+| Nexus Unit | `tests/Nexus/Unit` | — | — | мс | да |
+| Functional | `tests/Functional` | `temporal-test-server` (time-skip) | да | сек | да |
+| Acceptance/Extra | `tests/Acceptance/Extra` | `temporal start-dev` | да | секунды-десятки | да |
+| Acceptance/Harness | `tests/Acceptance/Harness` | `temporal start-dev` | да | секунды-десятки | нет, синхронизируем |
+| Arch | `tests/Arch` | — | — | мс | редко (само-управляющиеся правила) |
+
+## Файл-нейминг
+
+| Где | Суффикс |
+|---|---|
+| `tests/Unit/`, `tests/Functional/` | `*TestCase.php` |
+| `tests/Acceptance/Extra/`, `tests/Acceptance/Harness/` | `*Test.php` |
+| `tests/Nexus/Unit/` | `*Test.php` (исключение в Unit-suite'е) |
+| `tests/Arch/` | `*TestCase.php` |
+
+См. также `composer.json:phpunit` config для точного match-pattern'а.
+
+## См. также
+
+- [Инфраструктура запуска](infrastructure.md) — серверы, RR-lifecycle, fast/slow.
+- [Testing framework](framework.md) — `testing/` папка как переиспользуемый mini-SDK для тестов.
diff --git a/docs/testing/transcript-capture.md b/docs/testing/transcript-capture.md
new file mode 100644
index 000000000..b1aa5a9ce
--- /dev/null
+++ b/docs/testing/transcript-capture.md
@@ -0,0 +1,322 @@
+# Test transcript capture — usage guide
+
+Every acceptance run captures the full stream of messages between PHP workers and RoadRunner, plus PSR-3 logs, exceptions (including retried ones), the workflow history of every test, and a `[FATAL]` line if a worker crashes. Open one file after the run and you see everything.
+
+---
+
+## TL;DR
+
+```bash
+composer test:accept-fast              # run any acceptance suite
+composer test:transcript:last          # merge per-process shards into one file
+less runtime/tests/transcripts/_merged/transcript.log
+```
+
+If a test fails, PHPUnit also prints the path to stderr:
+
+```
+[transcript] /Users/.../runtime/tests/transcripts/phpunit__pid32098__1778699827739.log
+[transcript] run composer test:transcript:last to view the merged stream
+```
+
+---
+
+## Where the files live
+
+All transcripts go under one directory at the project root:
+
+```
+sdk-php/
+└── runtime/
+    └── tests/
+        └── transcripts/                            # ← all artifacts live here
+            ├── phpunit__pid<pid>__<startMs>.log    # PHPUnit process writes here:
+            │                                       #   [TEST_START], [TEST_END], [HISTORY], [HISTORY_ERROR]
+            ├── worker__pid<pid>__<startMs>.log     # Each PHP worker process spawned by RR:
+            │                                       #   [WIRE_INBOUND], [WIRE_OUTBOUND], [LOG],
+            │                                       #   [EXCEPTION], [ERROR], [FATAL], [META]
+            ├── worker__pid<otherPid>__...log       # One file per worker PID (default num_workers=2)
+            └── _merged/
+                └── transcript.log                  # ← single chronologically-merged view,
+                                                    #   produced by composer test:transcript:last
+```
+
+Filename anatomy:
+
+- **`phpunit__`** — the PHPUnit (test client) process. One file per `composer test:*` run.
+- **`worker__`** — a PHP worker process. RoadRunner runs N workers (controlled by `tests/Acceptance/.rr.yaml:activities.num_workers`), so you'll typically see one `worker__*` file per active worker. RoadRunner respawns crashed workers, and each respawn gets a fresh PID → fresh file (the old PID file is left intact for forensics).
+- **`pid<N>__<startMs>`** — uniquifies files when PIDs are reused across runs.
+
+> The directory is **wiped at the START of every acceptance run** (see `tests/Acceptance/bootstrap.php`). That's intentional: the artifact reflects the most recent run only. If you need to preserve it, copy it elsewhere immediately after the run.
+
+Configurable via env var: set `TEMPORAL_TRANSCRIPT_DIR=/some/path` (absolute or repo-relative) to change the destination.
+
+---
+
+## How to use it
+
+### 1. Run any acceptance test as usual
+
+```bash
+composer test:accept             # full suite
+composer test:accept-fast        # fast tier
+composer test:accept-slow        # slow tier
+# or:
+vendor/bin/phpunit --testsuite=Acceptance --filter='TranscriptHappyPath'
+```
+
+Capture is **on by default** for acceptance (`tests/Acceptance/.rr.yaml` sets `TEMPORAL_WIRE_TRACE: "1"`). No action needed. The merge file is NOT auto-generated.
+
+### 2. Merge the per-process shards into one file
+
+```bash
+composer test:transcript:last
+```
+
+This script (`bin/transcript-merge.php`):
+- Reads every `*.log` file under `runtime/tests/transcripts/`,
+- Sorts every line by `(timestamp, pid, sequence)`,
+- Writes the result to `runtime/tests/transcripts/_merged/transcript.log`,
+- Prints summary stats to stderr (wire frame counts, history line counts, fatal line counts).
+
+You can also run it manually:
+
+```bash
+php bin/transcript-merge.php
+```
+
+### 3. Read or grep the merged file
+
+```bash
+less runtime/tests/transcripts/_merged/transcript.log
+```
+
+Or jump straight to what you care about — see [Common queries](#common-queries) below.
+
+### 4. Clean up manually (optional)
+
+```bash
+composer clean:transcripts
+```
+
+Removes every file under `runtime/tests/transcripts/`. Normally not needed — the next acceptance run does this automatically.
+
+---
+
+## What you'll see in the file
+
+Every line looks like this:
+
+```
+2026-05-13T19:17:17.334416+00:00 32150 20 [WIRE_INBOUND] frame_id=7 bytes=200 payload={"headers":{...},"body":{...}}
+└─── ISO8601 timestamp ─────────┘ │     │   │           └─── attributes ─────┘ └── optional JSON payload ─────────┘
+                                  │     │   └── section tag
+                                  │     └── per-PID monotonic sequence
+                                  └── PID of the producing process
+```
+
+Section tags you'll encounter:
+
+| Section | Source | What it means |
+|---|---|---|
+| `META` | every process | Lifecycle markers — writer init, fatal-handler registered, host recording started, activity/workflow entry+completion |
+| `TEST_START` / `TEST_END` | PHPUnit | Test boundary. `TEST_END` carries `status=passed/failed/skipped`, `duration_ms`, `exception_class` |
+| `LOG` | worker | `Workflow::getLogger()->info(...)` and any SDK PSR-3 log call |
+| `WIRE_INBOUND` | worker | Every frame the worker received FROM RoadRunner (server-driven workflow tick, activity invocation, signal delivery, ...) |
+| `WIRE_OUTBOUND` | worker | Every frame the worker SENT to RoadRunner (workflow command, activity response, completion, ...) — `frame_id` matches the corresponding `WIRE_INBOUND` |
+| `EXCEPTION` | worker | An activity/workflow/nexus call threw. `phase` and `attempt` tell you which one. Retries produce one line per attempt. |
+| `ERROR` | worker | PHP `E_WARNING`, `E_NOTICE`, etc., trapped by `set_error_handler` (does not stop execution) |
+| `FATAL` | either | Worker died with a fatal error or uncaught throwable. The transcript still has every earlier line. |
+| `HISTORY` | PHPUnit | One line per `HistoryEvent` from the workflow execution the test touched. `event_type` like `EVENT_TYPE_WORKFLOW_EXECUTION_STARTED`, `EVENT_TYPE_ACTIVITY_TASK_FAILED`, etc. |
+| `HISTORY_ERROR` | PHPUnit | History fetch itself failed (the test result is unaffected) |
+| `WIRE_ERROR` | worker | RoadRunner-level transport error from the worker side |
+| `TRUNCATED` | worker | The writer hit its 50 MB soft cap and rotated |
+
+A more detailed schema reference is in [`Section reference`](#section-reference) at the bottom of this page.
+
+---
+
+## Common queries
+
+```bash
+# Just opened the file: how big is the merged stream and what does it contain?
+composer test:transcript:last     # prints counts to stderr
+
+# Show every line for one specific test
+grep -nE '\[(TEST_START|TEST_END|EXCEPTION|FATAL|HISTORY)\].*method=testHappyPathRoundTripIsCaptured' \
+  runtime/tests/transcripts/_merged/transcript.log
+
+# Find every activity retry across the run
+grep '\[EXCEPTION\].*phase=activity_throw' \
+  runtime/tests/transcripts/_merged/transcript.log
+
+# How many times did each activity retry?
+grep '\[EXCEPTION\].*phase=activity_throw' \
+  runtime/tests/transcripts/_merged/transcript.log \
+  | grep -oE 'name=\S+|attempt=\d+'
+
+# Workflow history for a specific workflow id
+grep '\[HISTORY\].*workflow_id=01957d4f-' \
+  runtime/tests/transcripts/_merged/transcript.log
+
+# Did any worker process crash?
+grep '\[FATAL\]' runtime/tests/transcripts/_merged/transcript.log \
+  || echo 'clean run, no fatals'
+
+# Watch wire frames flow for one task queue (live)
+grep --line-buffered -E '\[(WIRE_INBOUND|WIRE_OUTBOUND)\].*Extra_Transcript_TranscriptRetry' \
+  runtime/tests/transcripts/_merged/transcript.log
+
+# Were any PHP warnings or notices raised?
+grep '\[ERROR\]' runtime/tests/transcripts/_merged/transcript.log
+```
+
+---
+
+## Adding log lines from your own activity code
+
+`Workflow::getLogger()` already routes into the transcript automatically. **Activities** in the SDK don't have a built-in logger, so use the test-only facade:
+
+```php
+use Temporal\Tests\Acceptance\App\Logger\ActivityLog;
+
+class PaymentActivity
+{
+    #[ActivityMethod]
+    public function charge(int $invoiceId): bool
+    {
+        ActivityLog::info('paying invoice', ['invoice_id' => $invoiceId]);
+        // ... do work ...
+        ActivityLog::warning('payment slow', ['elapsed_ms' => 4200]);
+        return true;
+    }
+}
+```
+
+Each call becomes a `[LOG]` line in the worker's transcript file. Outside the acceptance container (e.g. unit tests), the facade is a no-op and prints `[meta] activity_log_unbound` to STDERR.
+
+---
+
+## Environment variables
+
+| Variable | Default | What it does |
+|---|---|---|
+| `TEMPORAL_WIRE_TRACE` | `"1"` in `tests/Acceptance/.rr.yaml` | When non-`"0"`, the worker host is wrapped with `RecordingHost` so every inbound/outbound frame is captured. Set to `"0"` to disable wire-frame capture but keep logs/exceptions/history. |
+| `TEMPORAL_TRANSCRIPT_DIR` | `runtime/tests/transcripts` | Where transcripts are written. Absolute or repo-relative path. |
+
+Both are read by `tests/Acceptance/worker.php` and `tests/Acceptance/App/Logger/LoggerFactory.php`.
+
+---
+
+## Crash-survival guarantees
+
+The transcript is designed so that **a worker crash leaves a usable file behind**.
+
+- Every write is `flock(LOCK_EX) → fwrite → fflush → unflock`. Sub-`PIPE_BUF` lines are atomic per POSIX, so concurrent writers from multiple worker processes cannot corrupt each other.
+- `TranscriptWriter` keeps a persistent `fopen('ab')` file descriptor and calls `fflush` on every write — so the line is on disk before `fwrite` returns.
+- `FatalHandler` installs three layers:
+  - `set_error_handler` — captures `E_WARNING`/`E_NOTICE` as `[ERROR]` and chains to PHP's default (returns `false`).
+  - `set_exception_handler` — captures any uncaught throwable as `[FATAL]`, then `exit(1)`.
+  - `register_shutdown_function` — if `error_get_last()` reveals an `E_ERROR`/`E_PARSE`/`E_CORE_ERROR`/`E_COMPILE_ERROR`/`E_USER_ERROR`, writes `[FATAL]` and flushes one last time.
+
+### Known limits
+
+These scenarios cannot produce a `[FATAL]` line, but **everything written before** them is still on disk:
+
+- `SIGKILL` / `kill -9` / kernel OOM killer — PHP never runs shutdown handlers.
+- Segmentation fault inside a C extension (`ext-grpc`, `ext-protobuf`).
+- Stack overflow before the shutdown phase reached.
+- Worker killed by RoadRunner's `destroy_timeout`.
+
+For these, you'll see the last `[WIRE_INBOUND]` or `[LOG]` line right before the worker disappeared, with no terminal `[FATAL]` marker. That gap is itself a diagnostic.
+
+---
+
+## Writing your own verification tests
+
+For new acceptance tests that need to assert on what was captured, use `TranscriptReader`:
+
+```php
+use Temporal\Tests\Acceptance\App\Logger\LoggerFactory;
+use Temporal\Tests\Acceptance\App\Logger\TranscriptReader;
+use Temporal\Tests\Acceptance\App\Logger\TranscriptSection;
+
+$reader = new TranscriptReader(LoggerFactory::getTranscriptDirectory());
+
+// Wait until any TEST_END marker shows up (with a hard timeout)
+$reader->waitForQuiescence(5000);
+
+// Scope to the lines written between this test's TEST_START and TEST_END
+$lines = $reader->linesForTest(static::class, 'testMyScenario');
+
+// Or query directly
+$throws = $reader->findBySectionAndAttribute(
+    TranscriptSection::EXCEPTION,
+    'phase',
+    'activity_throw',
+);
+$wireOutbound = $reader->findBySection(TranscriptSection::WIRE_OUTBOUND);
+
+// Assert ordering
+$ok = $reader->hasSequence([
+    ['section' => TranscriptSection::WIRE_OUTBOUND, 'attributes' => ['frame_id' => 1]],
+    ['section' => TranscriptSection::EXCEPTION, 'attributes' => ['attempt' => 1]],
+    ['section' => TranscriptSection::WIRE_OUTBOUND, 'attributes' => ['frame_id' => 2]],
+]);
+```
+
+Working examples:
+
+- `tests/Acceptance/Extra/Transcript/TranscriptHappyPathTest.php` — minimal round-trip.
+- `tests/Acceptance/Extra/Transcript/TranscriptRetryTest.php` — retries with per-attempt assertions.
+- `tests/Acceptance/Extra/Transcript/TranscriptWorkflowFailureTest.php` — workflow-side failure.
+
+---
+
+## Section reference (detailed)
+
+| Section | Producer | Key attributes | Payload | Notes |
+|---|---|---|---|---|
+| `META` | every process | `event` | optional | Lifecycle: `writer_initialized`, `fatal_handler_registered`, `host_recording_started`, `activity_start`, `activity_completed`, `workflow_*_start`, `workflow_*_completed`, `nexus_*_start`, `nexus_*_completed`. |
+| `TEST_START` | PHPUnit | `class`, `method` | — | Written before `parent::runTest()`. |
+| `TEST_END` | PHPUnit | `class`, `method`, `status`, `duration_ms`, `exception_class?` | — | Written in `finally`. |
+| `LOG` | worker | `level`, `message` | original context array | `Workflow::getLogger()` calls + `ActivityLog::*()` facade. |
+| `WIRE_INBOUND` | worker | `frame_id`, `bytes` | `headers`, `body` (decoded JSON or base64 raw) | From `RecordingHost::waitBatch`. |
+| `WIRE_OUTBOUND` | worker | `frame_id`, `bytes` | `body` (decoded JSON or base64 raw) | From `RecordingHost::send`. Matched with inbound by `frame_id`. |
+| `WIRE_ERROR` | worker | `class` | `message`, `trace` | From `RecordingHost::error` — transport-level failure. |
+| `EXCEPTION` | worker (interceptors) | `phase`, `name?`, `attempt?`, `activity_id?`, `workflow_id?`, `is_replaying?` | `class`, `message`, `trace`, `previous` | `phase` ∈ `activity_throw`, `workflow_execute`, `workflow_signal`, `workflow_query`, `workflow_update`, `workflow_validate_update`, `nexus_start`, `nexus_cancel`. Each retry attempt produces one line. |
+| `FATAL` | either | `class`/`type`, `file`, `line` | `message`, `trace` | From `FatalHandler::register`. |
+| `ERROR` | worker | `type`, `file`, `line` | `message` | Non-fatal PHP errors caught by `set_error_handler` — execution continues. |
+| `HISTORY` | PHPUnit | `workflow_id`, `run_id`, `event_id`, `event_type`, `event_time` | `attrs` = proto JSON of the `HistoryEvent` | One line per Temporal history event, written in `finally` for every test that injected a `WorkflowStubInterface`. |
+| `HISTORY_ERROR` | PHPUnit | `workflow_id`, `class` | `message` | History fetch failed; the test's own failure is preserved. |
+| `TRUNCATED` | worker | `reason`, `from`, `to` | — | Soft 50 MB cap reached; writer rotated to `<path>.<N>`. |
+
+---
+
+## Source map (where to read the code)
+
+| File | Role |
+|---|---|
+| `tests/Acceptance/App/Logger/TranscriptWriter.php` | Append-only, locked, persistent-FD writer. |
+| `tests/Acceptance/App/Logger/TranscriptReader.php` | Typed query API: `findBySection`, `findByAttribute`, `hasSequence`, `waitForQuiescence`, `linesForTest`. |
+| `tests/Acceptance/App/Logger/TranscriptSection.php` | The enum of section tags. |
+| `tests/Acceptance/App/Logger/TranscriptLine.php` | DTO returned by the reader. |
+| `tests/Acceptance/App/Logger/TranscriptAdapter.php` | PSR-3 → transcript bridge (used by FanoutLogger). |
+| `tests/Acceptance/App/Logger/FanoutLogger.php` | PSR-3 fan-out: writes to existing `FileLogger` AND the transcript. |
+| `tests/Acceptance/App/Logger/ActivityLog.php` | Static facade for activity-side `[LOG]` lines. |
+| `tests/Acceptance/App/Logger/LoggerFactory.php` | Resolves the transcript directory and creates writers. |
+| `tests/Acceptance/App/Logger/ClientLogger.php` | Pre-existing PSR-3 record reader (still used by other tests). |
+| `tests/Acceptance/App/Transport/RecordingHost.php` | `HostConnectionInterface` decorator capturing every frame. |
+| `tests/Acceptance/App/Runtime/FatalHandler.php` | Three-layer error/exception/shutdown handler. |
+| `tests/Acceptance/App/Interceptor/TranscriptActivityInterceptor.php` | Wraps `ActivityInboundInterceptor::handleActivityInbound`. |
+| `tests/Acceptance/App/Interceptor/TranscriptWorkflowInterceptor.php` | Wraps all five `WorkflowInboundCallsInterceptor` methods. |
+| `tests/Acceptance/App/Interceptor/TranscriptNexusInterceptor.php` | Wraps `NexusOperationInboundCallsInterceptor`. |
+| `tests/Acceptance/App/Feature/WorkerFactory.php` | Mounts the three interceptors via `CompositePipelineProvider`. |
+| `tests/Acceptance/worker.php` | Worker entry — registers `FatalHandler`, builds host, optionally wraps with `RecordingHost`. |
+| `tests/Acceptance/bootstrap.php` | Clears `runtime/tests/transcripts/` at suite start, creates the PHPUnit-side writer, binds it to the container. |
+| `tests/Acceptance/App/TestCase.php` | Writes `[TEST_START]/[TEST_END]/[HISTORY]/[HISTORY_ERROR]` and prints the file path to stderr on failure. |
+| `tests/Acceptance/.rr.yaml` | Sets `TEMPORAL_WIRE_TRACE=1` and `TEMPORAL_TRANSCRIPT_DIR` for the worker process. |
+| `bin/transcript-merge.php` | The `composer test:transcript:last` script. |
+| `tests/Unit/Logger/TranscriptWriterTestCase.php` | 11 unit tests for the writer + reader. |
+| `tests/Unit/Logger/FatalHandlerTestCase.php` | 3 unit tests proving fatal-error survival. |
+| `tests/Acceptance/Extra/Transcript/*.php` | Three live acceptance tests demonstrating happy path / retry / workflow failure capture. |
diff --git a/docs/workflow/current-details.md b/docs/workflow/current-details.md
new file mode 100644
index 000000000..c22b701f2
--- /dev/null
+++ b/docs/workflow/current-details.md
@@ -0,0 +1,98 @@
+# Current Details
+
+**Current Details** — это механизм в Temporal для динамического обновления описания или статуса Workflow прямо во время его выполнения.
+
+## Обзор
+
+В отличие от статических Summary или Details, которые устанавливаются при запуске и не меняются, Current Details можно обновлять многократно. Это значение отображается в Temporal UI и CLI, позволяя пользователям видеть текущий прогресс или состояние Workflow без выполнения специальных Query запросов.
+
+### Основные возможности:
+- Динамическое обновление во время выполнения.
+- Поддержка **Temporal Markdown** (жирный текст, списки, ссылки и т.д.).
+- Поддержка многострочного текста.
+- Отображение в Temporal UI в поле "Current details".
+
+## Использование в Workflow
+
+Для работы с Current Details используйте статические методы класса `Temporal\Workflow`.
+
+### Установка деталей
+
+Метод `setCurrentDetails` отправляет команду на обновление статуса. Рекомендуется использовать `yield`, чтобы дождаться подтверждения отправки команды.
+
+```php
+use Temporal\Workflow;
+
+#[WorkflowInterface]
+class OrderProcessingWorkflow
+{
+    #[WorkflowMethod]
+    public function process(Order $order): Generator
+    {
+        // Установка начального статуса
+        yield Workflow::setCurrentDetails("📋 Заказ получен: #{$order->id}");
+        
+        // Валидация
+        yield Workflow::setCurrentDetails("🔍 Валидация заказа...");
+        yield Workflow::executeActivity('validateOrder', [$order]);
+        
+        // Обработка платежа
+        yield Workflow::setCurrentDetails("💳 Обработка платежа...");
+        $payment = yield Workflow::executeActivity('processPayment', [$order]);
+        
+        // Финальный статус с использованием Markdown
+        yield Workflow::setCurrentDetails(
+            "✅ Заказ успешно обработан!\n\n" .
+            "**ID заказа:** {$order->id}\n" .
+            "**Сумма:** \${$payment->amount}"
+        );
+        
+        return $payment;
+    }
+}
+```
+
+### Получение текущих деталей
+
+Вы можете получить последнее установленное значение в рамках текущего выполнения:
+
+```php
+$currentStatus = Workflow::getCurrentDetails();
+```
+
+## Использование в интерцепторах
+
+Вы можете перехватывать вызовы `setCurrentDetails` с помощью `WorkflowOutboundCallsInterceptor`.
+
+```php
+use Temporal\Interceptor\WorkflowOutboundCallsInterceptor;
+use Temporal\Interceptor\WorkflowOutboundCalls\SetCurrentDetailsInput;
+
+class MyInterceptor implements WorkflowOutboundCallsInterceptor
+{
+    use WorkflowOutboundCallsInterceptorTrait;
+
+    public function setCurrentDetails(SetCurrentDetailsInput $input, callable $next): PromiseInterface
+    {
+        // Можно модифицировать текст перед отправкой
+        $modifiedInput = $input->with(
+            details: "[LOG] " . $input->details
+        );
+        
+        return $next($modifiedInput);
+    }
+}
+```
+
+## Ограничения и требования
+
+- **Версия RoadRunner**: Требуется версия **2025.2.0** или выше.
+- **Безопасность**: Изображения, произвольный HTML и скрипты не поддерживаются в целях безопасности.
+
+## Поддержка Markdown
+
+Current Details поддерживает базовый синтаксис Temporal Markdown:
+- `# Заголовок`
+- `**Жирный текст**`
+- `- Списки`
+- `[Ссылки](https://temporal.io)`
diff --git a/phpunit.xml.dist b/phpunit.xml.dist
index 241af9023..6053fe1f5 100644
--- a/phpunit.xml.dist
+++ b/phpunit.xml.dist
@@ -75,6 +75,7 @@
         </testsuite>
         <testsuite name="Unit">
             <directory suffix="TestCase.php">tests/Unit</directory>
+            <directory suffix="Test.php">tests/Nexus/Unit</directory>
         </testsuite>
         <testsuite name="Functional">
             <directory suffix="TestCase.php">tests/Functional</directory>
diff --git a/psalm-baseline.xml b/psalm-baseline.xml
index 511fbe21a..90b879da8 100644
--- a/psalm-baseline.xml
+++ b/psalm-baseline.xml
@@ -31,11 +31,6 @@
     </ArgumentTypeCoercion>
   </file>
   <file src="src/Client/Schedule/Action/StartWorkflowAction.php">
-    <DocblockTypeContradiction>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-    </DocblockTypeContradiction>
     <InaccessibleProperty>
       <code><![CDATA[$workflowType->name]]></code>
     </InaccessibleProperty>
@@ -99,9 +94,6 @@
       <code><![CDATA[$this->excludeCalendarList]]></code>
       <code><![CDATA[$this->excludeCalendarList]]></code>
     </DeprecatedProperty>
-    <DocblockTypeContradiction>
-      <code><![CDATA[parse]]></code>
-    </DocblockTypeContradiction>
   </file>
   <file src="src/Client/ScheduleClient.php">
     <DeprecatedProperty>
@@ -255,11 +247,6 @@
       <code><![CDATA[getID]]></code>
     </PossiblyNullReference>
   </file>
-  <file src="src/Exception/Client/ServiceClientException.php">
-    <ImplementedReturnTypeMismatch>
-      <code><![CDATA[RepeatedField]]></code>
-    </ImplementedReturnTypeMismatch>
-  </file>
   <file src="src/Exception/Client/WorkflowException.php">
     <UnsafeInstantiation>
       <code><![CDATA[new static(null, $execution, $workflowType, $previous)]]></code>
@@ -444,9 +431,6 @@
     </PropertyNotSetInConstructor>
   </file>
   <file src="src/Internal/Declaration/Graph/ClassNode.php">
-    <ImplicitToStringCast>
-      <code><![CDATA[list<array{class-string, \ReflectionMethod}>]]></code>
-    </ImplicitToStringCast>
     <InvalidReturnType>
       <code><![CDATA[\Traversable<ClassNode>]]></code>
     </InvalidReturnType>
@@ -512,6 +496,12 @@
     </RedundantConditionGivenDocblockType>
     <UnnecessaryVarAnnotation>
       <code><![CDATA[\ReflectionMethod]]></code>
+      <code><![CDATA[\Traversable<ClassNode, \ReflectionMethod>]]></code>
+    </UnnecessaryVarAnnotation>
+  </file>
+  <file src="src/Internal/Declaration/Reader/NexusServiceReader.php">
+    <UnnecessaryVarAnnotation>
+      <code><![CDATA[\Traversable<ClassNode, \ReflectionMethod>]]></code>
     </UnnecessaryVarAnnotation>
   </file>
   <file src="src/Internal/Declaration/Reader/WorkflowReader.php">
@@ -530,7 +520,8 @@
       <code><![CDATA[$retry !== null]]></code>
     </RedundantConditionGivenDocblockType>
     <UnnecessaryVarAnnotation>
-      <code><![CDATA[\Traversable<class-string, \ReflectionMethod>]]></code>
+      <code><![CDATA[\Traversable<ClassNode, \ReflectionMethod>]]></code>
+      <code><![CDATA[\Traversable<ClassNode, \ReflectionMethod>]]></code>
     </UnnecessaryVarAnnotation>
   </file>
   <file src="src/Internal/Declaration/WorkflowInstance/QueryDispatcher.php">
@@ -582,18 +573,6 @@
       <code><![CDATA[setDataConverter]]></code>
     </UndefinedInterfaceMethod>
   </file>
-  <file src="src/Internal/Mapper/WorkflowExecutionConfigMapper.php">
-    <DocblockTypeContradiction>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-    </DocblockTypeContradiction>
-    <RedundantConditionGivenDocblockType>
-      <code><![CDATA[parse]]></code>
-    </RedundantConditionGivenDocblockType>
-  </file>
   <file src="src/Internal/Mapper/WorkflowExecutionInfoMapper.php">
     <ArgumentTypeCoercion>
       <code><![CDATA[$execution->getRunId()]]></code>
@@ -606,16 +585,6 @@
       <code><![CDATA[getBinaryChecksum]]></code>
       <code><![CDATA[getMostRecentWorkerVersionStamp]]></code>
     </DeprecatedMethod>
-    <DocblockTypeContradiction>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-    </DocblockTypeContradiction>
-    <RedundantConditionGivenDocblockType>
-      <code><![CDATA[parse]]></code>
-    </RedundantConditionGivenDocblockType>
   </file>
   <file src="src/Internal/Marshaller/Mapper/AttributeMapper.php">
     <MissingClosureParamType>
@@ -814,17 +783,7 @@
     </DeprecatedConstant>
     <RedundantCondition>
       <code><![CDATA[$nullEmpty && $seconds === 0 && $micros === 0]]></code>
-      <code><![CDATA[parse]]></code>
     </RedundantCondition>
-    <TypeDoesNotContainNull>
-      <code><![CDATA[parse]]></code>
-    </TypeDoesNotContainNull>
-    <TypeDoesNotContainType>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-      <code><![CDATA[parse]]></code>
-    </TypeDoesNotContainType>
   </file>
   <file src="src/Internal/Support/DateTime.php">
     <InvalidReturnStatement>
@@ -921,10 +880,6 @@
     </ArgumentTypeCoercion>
   </file>
   <file src="src/Internal/Transport/Router/StartWorkflow.php">
-    <PossiblyFalseArgument>
-      <code><![CDATA[\json_encode($param)]]></code>
-      <code><![CDATA[\json_encode($param)]]></code>
-    </PossiblyFalseArgument>
     <UnnecessaryVarAnnotation>
       <code><![CDATA[Input]]></code>
     </UnnecessaryVarAnnotation>
@@ -933,13 +888,6 @@
     <ArgumentTypeCoercion>
       <code><![CDATA[$e->getMessage()]]></code>
     </ArgumentTypeCoercion>
-    <InvalidArgument>
-      <code><![CDATA[$request]]></code>
-      <code><![CDATA[$request]]></code>
-    </InvalidArgument>
-    <MismatchingDocblockParamType>
-      <code><![CDATA[RequestInterface]]></code>
-    </MismatchingDocblockParamType>
   </file>
   <file src="src/Internal/Workflow/ActivityProxy.php">
     <ArgumentTypeCoercion>
@@ -1000,6 +948,17 @@
       <code><![CDATA[$header ?? Header::empty()]]></code>
     </PropertyTypeCoercion>
   </file>
+  <file src="src/Internal/Workflow/NexusOperationStub.php">
+    <ArgumentTypeCoercion>
+      <code><![CDATA[$endpoint]]></code>
+      <code><![CDATA[$service]]></code>
+    </ArgumentTypeCoercion>
+  </file>
+  <file src="src/Internal/Workflow/NexusServiceProxy.php">
+    <ArgumentTypeCoercion>
+      <code><![CDATA[$input->operation]]></code>
+    </ArgumentTypeCoercion>
+  </file>
   <file src="src/Internal/Workflow/Process/DeferredGenerator.php">
     <UnevaluatedCode>
       <code><![CDATA[yield;]]></code>
@@ -1057,6 +1016,7 @@
     <ArgumentTypeCoercion>
       <code><![CDATA[$input->maxSupported]]></code>
       <code><![CDATA[$input->minSupported]]></code>
+      <code><![CDATA[$input->operation]]></code>
       <code><![CDATA[$input->type]]></code>
       <code><![CDATA[$type]]></code>
       <code><![CDATA[$type]]></code>
@@ -1099,6 +1059,37 @@
       <code><![CDATA[$clone->trace = &$this->trace]]></code>
     </UnsupportedPropertyReferenceUsage>
   </file>
+  <file src="src/Nexus/Attribute/AsyncOperation.php">
+    <DeprecatedClass>
+      <code><![CDATA[NamedArgumentConstructor]]></code>
+    </DeprecatedClass>
+  </file>
+  <file src="src/Nexus/Attribute/Operation.php">
+    <DeprecatedClass>
+      <code><![CDATA[NamedArgumentConstructor]]></code>
+    </DeprecatedClass>
+  </file>
+  <file src="src/Nexus/Attribute/Service.php">
+    <DeprecatedClass>
+      <code><![CDATA[NamedArgumentConstructor]]></code>
+    </DeprecatedClass>
+  </file>
+  <file src="src/Nexus/Handler/Internal/WorkflowRunStarter.php">
+    <DeprecatedConstant>
+      <code><![CDATA[Header::OPERATION_ID]]></code>
+      <code><![CDATA[Header::OPERATION_ID]]></code>
+    </DeprecatedConstant>
+  </file>
+  <file src="src/Nexus/Handler/LinkCollection.php">
+    <RedundantFunctionCall>
+      <code><![CDATA[\array_values]]></code>
+    </RedundantFunctionCall>
+  </file>
+  <file src="src/Nexus/WorkflowRunOperation.php">
+    <ArgumentTypeCoercion>
+      <code><![CDATA[$decoded->workflowId]]></code>
+    </ArgumentTypeCoercion>
+  </file>
   <file src="src/Promise.php">
     <InvalidArgument>
       <code><![CDATA[$reasons]]></code>
@@ -1182,12 +1173,6 @@
     </PossiblyNullArgument>
   </file>
   <file src="src/Worker/Transport/Codec/ProtoCodec.php">
-    <LessSpecificReturnStatement>
-      <code><![CDATA[$frame->serializeToString()]]></code>
-    </LessSpecificReturnStatement>
-    <MoreSpecificReturnType>
-      <code><![CDATA[string]]></code>
-    </MoreSpecificReturnType>
     <PossiblyInvalidArgument>
       <code><![CDATA[$e->getCode()]]></code>
       <code><![CDATA[$e->getCode()]]></code>
@@ -1210,22 +1195,10 @@
     </PossiblyNullReference>
   </file>
   <file src="src/Worker/Transport/Codec/ProtoCodec/Encoder.php">
-    <PossiblyFalseArgument>
-      <code><![CDATA[\json_encode($cmd->getOptions(), JSON_INVALID_UTF8_IGNORE | JSON_UNESCAPED_UNICODE)]]></code>
-      <code><![CDATA[\json_encode($options)]]></code>
-    </PossiblyFalseArgument>
     <PossiblyNullArgument>
       <code><![CDATA[$cmd->getFailure()]]></code>
     </PossiblyNullArgument>
   </file>
-  <file src="src/Worker/Transport/Command/Client/FailedClientResponse.php">
-    <InvalidNullableReturnType>
-      <code><![CDATA[\Throwable]]></code>
-    </InvalidNullableReturnType>
-    <NullableReturnStatement>
-      <code><![CDATA[$this->failure]]></code>
-    </NullableReturnStatement>
-  </file>
   <file src="src/Worker/Transport/Command/Client/SuccessClientResponse.php">
     <InvalidNullableReturnType>
       <code><![CDATA[ValuesInterface]]></code>
@@ -1360,6 +1333,16 @@
       <code><![CDATA[getUpdateContext]]></code>
     </UndefinedInterfaceMethod>
   </file>
+  <file src="src/Workflow/NexusOperationOptions.php">
+    <ImpureMethodCall>
+      <code><![CDATA[assert]]></code>
+      <code><![CDATA[assert]]></code>
+      <code><![CDATA[assert]]></code>
+      <code><![CDATA[parse]]></code>
+      <code><![CDATA[parse]]></code>
+      <code><![CDATA[parse]]></code>
+    </ImpureMethodCall>
+  </file>
   <file src="src/Workflow/QueryMethod.php">
     <DeprecatedClass>
       <code><![CDATA[NamedArgumentConstructor]]></code>
@@ -1486,19 +1469,6 @@
       <code><![CDATA[$message->getHeader()]]></code>
       <code><![CDATA[$message->getPayloads()]]></code>
     </PossiblyNullArgument>
-    <TooManyTemplateParams>
-      <code><![CDATA[$fields]]></code>
-      <code><![CDATA[$meta]]></code>
-    </TooManyTemplateParams>
-  </file>
-  <file src="testing/src/Transcript/WorkflowHistoryDumper.php">
-    <InvalidOperand>
-      <code><![CDATA[$eventTime->getSeconds() + \round($eventTime->getNanos() / 1_000_000_000, 6)]]></code>
-      <code><![CDATA[($sec - $startSec) * 1000]]></code>
-    </InvalidOperand>
-    <PossiblyInvalidOperand>
-      <code><![CDATA[$eventTime->getSeconds()]]></code>
-    </PossiblyInvalidOperand>
   </file>
   <file src="testing/src/WorkerMock.php">
     <DeprecatedMethod>
diff --git a/psalm.xml b/psalm.xml
index ef14c51ce..9c160f6d4 100644
--- a/psalm.xml
+++ b/psalm.xml
@@ -22,6 +22,11 @@
             <directory name="vendor" />
         </ignoreFiles>
     </projectFiles>
+    <stubs>
+        <file name="stubs/GoogleProtobufRepeatedField.phpstub" />
+        <file name="stubs/GoogleProtobufMapField.phpstub" />
+        <file name="stubs/CarbonInterval.phpstub" />
+    </stubs>
     <issueHandlers>
         <MissingOverrideAttribute errorLevel="suppress" />
         <ClassMustBeFinal errorLevel="suppress" />
diff --git a/src/Client/WorkflowOptions.php b/src/Client/WorkflowOptions.php
index 5f483e77e..e0419e31b 100644
--- a/src/Client/WorkflowOptions.php
+++ b/src/Client/WorkflowOptions.php
@@ -31,10 +31,14 @@
 use Temporal\Internal\Marshaller\Type\CronType;
 use Temporal\Internal\Marshaller\Type\DateIntervalType;
 use Temporal\Internal\Marshaller\Type\NullableType;
+use Temporal\Internal\Nexus\NexusLinkConverter;
+use Temporal\Internal\Client\OnConflictOptions;
 use Temporal\Internal\Support\DateInterval;
 use Temporal\Internal\Support\Options;
+use Temporal\Nexus\Link as NexusLink;
 use Temporal\Worker\Worker;
 use Temporal\Worker\WorkerFactoryInterface;
+use Temporal\Workflow\CompletionCallback;
 
 /**
  * WorkflowOptions configuration parameters for starting a workflow execution.
@@ -189,6 +193,17 @@ final class WorkflowOptions extends Options
     #[Marshal(name: 'VersioningOverride')]
     public ?VersioningOverride $versioningOverride = null;
 
+    public ?string $requestId = null;
+
+    /** @var list<CompletionCallback> */
+    public array $completionCallbacks = [];
+
+    /** @internal */
+    public ?OnConflictOptions $onConflictOptions = null;
+
+    /** @var list<\Temporal\Api\Common\V1\Link> */
+    public array $links = [];
+
     /**
      * @throws \Exception
      */
@@ -606,4 +621,109 @@ public function withPriority(Priority $priority): self
         $self->priority = $priority;
         return $self;
     }
+
+    /**
+     * Pin gRPC `request_id`. `null` = fresh UUID per call.
+     *
+     * @return $this
+     */
+    #[Pure]
+    public function withRequestId(?string $requestId): self
+    {
+        $self = clone $this;
+        $self->requestId = $requestId;
+        return $self;
+    }
+
+    /**
+     * Append a Nexus completion callback. Use {@see self::withCompletionCallbacks()}
+     * with an empty argument list to clear.
+     *
+     * @param non-empty-string $url
+     * @param array<string, string> $headers
+     * @return $this
+     */
+    #[Pure]
+    public function withNexusCompletionCallback(string $url, array $headers = []): self
+    {
+        $self = clone $this;
+        $self->completionCallbacks = [...$this->completionCallbacks, new CompletionCallback($url, $headers)];
+        return $self;
+    }
+
+    /**
+     * Replace the full list of completion callbacks.
+     *
+     * @return $this
+     */
+    #[Pure]
+    public function withCompletionCallbacks(CompletionCallback ...$callbacks): self
+    {
+        $self = clone $this;
+        $self->completionCallbacks = \array_values($callbacks);
+        return $self;
+    }
+
+    /**
+     * @internal
+     * @return $this
+     */
+    #[Pure]
+    public function withOnConflictOptionsInternal(?OnConflictOptions $options): self
+    {
+        $self = clone $this;
+        $self->onConflictOptions = $options;
+        return $self;
+    }
+
+    /**
+     * Replace the link list with proto Link[] derived from Nexus-level URIs.
+     *
+     * @psalm-suppress ImpureMethodCall
+     *
+     * @param iterable<NexusLink> $nexusLinks
+     * @return $this
+     */
+    #[Pure]
+    public function withLinks(iterable $nexusLinks): self
+    {
+        $self = clone $this;
+        $self->links = NexusLinkConverter::toProtoLinks($nexusLinks);
+        return $self;
+    }
+
+    /**
+     * Snapshot of the DTO for `var_dump`/`print_r`/Xdebug pretty-printing.
+     *
+     * Renders {@see \DateInterval} fields as ISO 8601 spec strings (e.g.
+     * `PT60S`); the default dump expands them into nine zero components and
+     * buries the actual values.
+     */
+    public function __debugInfo(): array
+    {
+        return [
+            'workflowId' => $this->workflowId,
+            'taskQueue' => $this->taskQueue,
+            'eagerStart' => $this->eagerStart,
+            'workflowExecutionTimeout' => CarbonInterval::instance($this->workflowExecutionTimeout)->spec(),
+            'workflowRunTimeout' => CarbonInterval::instance($this->workflowRunTimeout)->spec(),
+            'workflowStartDelay' => CarbonInterval::instance($this->workflowStartDelay)->spec(),
+            'workflowTaskTimeout' => CarbonInterval::instance($this->workflowTaskTimeout)->spec(),
+            'workflowIdReusePolicy' => $this->workflowIdReusePolicy,
+            'workflowIdConflictPolicy' => $this->workflowIdConflictPolicy,
+            'retryOptions' => $this->retryOptions,
+            'cronSchedule' => $this->cronSchedule,
+            'memo' => $this->memo,
+            'searchAttributes' => $this->searchAttributes,
+            'typedSearchAttributes' => $this->typedSearchAttributes,
+            'staticDetails' => $this->staticDetails,
+            'staticSummary' => $this->staticSummary,
+            'priority' => $this->priority,
+            'versioningOverride' => $this->versioningOverride,
+            'requestId' => $this->requestId,
+            'completionCallbacks' => $this->completionCallbacks,
+            'onConflictOptions' => $this->onConflictOptions,
+            'links' => $this->links,
+        ];
+    }
 }
diff --git a/src/DataConverter/EncodedValues.php b/src/DataConverter/EncodedValues.php
index c94ca3219..0d32ebfe6 100644
--- a/src/DataConverter/EncodedValues.php
+++ b/src/DataConverter/EncodedValues.php
@@ -60,6 +60,24 @@ public static function fromPayloads(Payloads $payloads, DataConverterInterface $
         return static::fromPayloadCollection($payloads->getPayloads(), $dataConverter);
     }
 
+    public static function fromPayload(?Payload $payload, DataConverterInterface $dataConverter): EncodedValues
+    {
+        $payloads = new Payloads();
+        if ($payload !== null) {
+            $payloads->setPayloads([$payload]);
+        }
+        return static::fromPayloads($payloads, $dataConverter);
+    }
+
+    public static function firstPayload(ValuesInterface $values): ?Payload
+    {
+        $payloads = $values->toPayloads()->getPayloads();
+        if ($payloads->count() === 0) {
+            return null;
+        }
+        return $payloads[0];
+    }
+
     public static function sliceValues(
         DataConverterInterface $converter,
         ValuesInterface $values,
diff --git a/src/Exception/Client/MultyOperation/OperationStatus.php b/src/Exception/Client/MultyOperation/OperationStatus.php
index fea2e023e..8b191ccd1 100644
--- a/src/Exception/Client/MultyOperation/OperationStatus.php
+++ b/src/Exception/Client/MultyOperation/OperationStatus.php
@@ -17,7 +17,7 @@ final class OperationStatus
     use UnpackDetailsTrait;
 
     /**
-     * @param \ArrayAccess<int, Any>&RepeatedField $details
+     * @param RepeatedField<Any> $details
      */
     private function __construct(
         private readonly \Traversable $details,
@@ -35,7 +35,7 @@ public function getMessage(): string
     }
 
     /**
-     * @return \ArrayAccess<int, Any>&RepeatedField
+     * @return RepeatedField<Any>
      */
     private function getDetails(): \Traversable
     {
diff --git a/src/Exception/Client/ServiceClientException.php b/src/Exception/Client/ServiceClientException.php
index d92d81a10..fe54cd108 100644
--- a/src/Exception/Client/ServiceClientException.php
+++ b/src/Exception/Client/ServiceClientException.php
@@ -44,7 +44,7 @@ public function getStatus(): Status
     }
 
     /**
-     * @return RepeatedField
+     * @return RepeatedField<\Google\Protobuf\Any>
      */
     public function getDetails(): \ArrayAccess&\Countable&\IteratorAggregate
     {
diff --git a/src/Exception/Client/UnpackDetailsTrait.php b/src/Exception/Client/UnpackDetailsTrait.php
index 82449f4bb..ce79059b4 100644
--- a/src/Exception/Client/UnpackDetailsTrait.php
+++ b/src/Exception/Client/UnpackDetailsTrait.php
@@ -31,7 +31,6 @@ public function getFailure(string $class): ?object
         // ensures that message descriptor was added to the pool
         Message::initOnce();
 
-        /** @var Any $detail */
         foreach ($details as $detail) {
             if ($detail->is($class)) {
                 return $detail->unpack();
@@ -42,7 +41,7 @@ public function getFailure(string $class): ?object
     }
 
     /**
-     * @return \ArrayAccess<int, Any>&RepeatedField
+     * @return RepeatedField<Any>
      */
     abstract private function getDetails(): iterable;
 }
diff --git a/src/Exception/Failure/FailureConverter.php b/src/Exception/Failure/FailureConverter.php
index 646cef035..6c9b0ac9d 100644
--- a/src/Exception/Failure/FailureConverter.php
+++ b/src/Exception/Failure/FailureConverter.php
@@ -11,6 +11,10 @@
 
 namespace Temporal\Exception\Failure;
 
+use Temporal\Nexus\Exception\HandlerException as NexusHandlerException;
+use Temporal\Nexus\Exception\OperationException as NexusOperationException;
+use Temporal\Nexus\OperationState;
+use Temporal\Nexus\Internal\Failure\NexusFailureConverter;
 use Temporal\Api\Common\V1\ActivityType;
 use Temporal\Api\Common\V1\WorkflowExecution;
 use Temporal\Api\Common\V1\WorkflowType;
@@ -19,6 +23,8 @@
 use Temporal\Api\Failure\V1\CanceledFailureInfo;
 use Temporal\Api\Failure\V1\ChildWorkflowExecutionFailureInfo;
 use Temporal\Api\Failure\V1\Failure;
+use Temporal\Api\Failure\V1\NexusHandlerFailureInfo;
+use Temporal\Api\Failure\V1\NexusOperationFailureInfo;
 use Temporal\Api\Failure\V1\ServerFailureInfo;
 use Temporal\Api\Failure\V1\TerminatedFailureInfo;
 use Temporal\Api\Failure\V1\TimeoutFailureInfo;
@@ -29,6 +35,8 @@
 
 final class FailureConverter
 {
+    public const NEXUS_OPERATION_ERROR_TYPE = 'OperationError';
+
     public static function mapFailureToException(Failure $failure, DataConverterInterface $converter): TemporalFailure
     {
         $e = self::createFailureException($failure, $converter);
@@ -148,6 +156,48 @@ public static function mapExceptionToFailure(\Throwable $e, DataConverterInterfa
                 $failure->setCanceledFailureInfo(new CanceledFailureInfo());
                 break;
 
+            case $e instanceof NexusHandlerException:
+                $info = new NexusHandlerFailureInfo();
+                $info->setType($e->errorType->value);
+                $info->setRetryBehavior(NexusFailureConverter::mapRetryBehavior($e->retryBehavior));
+
+                $failure->setNexusHandlerFailureInfo($info);
+                break;
+
+            case $e instanceof NexusHandlerFailure:
+                $info = new NexusHandlerFailureInfo();
+                $info->setType($e->getType());
+                $info->setRetryBehavior($e->getRetryBehavior());
+
+                $failure->setNexusHandlerFailureInfo($info);
+                break;
+
+            case $e instanceof NexusOperationException && $e->state === OperationState::Canceled:
+                $failure->setCanceledFailureInfo(new CanceledFailureInfo());
+                break;
+
+            case $e instanceof NexusOperationException:
+                $info = new ApplicationFailureInfo();
+                $info->setType(self::NEXUS_OPERATION_ERROR_TYPE);
+                $info->setNonRetryable(true);
+
+                $failure->setApplicationFailureInfo($info);
+                break;
+
+            case $e instanceof NexusOperationFailure:
+                $info = new NexusOperationFailureInfo();
+                /** @psalm-suppress DeprecatedMethod */
+                $info
+                    ->setScheduledEventId($e->getScheduledEventId())
+                    ->setEndpoint($e->getEndpoint())
+                    ->setService($e->getService())
+                    ->setOperation($e->getOperation())
+                    ->setOperationId($e->getOperationToken())
+                    ->setOperationToken($e->getOperationToken());
+
+                $failure->setNexusOperationExecutionFailureInfo($info);
+                break;
+
             default:
                 $info = new ApplicationFailureInfo();
                 $info->setType($e::class);
@@ -261,6 +311,38 @@ private static function createFailureException(Failure $failure, DataConverterIn
                     $previous,
                 );
 
+            case $failure->hasNexusHandlerFailureInfo():
+                $info = $failure->getNexusHandlerFailureInfo();
+                \assert($info instanceof NexusHandlerFailureInfo);
+
+                return new NexusHandlerFailure(
+                    $failure->getMessage(),
+                    $info->getType(),
+                    $info->getRetryBehavior(),
+                    $previous,
+                );
+
+            case $failure->hasNexusOperationExecutionFailureInfo():
+                $info = $failure->getNexusOperationExecutionFailureInfo();
+                \assert($info instanceof NexusOperationFailureInfo);
+
+                // Fall back to deprecated operation_id for older servers.
+                $token = $info->getOperationToken();
+                if ($token === '') {
+                    /** @psalm-suppress DeprecatedMethod */
+                    $token = $info->getOperationId();
+                }
+
+                return new NexusOperationFailure(
+                    $failure->getMessage(),
+                    (int) $info->getScheduledEventId(),
+                    $info->getEndpoint(),
+                    $info->getService(),
+                    $info->getOperation(),
+                    $token,
+                    $previous,
+                );
+
             default:
                 throw new \InvalidArgumentException('Failure info not set');
         }
diff --git a/src/Exception/Failure/NexusHandlerFailure.php b/src/Exception/Failure/NexusHandlerFailure.php
new file mode 100644
index 000000000..485d27929
--- /dev/null
+++ b/src/Exception/Failure/NexusHandlerFailure.php
@@ -0,0 +1,62 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Exception\Failure;
+
+use Temporal\Api\Enums\V1\NexusHandlerErrorRetryBehavior;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\RetryBehavior;
+
+/**
+ * Transport-level Nexus HandlerError (`BAD_REQUEST`, `INTERNAL`, `NOT_FOUND`, etc.).
+ * Maps 1:1 to the `NexusHandlerException` thrown on the handler side.
+ */
+class NexusHandlerFailure extends TemporalFailure
+{
+    public function __construct(
+        string $message,
+        private readonly string $type,
+        private readonly int $retryBehavior,
+        ?\Throwable $previous = null,
+    ) {
+        parent::__construct($message, null, $previous);
+    }
+
+    /**
+     * Raw error-type string (e.g. `BAD_REQUEST`, or user-defined).
+     */
+    public function getType(): string
+    {
+        return $this->type;
+    }
+
+    /**
+     * {@see \Temporal\Api\Enums\V1\NexusHandlerErrorRetryBehavior} value.
+     */
+    public function getRetryBehavior(): int
+    {
+        return $this->retryBehavior;
+    }
+
+    public function getErrorType(): ErrorType
+    {
+        return ErrorType::tryFrom($this->type) ?? ErrorType::Unknown;
+    }
+
+    public function getRetryBehaviorEnum(): RetryBehavior
+    {
+        return match ($this->retryBehavior) {
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE => RetryBehavior::Retryable,
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE => RetryBehavior::NonRetryable,
+            default => RetryBehavior::Unspecified,
+        };
+    }
+}
diff --git a/src/Exception/Failure/NexusOperationFailure.php b/src/Exception/Failure/NexusOperationFailure.php
new file mode 100644
index 000000000..afac4faea
--- /dev/null
+++ b/src/Exception/Failure/NexusOperationFailure.php
@@ -0,0 +1,70 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Exception\Failure;
+
+/**
+ * Workflow-side failure for a Nexus operation invoked via
+ * {@see \Temporal\Workflow::executeNexusOperation()}.
+ * `$previous` carries the cause as a {@see TemporalFailure}.
+ */
+class NexusOperationFailure extends TemporalFailure
+{
+    public function __construct(
+        string $message,
+        private readonly int $scheduledEventId,
+        private readonly string $endpoint,
+        private readonly string $service,
+        private readonly string $operation,
+        private readonly string $operationToken,
+        ?\Throwable $previous = null,
+    ) {
+        parent::__construct(
+            self::buildMessage([
+                'endpoint' => $endpoint,
+                'service' => $service,
+                'operation' => $operation,
+                'operationToken' => $operationToken,
+                'scheduledEventId' => $scheduledEventId,
+            ]),
+            $message,
+            $previous,
+        );
+    }
+
+    public function getScheduledEventId(): int
+    {
+        return $this->scheduledEventId;
+    }
+
+    public function getEndpoint(): string
+    {
+        return $this->endpoint;
+    }
+
+    public function getService(): string
+    {
+        return $this->service;
+    }
+
+    public function getOperation(): string
+    {
+        return $this->operation;
+    }
+
+    /**
+     * Async operation token issued by the handler — empty for sync operations.
+     */
+    public function getOperationToken(): string
+    {
+        return $this->operationToken;
+    }
+}
diff --git a/src/Interceptor/NexusOperationInbound/CancelOperationInput.php b/src/Interceptor/NexusOperationInbound/CancelOperationInput.php
new file mode 100644
index 000000000..6b08d9a10
--- /dev/null
+++ b/src/Interceptor/NexusOperationInbound/CancelOperationInput.php
@@ -0,0 +1,40 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Interceptor\NexusOperationInbound;
+
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+
+/**
+ * @psalm-immutable
+ */
+final class CancelOperationInput
+{
+    /**
+     * @no-named-arguments
+     * @internal Don't use the constructor. Use {@see self::with()} instead.
+     */
+    public function __construct(
+        public readonly OperationContext $operationContext,
+        public readonly OperationCancelDetails $cancelDetails,
+    ) {}
+
+    public function with(
+        ?OperationContext $operationContext = null,
+        ?OperationCancelDetails $cancelDetails = null,
+    ): self {
+        return new self(
+            $operationContext ?? $this->operationContext,
+            $cancelDetails ?? $this->cancelDetails,
+        );
+    }
+}
diff --git a/src/Interceptor/NexusOperationInbound/StartOperationInput.php b/src/Interceptor/NexusOperationInbound/StartOperationInput.php
new file mode 100644
index 000000000..0100cf202
--- /dev/null
+++ b/src/Interceptor/NexusOperationInbound/StartOperationInput.php
@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Interceptor\NexusOperationInbound;
+
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationStartDetails;
+
+/**
+ * @psalm-immutable
+ */
+final class StartOperationInput
+{
+    private const UNSET = "\0__temporal_unset__\0";
+
+    /**
+     * @no-named-arguments
+     * @internal Don't use the constructor. Use {@see self::with()} instead.
+     */
+    public function __construct(
+        public readonly OperationContext $operationContext,
+        public readonly OperationStartDetails $startDetails,
+        public readonly mixed $input,
+    ) {}
+
+    public function with(
+        ?OperationContext $operationContext = null,
+        ?OperationStartDetails $startDetails = null,
+        mixed $input = self::UNSET,
+    ): self {
+        return new self(
+            $operationContext ?? $this->operationContext,
+            $startDetails ?? $this->startDetails,
+            $input === self::UNSET ? $this->input : $input,
+        );
+    }
+}
diff --git a/src/Interceptor/NexusOperationInboundCallsInterceptor.php b/src/Interceptor/NexusOperationInboundCallsInterceptor.php
new file mode 100644
index 000000000..b75509030
--- /dev/null
+++ b/src/Interceptor/NexusOperationInboundCallsInterceptor.php
@@ -0,0 +1,53 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Interceptor;
+
+use Temporal\Interceptor\NexusOperationInbound\CancelOperationInput;
+use Temporal\Interceptor\NexusOperationInbound\StartOperationInput;
+use Temporal\Interceptor\Trait\NexusOperationInboundCallsInterceptorTrait;
+use Temporal\Internal\Interceptor\Interceptor;
+use Temporal\Nexus\Handler\OperationStartResult;
+
+/**
+ * It's recommended to use `NexusOperationInboundCallsInterceptorTrait` when implementing this interface
+ * because the interface might be extended in the future. The trait will provide forward compatibility.
+ *
+ * ```php
+ * class MyNexusOperationInboundCallsInterceptor implements NexusOperationInboundCallsInterceptor
+ * {
+ *     use NexusOperationInboundCallsInterceptorTrait;
+ *
+ *     public function startOperation(StartOperationInput $input, callable $next): OperationStartResult
+ *     {
+ *         if ($input->operationContext->headers->get('authorization') !== 'expected-token') {
+ *             throw HandlerException::create(ErrorType::Unauthorized, 'Unauthorized');
+ *         }
+ *
+ *         return $next($input);
+ *     }
+ * }
+ * ```
+ *
+ * @see NexusOperationInboundCallsInterceptorTrait
+ */
+interface NexusOperationInboundCallsInterceptor extends Interceptor
+{
+    /**
+     * @param callable(StartOperationInput): OperationStartResult $next
+     */
+    public function startOperation(StartOperationInput $input, callable $next): OperationStartResult;
+
+    /**
+     * @param callable(CancelOperationInput): void $next
+     */
+    public function cancelOperation(CancelOperationInput $input, callable $next): void;
+}
diff --git a/src/Interceptor/NexusOperationOutbound/GetInfoInput.php b/src/Interceptor/NexusOperationOutbound/GetInfoInput.php
new file mode 100644
index 000000000..2337371d6
--- /dev/null
+++ b/src/Interceptor/NexusOperationOutbound/GetInfoInput.php
@@ -0,0 +1,24 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Interceptor\NexusOperationOutbound;
+
+/**
+ * @psalm-immutable
+ */
+final class GetInfoInput
+{
+    /**
+     * @no-named-arguments
+     * @internal Don't use the constructor.
+     */
+    public function __construct() {}
+}
diff --git a/src/Interceptor/NexusOperationOutboundCallsInterceptor.php b/src/Interceptor/NexusOperationOutboundCallsInterceptor.php
new file mode 100644
index 000000000..1ce1186b1
--- /dev/null
+++ b/src/Interceptor/NexusOperationOutboundCallsInterceptor.php
@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Interceptor;
+
+use Temporal\Interceptor\NexusOperationOutbound\GetInfoInput;
+use Temporal\Interceptor\Trait\NexusOperationOutboundCallsInterceptorTrait;
+use Temporal\Internal\Interceptor\Interceptor;
+use Temporal\Nexus\NexusOperationContext;
+
+/**
+ * It's recommended to use `NexusOperationOutboundCallsInterceptorTrait` when implementing this
+ * interface because the interface might be extended in the future. The trait will provide forward
+ * compatibility.
+ *
+ * ```php
+ * class MyNexusOperationOutboundCallsInterceptor implements NexusOperationOutboundCallsInterceptor
+ * {
+ *     use NexusOperationOutboundCallsInterceptorTrait;
+ *
+ *     public function getInfo(GetInfoInput $input, callable $next): NexusOperationContext
+ *     {
+ *         $info = $next($input);
+ *
+ *         return $info;
+ *     }
+ * }
+ * ```
+ *
+ * @see NexusOperationOutboundCallsInterceptorTrait
+ */
+interface NexusOperationOutboundCallsInterceptor extends Interceptor
+{
+    /**
+     * Intercepts the call to read the Nexus operation info ({@see \Temporal\Nexus\Nexus::getOperationContext()}).
+     *
+     * @param callable(GetInfoInput): NexusOperationContext $next
+     */
+    public function getInfo(GetInfoInput $input, callable $next): NexusOperationContext;
+}
diff --git a/src/Interceptor/Trait/NexusOperationInboundCallsInterceptorTrait.php b/src/Interceptor/Trait/NexusOperationInboundCallsInterceptorTrait.php
new file mode 100644
index 000000000..b5d181c57
--- /dev/null
+++ b/src/Interceptor/Trait/NexusOperationInboundCallsInterceptorTrait.php
@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Interceptor\Trait;
+
+use Temporal\Interceptor\NexusOperationInbound\CancelOperationInput;
+use Temporal\Interceptor\NexusOperationInbound\StartOperationInput;
+use Temporal\Interceptor\NexusOperationInboundCallsInterceptor;
+use Temporal\Nexus\Handler\OperationStartResult;
+
+/**
+ * Trait that provides a default interceptor implementation.
+ *
+ * @see NexusOperationInboundCallsInterceptor
+ *
+ * @psalm-require-implements NexusOperationInboundCallsInterceptor
+ */
+trait NexusOperationInboundCallsInterceptorTrait
+{
+    /**
+     * Default implementation of the `startOperation` method.
+     *
+     * @see NexusOperationInboundCallsInterceptor::startOperation()
+     */
+    public function startOperation(StartOperationInput $input, callable $next): OperationStartResult
+    {
+        return $next($input);
+    }
+
+    /**
+     * Default implementation of the `cancelOperation` method.
+     *
+     * @see NexusOperationInboundCallsInterceptor::cancelOperation()
+     */
+    public function cancelOperation(CancelOperationInput $input, callable $next): void
+    {
+        $next($input);
+    }
+}
diff --git a/src/Interceptor/Trait/NexusOperationOutboundCallsInterceptorTrait.php b/src/Interceptor/Trait/NexusOperationOutboundCallsInterceptorTrait.php
new file mode 100644
index 000000000..8f4acbce8
--- /dev/null
+++ b/src/Interceptor/Trait/NexusOperationOutboundCallsInterceptorTrait.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Interceptor\Trait;
+
+use Temporal\Interceptor\NexusOperationOutbound\GetInfoInput;
+use Temporal\Interceptor\NexusOperationOutboundCallsInterceptor;
+use Temporal\Nexus\NexusOperationContext;
+
+/**
+ * Trait that provides a default interceptor implementation.
+ *
+ * @see NexusOperationOutboundCallsInterceptor
+ *
+ * @psalm-require-implements NexusOperationOutboundCallsInterceptor
+ */
+trait NexusOperationOutboundCallsInterceptorTrait
+{
+    /**
+     * Default implementation of the `getInfo` method.
+     *
+     * @see NexusOperationOutboundCallsInterceptor::getInfo()
+     */
+    public function getInfo(GetInfoInput $input, callable $next): NexusOperationContext
+    {
+        return $next($input);
+    }
+}
diff --git a/src/Interceptor/Trait/WorkflowOutboundCallsInterceptorTrait.php b/src/Interceptor/Trait/WorkflowOutboundCallsInterceptorTrait.php
index 1fdeb8a0d..33d92281c 100644
--- a/src/Interceptor/Trait/WorkflowOutboundCallsInterceptorTrait.php
+++ b/src/Interceptor/Trait/WorkflowOutboundCallsInterceptorTrait.php
@@ -20,6 +20,7 @@
 use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteActivityInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteChildWorkflowInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteLocalActivityInput;
+use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteNexusOperationInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\GetVersionInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\PanicInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\SideEffectInput;
@@ -200,4 +201,14 @@ public function awaitWithTimeout(AwaitWithTimeoutInput $input, callable $next):
     {
         return $next($input);
     }
+
+    /**
+     * Default implementation of the `executeNexusOperation` method.
+     *
+     * @see WorkflowOutboundCallsInterceptor::executeNexusOperation()
+     */
+    public function executeNexusOperation(ExecuteNexusOperationInput $input, callable $next): PromiseInterface
+    {
+        return $next($input);
+    }
 }
diff --git a/src/Interceptor/WorkflowOutboundCalls/ExecuteNexusOperationInput.php b/src/Interceptor/WorkflowOutboundCalls/ExecuteNexusOperationInput.php
new file mode 100644
index 000000000..827ef12bc
--- /dev/null
+++ b/src/Interceptor/WorkflowOutboundCalls/ExecuteNexusOperationInput.php
@@ -0,0 +1,71 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Interceptor\WorkflowOutboundCalls;
+
+use Temporal\DataConverter\Type;
+use Temporal\Workflow\NexusOperationOptions;
+
+/**
+ * @psalm-immutable
+ */
+final class ExecuteNexusOperationInput
+{
+    /**
+     * @param array<string, string> $nexusHeaders raw-string headers forwarded
+     *        on the Nexus operation wire (separate from the Temporal `Header`
+     *        that carries payload-typed values).
+     *
+     * @no-named-arguments
+     * @internal Don't use the constructor. Use {@see self::with()} instead.
+     */
+    public function __construct(
+        public readonly string $endpoint,
+        public readonly string $service,
+        public readonly string $operation,
+        public readonly array $args,
+        public readonly NexusOperationOptions $options,
+        public readonly null|Type|string|\ReflectionClass|\ReflectionType $returnType,
+        public readonly array $nexusHeaders = [],
+    ) {}
+
+    public function effectiveOptions(): NexusOperationOptions
+    {
+        $options = $this->options;
+        if ($this->endpoint !== '' && $this->endpoint !== $options->endpoint) {
+            $options = $options->withEndpoint($this->endpoint);
+        }
+        if ($this->service !== '' && $this->service !== $options->service) {
+            $options = $options->withService($this->service);
+        }
+        return $options;
+    }
+
+    public function with(
+        ?string $endpoint = null,
+        ?string $service = null,
+        ?string $operation = null,
+        ?array $args = null,
+        ?NexusOperationOptions $options = null,
+        null|Type|string|\ReflectionClass|\ReflectionType $returnType = null,
+        ?array $nexusHeaders = null,
+    ): self {
+        return new self(
+            $endpoint ?? $this->endpoint,
+            $service ?? $this->service,
+            $operation ?? $this->operation,
+            $args ?? $this->args,
+            $options ?? $this->options,
+            $returnType ?? $this->returnType,
+            $nexusHeaders ?? $this->nexusHeaders,
+        );
+    }
+}
diff --git a/src/Interceptor/WorkflowOutboundCalls/TimerInput.php b/src/Interceptor/WorkflowOutboundCalls/TimerInput.php
index 5a72cb9e5..8b8ef3b0e 100644
--- a/src/Interceptor/WorkflowOutboundCalls/TimerInput.php
+++ b/src/Interceptor/WorkflowOutboundCalls/TimerInput.php
@@ -24,7 +24,6 @@ final class TimerInput
      */
     public function __construct(
         public readonly \DateInterval $interval,
-
         public readonly ?TimerOptions $timerOptions,
     ) {}
 
diff --git a/src/Interceptor/WorkflowOutboundCallsInterceptor.php b/src/Interceptor/WorkflowOutboundCallsInterceptor.php
index 620f1a4f8..8c72edecc 100644
--- a/src/Interceptor/WorkflowOutboundCallsInterceptor.php
+++ b/src/Interceptor/WorkflowOutboundCallsInterceptor.php
@@ -21,6 +21,7 @@
 use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteActivityInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteChildWorkflowInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteLocalActivityInput;
+use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteNexusOperationInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\GetVersionInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\PanicInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\SideEffectInput;
@@ -141,4 +142,9 @@ public function await(AwaitInput $input, callable $next): PromiseInterface;
      * @param callable(AwaitWithTimeoutInput): PromiseInterface $next
      */
     public function awaitWithTimeout(AwaitWithTimeoutInput $input, callable $next): PromiseInterface;
+
+    /**
+     * @param callable(ExecuteNexusOperationInput): PromiseInterface $next
+     */
+    public function executeNexusOperation(ExecuteNexusOperationInput $input, callable $next): PromiseInterface;
 }
diff --git a/src/Internal/Client/OnConflictOptions.php b/src/Internal/Client/OnConflictOptions.php
new file mode 100644
index 000000000..25ec82d5a
--- /dev/null
+++ b/src/Internal/Client/OnConflictOptions.php
@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Client;
+
+/**
+ * Workflow-id conflict policy options: what to attach to the existing run when
+ * a start request conflicts. Serialized to {@see \Temporal\Api\Workflow\V1\OnConflictOptions}.
+ *
+ * @internal
+ * @psalm-immutable
+ */
+final class OnConflictOptions
+{
+    public function __construct(
+        public readonly bool $attachRequestId = true,
+        public readonly bool $attachCompletionCallbacks = true,
+        public readonly bool $attachLinks = true,
+    ) {}
+}
diff --git a/src/Internal/Client/WorkflowStarter.php b/src/Internal/Client/WorkflowStarter.php
index 10131b91c..229ffc480 100644
--- a/src/Internal/Client/WorkflowStarter.php
+++ b/src/Internal/Client/WorkflowStarter.php
@@ -11,7 +11,10 @@
 
 namespace Temporal\Internal\Client;
 
+use Temporal\Api\Common\V1\Callback;
+use Temporal\Api\Common\V1\Callback\Nexus as NexusCallback;
 use Temporal\Api\Common\V1\WorkflowType;
+use Temporal\Api\Workflow\V1\OnConflictOptions as OnConflictOptionsProto;
 use Temporal\Api\Deployment\V1\WorkerDeploymentVersion;
 use Temporal\Api\Errordetails\V1\MultiOperationExecutionFailure;
 use Temporal\Api\Errordetails\V1\WorkflowExecutionAlreadyStartedFailure;
@@ -49,6 +52,7 @@
 use Temporal\Interceptor\WorkflowClientCallsInterceptor;
 use Temporal\Internal\Interceptor\Pipeline;
 use Temporal\Internal\Support\DateInterval;
+use Temporal\Workflow\CompletionCallback;
 use Temporal\Workflow\WorkflowExecution;
 
 /**
@@ -276,6 +280,31 @@ function (UpdateWithStartInput $input): UpdateWithStartOutput {
         );
     }
 
+    private static function completionCallbackToProto(CompletionCallback $callback): Callback
+    {
+        $nexus = new NexusCallback();
+        $nexus->setUrl($callback->url);
+        if ($callback->headers !== []) {
+            $nexus->setHeader($callback->headers);
+        }
+
+        $proto = new Callback();
+        $proto->setNexus($nexus);
+        if ($callback->links !== []) {
+            $proto->setLinks($callback->links);
+        }
+        return $proto;
+    }
+
+    private static function onConflictOptionsToProto(OnConflictOptions $options): OnConflictOptionsProto
+    {
+        $proto = new OnConflictOptionsProto();
+        $proto->setAttachRequestId($options->attachRequestId);
+        $proto->setAttachCompletionCallbacks($options->attachCompletionCallbacks);
+        $proto->setAttachLinks($options->attachLinks);
+        return $proto;
+    }
+
     /**
      * @param StartWorkflowExecutionRequest|SignalWithStartWorkflowExecutionRequest $request
      *        use {@see configureExecutionRequest()} to prepare request
@@ -324,7 +353,7 @@ private function configureExecutionRequest(
     ): StartWorkflowExecutionRequest|SignalWithStartWorkflowExecutionRequest {
         $options = $input->options;
 
-        $req->setRequestId(Uuid::v4())
+        $req->setRequestId($options->requestId ?? Uuid::v4())
             ->setIdentity($this->clientOptions->identity)
             ->setNamespace($this->clientOptions->namespace)
             ->setTaskQueue(new TaskQueue(['name' => $options->taskQueue]))
@@ -395,6 +424,21 @@ private function configureExecutionRequest(
 
         if ($req instanceof StartWorkflowExecutionRequest) {
             $req->setRequestEagerExecution($options->eagerStart);
+
+            // SignalWithStart's proto has no completion_callbacks / on_conflict_options field — start path only.
+            if ($options->completionCallbacks !== []) {
+                $req->setCompletionCallbacks(
+                    \array_map(self::completionCallbackToProto(...), $options->completionCallbacks),
+                );
+            }
+
+            if ($options->onConflictOptions !== null) {
+                $req->setOnConflictOptions(self::onConflictOptionsToProto($options->onConflictOptions));
+            }
+
+            if ($options->links !== []) {
+                $req->setLinks($options->links);
+            }
         }
 
         if (!$input->arguments->isEmpty()) {
diff --git a/src/Internal/Declaration/Graph/ClassNode.php b/src/Internal/Declaration/Graph/ClassNode.php
index 996b894bc..2d59fe5a8 100644
--- a/src/Internal/Declaration/Graph/ClassNode.php
+++ b/src/Internal/Declaration/Graph/ClassNode.php
@@ -58,7 +58,7 @@ public function count(): int
      * Get a method with all the declared classes.
      *
      * @param non-empty-string $name
-     * @return \Traversable<int, \Traversable<class-string, \ReflectionMethod>>
+     * @return \Traversable<int, \Traversable<ClassNode, \ReflectionMethod>>
      * @throws \ReflectionException
      */
     public function getMethods(string $name, bool $reverse = true): \Traversable
@@ -190,7 +190,7 @@ private function getInheritance(): array
 
     /**
      * @param iterable<ClassNode> $classes
-     * @return list<array{class-string, \ReflectionMethod}>
+     * @return list<array{ClassNode, \ReflectionMethod}>
      * @throws \ReflectionException
      */
     private function boxMethods(iterable $classes, string $name): array
@@ -207,8 +207,8 @@ private function boxMethods(iterable $classes, string $name): array
     }
 
     /**
-     * @param array<array{class-string, \ReflectionMethod}> $boxed
-     * @return \Traversable<class-string, \ReflectionMethod>
+     * @param array<array{ClassNode, \ReflectionMethod}> $boxed
+     * @return \Traversable<ClassNode, \ReflectionMethod>
      */
     private function unboxMethods(array $boxed): \Traversable
     {
diff --git a/src/Internal/Declaration/Instantiator/NexusServiceInstantiator.php b/src/Internal/Declaration/Instantiator/NexusServiceInstantiator.php
new file mode 100644
index 000000000..a801dd75d
--- /dev/null
+++ b/src/Internal/Declaration/Instantiator/NexusServiceInstantiator.php
@@ -0,0 +1,114 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Declaration\Instantiator;
+
+use Temporal\Internal\Declaration\NexusServiceInstance;
+use Temporal\Internal\Declaration\Prototype\NexusServicePrototype;
+use Temporal\Internal\Declaration\Reader\NexusServiceReader;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Exception\NexusException;
+use Temporal\Nexus\Handler\Internal\MethodOperationHandler;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+
+/**
+ * Binds a {@see NexusServicePrototype} to its implementation and builds the
+ * per-operation handler map keyed by wire operation name.
+ */
+final class NexusServiceInstantiator
+{
+    public function instantiate(NexusServicePrototype $prototype): NexusServiceInstance
+    {
+        $instance = $this->resolveInstance($prototype);
+        $handlers = $this->buildOperationHandlers($prototype, $instance);
+
+        return new NexusServiceInstance($prototype, $handlers);
+    }
+
+    private function resolveInstance(NexusServicePrototype $prototype): object
+    {
+        $factory = $prototype->getFactory();
+        if ($factory !== null) {
+            $instance = $factory();
+            if (!\is_object($instance)) {
+                throw new InvalidArgumentException(\sprintf(
+                    'Nexus service factory for "%s" must return an object, got %s',
+                    $prototype->getID(),
+                    \get_debug_type($instance),
+                ));
+            }
+            return $instance;
+        }
+
+        $reflection = $prototype->getClass();
+        if (!$reflection->isInstantiable() || $reflection->getConstructor()?->getNumberOfRequiredParameters() > 0) {
+            throw new NexusException(\sprintf(
+                'Service implementation for "%s" cannot be instantiated without arguments — bind via withInstance() or withFactory()',
+                $prototype->getID(),
+            ));
+        }
+
+        return $reflection->newInstance();
+    }
+
+    /**
+     * @return array<string, OperationHandlerInterface>
+     */
+    private function buildOperationHandlers(NexusServicePrototype $prototype, object $instance): array
+    {
+        $handlers = [];
+        $reflection = new \ReflectionClass($instance);
+
+        foreach ($prototype->getOperations() as $operation) {
+            try {
+                $startMethod = $reflection->getMethod($operation->methodName);
+            } catch (\ReflectionException $e) {
+                throw new NexusException(\sprintf(
+                    'Service implementation %s is missing method %s() for operation "%s"',
+                    $reflection->getName(),
+                    $operation->methodName,
+                    $operation->name,
+                ), 0, $e);
+            }
+
+            if (!$startMethod->isPublic() || $startMethod->isStatic() || $startMethod->isAbstract()) {
+                throw new NexusException(\sprintf(
+                    'Operation method %s::%s() must be public and non-static',
+                    $reflection->getName(),
+                    $operation->methodName,
+                ));
+            }
+
+            if (NexusServiceReader::returnsOperationHandler($startMethod)) {
+                $handler = $startMethod->invoke($instance);
+                if (!$handler instanceof OperationHandlerInterface) {
+                    throw new NexusException(\sprintf(
+                        'Operation handler factory %s::%s() must return an %s instance, got %s',
+                        $reflection->getName(),
+                        $operation->methodName,
+                        OperationHandlerInterface::class,
+                        \get_debug_type($handler),
+                    ));
+                }
+                $handlers[$operation->name] = $handler;
+                continue;
+            }
+
+            $handlers[$operation->name] = new MethodOperationHandler(
+                instance: $instance,
+                startMethod: $startMethod,
+                operation: $operation,
+            );
+        }
+
+        return $handlers;
+    }
+}
diff --git a/src/Internal/Declaration/NexusServiceInstance.php b/src/Internal/Declaration/NexusServiceInstance.php
new file mode 100644
index 000000000..532cfc9ec
--- /dev/null
+++ b/src/Internal/Declaration/NexusServiceInstance.php
@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Declaration;
+
+use Temporal\Internal\Declaration\Prototype\NexusServicePrototype;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+
+/**
+ * Live binding of a {@see NexusServicePrototype} to its implementation,
+ * with per-operation handlers keyed by wire operation name.
+ */
+final class NexusServiceInstance
+{
+    /**
+     * @param array<string, OperationHandlerInterface> $operationHandlers Keyed by wire operation name.
+     */
+    public function __construct(
+        public readonly NexusServicePrototype $prototype,
+        public readonly array $operationHandlers,
+    ) {}
+}
diff --git a/src/Internal/Declaration/Prototype/NexusOperationPrototype.php b/src/Internal/Declaration/Prototype/NexusOperationPrototype.php
new file mode 100644
index 000000000..e30aca3eb
--- /dev/null
+++ b/src/Internal/Declaration/Prototype/NexusOperationPrototype.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Declaration\Prototype;
+
+use Temporal\DataConverter\Type;
+use Temporal\Nexus\Validation\OperationNameValidator;
+
+/**
+ * Storage DTO for a Nexus operation declaration built by {@see \Temporal\Internal\Declaration\Reader\NexusServiceReader}.
+ */
+final class NexusOperationPrototype
+{
+    /**
+     * @param non-empty-string $name Wire-level operation name.
+     * @param non-empty-string $methodName PHP method name on the contract.
+     */
+    public function __construct(
+        public readonly string $name,
+        public readonly string $methodName,
+        public readonly Type $inputType,
+        public readonly Type $outputType,
+        public readonly bool $async,
+        public readonly \ReflectionMethod $handler,
+    ) {
+        OperationNameValidator::assert($name);
+    }
+}
diff --git a/src/Internal/Declaration/Prototype/NexusServiceCollection.php b/src/Internal/Declaration/Prototype/NexusServiceCollection.php
new file mode 100644
index 000000000..7bcc40a20
--- /dev/null
+++ b/src/Internal/Declaration/Prototype/NexusServiceCollection.php
@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Declaration\Prototype;
+
+use Temporal\Internal\Repository\ArrayRepository;
+
+/**
+ * @template-extends ArrayRepository<NexusServicePrototype>
+ */
+final class NexusServiceCollection extends ArrayRepository {}
diff --git a/src/Internal/Declaration/Prototype/NexusServicePrototype.php b/src/Internal/Declaration/Prototype/NexusServicePrototype.php
new file mode 100644
index 000000000..458d95627
--- /dev/null
+++ b/src/Internal/Declaration/Prototype/NexusServicePrototype.php
@@ -0,0 +1,69 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Declaration\Prototype;
+
+use Temporal\Nexus\Validation\ServiceNameValidator;
+
+/**
+ * Storage DTO for a `#[Service]`-annotated Nexus contract; same shape as {@see ActivityPrototype}.
+ */
+final class NexusServicePrototype extends Prototype
+{
+    /** @var array<string, NexusOperationPrototype> Keyed by wire operation name. */
+    private readonly array $operations;
+
+    private ?\Closure $factory = null;
+
+    /**
+     * @param non-empty-string $name Wire-level service name.
+     * @param array<string, NexusOperationPrototype> $operations
+     */
+    public function __construct(
+        string $name,
+        array $operations,
+        \ReflectionClass $class,
+    ) {
+        ServiceNameValidator::assert($name);
+        parent::__construct($name, null, $class);
+        $this->operations = $operations;
+    }
+
+    /**
+     * @return array<string, NexusOperationPrototype>
+     */
+    public function getOperations(): array
+    {
+        return $this->operations;
+    }
+
+    public function getFactory(): ?\Closure
+    {
+        return $this->factory;
+    }
+
+    /**
+     * Bind the given object as the service implementation. Equivalent to
+     * `withFactory(static fn() => $instance)` — same shape as
+     * {@see ActivityPrototype::withInstance()}.
+     */
+    public function withInstance(object $instance): self
+    {
+        return $this->withFactory(static fn(): object => $instance);
+    }
+
+    public function withFactory(\Closure $factory): self
+    {
+        $proto = clone $this;
+        $proto->factory = $factory;
+        return $proto;
+    }
+}
diff --git a/src/Internal/Declaration/Reader/ActivityReader.php b/src/Internal/Declaration/Reader/ActivityReader.php
index c97c22a4c..5b00fed67 100644
--- a/src/Internal/Declaration/Reader/ActivityReader.php
+++ b/src/Internal/Declaration/Reader/ActivityReader.php
@@ -96,7 +96,7 @@ private function getMethodGroups(ClassNode $graph, \ReflectionMethod $root): arr
             // Each group of methods means one level of hierarchy in the
             // inheritance graph.
             //
-            /** @var ClassNode $ctx */
+            /** @var \Traversable<ClassNode, \ReflectionMethod> $group */
             foreach ($group as $ctx => $method) {
                 /** @var MethodRetry $retry */
                 $retry = $this->reader->firstFunctionMetadata($method, MethodRetry::class);
diff --git a/src/Internal/Declaration/Reader/NexusServiceReader.php b/src/Internal/Declaration/Reader/NexusServiceReader.php
new file mode 100644
index 000000000..73f2e7c25
--- /dev/null
+++ b/src/Internal/Declaration/Reader/NexusServiceReader.php
@@ -0,0 +1,298 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Declaration\Reader;
+
+use Temporal\DataConverter\Type;
+use Temporal\Internal\Declaration\Graph\ClassNode;
+use Temporal\Internal\Declaration\Prototype\NexusOperationPrototype;
+use Temporal\Internal\Declaration\Prototype\NexusServicePrototype;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\WorkflowHandle;
+
+/**
+ * Reflection-driven discovery of `#[Service]` contracts producing a {@see NexusServicePrototype}.
+ *
+ * @template-extends Reader<NexusServicePrototype>
+ */
+class NexusServiceReader extends Reader
+{
+    /**
+     * @internal
+     */
+    public static function returnsOperationHandler(\ReflectionMethod $method): bool
+    {
+        $returnType = $method->getReturnType();
+
+        return $returnType instanceof \ReflectionNamedType
+            && !$returnType->allowsNull()
+            && !$returnType->isBuiltin()
+            && \is_a($returnType->getName(), OperationHandlerInterface::class, true);
+    }
+
+    /**
+     * @param class-string $class
+     */
+    public function fromClass(string $class): NexusServicePrototype
+    {
+        $reflection = new \ReflectionClass($class);
+        $graph = new ClassNode($reflection);
+
+        $serviceNodes = $this->serviceNodes($graph);
+        $contract = $this->resolveContract($reflection, $serviceNodes);
+
+        $service = $this->reader->firstClassMetadata($contract, Service::class);
+        \assert($service !== null);
+        $name = $service->name !== '' ? $service->name : $contract->getShortName();
+
+        $this->assertServiceNamesMatch($serviceNodes, $contract, $name);
+
+        $operations = $this->collectOperations($graph);
+
+        return new NexusServicePrototype($name, $operations, $reflection);
+    }
+
+    /**
+     * Locate the single `#[Service]`-bearing type for the hierarchy; the root wins if annotated.
+     *
+     * @param \ReflectionClass<object> $root
+     * @param array<class-string, \ReflectionClass<object>> $matches
+     * @return \ReflectionClass<object>
+     */
+    private function resolveContract(\ReflectionClass $root, array $matches): \ReflectionClass
+    {
+        if ($this->reader->firstClassMetadata($root, Service::class) !== null) {
+            return $root;
+        }
+
+        if ($matches === []) {
+            throw new InvalidArgumentException(\sprintf(
+                'Missing #[Service] attribute on %s or any implemented interface',
+                $root->getName(),
+            ));
+        }
+
+        if (\count($matches) > 1) {
+            throw new InvalidArgumentException(\sprintf(
+                '%s implements multiple #[Service] types (%s); ambiguous',
+                $root->getName(),
+                \implode(', ', \array_keys($matches)),
+            ));
+        }
+
+        return \reset($matches);
+    }
+
+    /**
+     * Reject hierarchies whose other `#[Service]` types declare a different service name.
+     *
+     * @param array<class-string, \ReflectionClass<object>> $serviceNodes
+     * @param \ReflectionClass<object> $contract
+     */
+    private function assertServiceNamesMatch(array $serviceNodes, \ReflectionClass $contract, string $name): void
+    {
+        foreach ($serviceNodes as $node) {
+            if ($node->getName() === $contract->getName()) {
+                continue;
+            }
+
+            $service = $this->reader->firstClassMetadata($node, Service::class);
+            \assert($service !== null);
+            $nodeName = $service->name !== '' ? $service->name : $node->getShortName();
+            if ($nodeName !== $name) {
+                throw new InvalidArgumentException(
+                    "Interface {$node->getName()} has a service attribute whose name ({$nodeName}) "
+                    . "does not match the expected name on the contract ({$name})",
+                );
+            }
+        }
+    }
+
+    /**
+     * Collect every `#[Service]`-annotated type across the hierarchy, keyed by class name.
+     *
+     * @return array<class-string, \ReflectionClass<object>>
+     */
+    private function serviceNodes(ClassNode $graph): array
+    {
+        $matches = [];
+        foreach ($graph as $edge) {
+            foreach ($edge as $node) {
+                $reflection = $node->getReflection();
+                if ($this->reader->firstClassMetadata($reflection, Service::class) !== null) {
+                    $matches[$reflection->getName()] = $reflection;
+                }
+            }
+        }
+
+        return $matches;
+    }
+
+    /**
+     * @return array<string, NexusOperationPrototype>
+     */
+    private function collectOperations(ClassNode $graph): array
+    {
+        $operationFailures = [];
+        $operations = [];
+
+        foreach (\array_keys($graph->getAllMethods()) as $name) {
+            $first = null;
+            /** @var \Traversable<ClassNode, \ReflectionMethod> $group */
+            foreach ($graph->getMethods($name) as $group) {
+                foreach ($group as $method) {
+                    try {
+                        $attribute = $this->operationAttribute($method);
+                        if ($attribute === null) {
+                            continue;
+                        }
+
+                        $current = $this->operationFromMethod($method, $attribute);
+                        if ($first === null) {
+                            $first = $current;
+                            if (isset($operations[$first->name])) {
+                                $operationFailures[] = "Multiple operations named '{$first->name}'";
+                                break 2;
+                            }
+                            $operations[$first->name] = $first;
+                        } elseif (
+                            $first->name !== $current->name
+                            || $first->inputType != $current->inputType
+                            || $first->outputType != $current->outputType
+                        ) {
+                            $operationFailures[] = "{$method->getName()} on {$method->getDeclaringClass()->getName()} "
+                                . 'mismatches against another operation of the same name/signature';
+                            break 2;
+                        }
+                    } catch (\Exception $exception) {
+                        $operationFailures[] = "{$method->getName()} on {$method->getDeclaringClass()->getName()} "
+                            . "is invalid: {$exception->getMessage()}";
+                        break 2;
+                    }
+                }
+            }
+        }
+
+        if (\count($operationFailures) > 0) {
+            throw new InvalidArgumentException(
+                \count($operationFailures) . ' operation(s) were invalid, reasons: '
+                . \implode(', ', $operationFailures),
+            );
+        }
+
+        if (\count($operations) === 0) {
+            throw new InvalidArgumentException('No operations defined');
+        }
+
+        return $operations;
+    }
+
+    /**
+     * Resolve the operation attribute for a method; `null` means the method is not an operation.
+     */
+    private function operationAttribute(\ReflectionMethod $method): Operation|AsyncOperation|null
+    {
+        $sync = $this->reader->firstFunctionMetadata($method, Operation::class);
+        $async = $this->reader->firstFunctionMetadata($method, AsyncOperation::class);
+
+        if ($sync !== null && $async !== null) {
+            throw new InvalidArgumentException('declares both #[Operation] and #[AsyncOperation]');
+        }
+
+        return $sync ?? $async;
+    }
+
+    /**
+     * Build a {@see NexusOperationPrototype} from a resolved `#[Operation]` / `#[AsyncOperation]` attribute.
+     */
+    private function operationFromMethod(
+        \ReflectionMethod $method,
+        Operation|AsyncOperation $attribute,
+    ): NexusOperationPrototype {
+        if ($method->getNumberOfParameters() > 1) {
+            throw new InvalidArgumentException('Can have no more than one parameter');
+        }
+        if ($method->isStatic()) {
+            throw new InvalidArgumentException('Cannot be static');
+        }
+        if (!$this->isValidMethod($method)) {
+            throw new InvalidArgumentException('Must be public');
+        }
+
+        $inputType = new Type(Type::TYPE_VOID);
+        if ($method->getNumberOfParameters() === 1) {
+            $inputType = Type::create($method->getParameters()[0]->getType());
+        }
+
+        $async = $attribute instanceof AsyncOperation ? $attribute : null;
+
+        if ($async !== null) {
+            $this->assertAsyncReturnType($method);
+            $operationName = $async->name !== '' ? $async->name : $method->getName();
+            $outputType = Type::create($async->output !== '' ? $async->output : Type::TYPE_VOID);
+
+            if (self::returnsOperationHandler($method)) {
+                if ($method->getNumberOfParameters() !== 0) {
+                    throw new InvalidArgumentException(
+                        'Operation handler factory must declare no parameters; '
+                        . 'the input arrives in OperationHandlerInterface::start()',
+                    );
+                }
+                $inputType = Type::create($async->input !== '' ? $async->input : Type::TYPE_ANY);
+            }
+        } else {
+            $operationName = $attribute->name !== '' ? $attribute->name : $method->getName();
+            $outputType = Type::create($method->getReturnType());
+        }
+
+        return new NexusOperationPrototype(
+            name: $operationName,
+            methodName: $method->getName(),
+            inputType: $inputType,
+            outputType: $outputType,
+            async: $async !== null,
+            handler: $method,
+        );
+    }
+
+    /**
+     * An `#[AsyncOperation]` method must return a non-nullable `WorkflowHandle`
+     * (SDK-managed workflow run) or an `OperationHandlerInterface` implementation
+     * (manual operation owning both start and cancel).
+     */
+    private function assertAsyncReturnType(\ReflectionMethod $method): void
+    {
+        $returnType = $method->getReturnType();
+        if (
+            $returnType instanceof \ReflectionNamedType
+            && !$returnType->allowsNull()
+            && $returnType->getName() === WorkflowHandle::class
+        ) {
+            return;
+        }
+        if (self::returnsOperationHandler($method)) {
+            return;
+        }
+
+        throw new InvalidArgumentException(\sprintf(
+            '#[%s] method %s::%s() must declare a `%s` return type or return an `%s` implementation',
+            AsyncOperation::class,
+            $method->getDeclaringClass()->getName(),
+            $method->getName(),
+            WorkflowHandle::class,
+            OperationHandlerInterface::class,
+        ));
+    }
+}
diff --git a/src/Internal/Declaration/Reader/WorkflowReader.php b/src/Internal/Declaration/Reader/WorkflowReader.php
index d97877a22..a90b78078 100644
--- a/src/Internal/Declaration/Reader/WorkflowReader.php
+++ b/src/Internal/Declaration/Reader/WorkflowReader.php
@@ -279,6 +279,7 @@ private function assertWorkflowInterface(ClassNode $graph): void
      */
     private function getAttributedMethod(ClassNode $graph, \ReflectionMethod $handler, string $name): ?object
     {
+        /** @var \Traversable<ClassNode, \ReflectionMethod> $group */
         foreach ($graph->getMethods($handler->getName()) as $group) {
             foreach ($group as $method) {
                 $attribute = $this->reader->firstFunctionMetadata($method, $name);
@@ -301,7 +302,7 @@ private function getPrototype(ClassNode $graph, \ReflectionMethod $handler): ?Wo
     {
         $cronSchedule = $previousRetry = $prototype = $returnType = $versionBehavior = null;
 
-        /** @var \Traversable<class-string, \ReflectionMethod> $group */
+        /** @var \Traversable<ClassNode, \ReflectionMethod> $group */
         foreach ($graph->getMethods($handler->getName()) as $group) {
             $contextualRetry = $previousRetry;
 
diff --git a/src/Internal/Nexus/HandlerErrorMapper.php b/src/Internal/Nexus/HandlerErrorMapper.php
new file mode 100644
index 000000000..6f4fb6639
--- /dev/null
+++ b/src/Internal/Nexus/HandlerErrorMapper.php
@@ -0,0 +1,87 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Nexus;
+
+use Google\Rpc\Code;
+use Temporal\Exception\Client\ServiceClientException;
+use Temporal\Exception\Client\WorkflowException;
+use Temporal\Exception\Client\WorkflowExecutionAlreadyStartedException;
+use Temporal\Exception\Client\WorkflowNotFoundException;
+use Temporal\Exception\Failure\ApplicationFailure;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\RetryBehavior;
+
+/**
+ * @internal
+ */
+final class HandlerErrorMapper
+{
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    public static function mapToHandlerException(\Throwable $e): ?HandlerException
+    {
+        if ($e instanceof ApplicationFailure && $e->isNonRetryable()) {
+            return HandlerException::fromCause(ErrorType::Internal, $e, RetryBehavior::NonRetryable);
+        }
+
+        if ($e instanceof WorkflowNotFoundException) {
+            return HandlerException::fromCause(ErrorType::NotFound, $e);
+        }
+
+        if ($e instanceof WorkflowExecutionAlreadyStartedException) {
+            return HandlerException::fromCause(ErrorType::Internal, $e, RetryBehavior::NonRetryable);
+        }
+
+        if ($e instanceof WorkflowException) {
+            $previous = $e->getPrevious();
+            if ($previous instanceof ServiceClientException) {
+                return self::fromGrpcCode($previous);
+            }
+
+            return HandlerException::fromCause(ErrorType::BadRequest, $e);
+        }
+
+        if ($e instanceof ServiceClientException) {
+            return self::fromGrpcCode($e);
+        }
+
+        return null;
+    }
+
+    private static function fromGrpcCode(ServiceClientException $e): HandlerException
+    {
+        return match ($e->getCode()) {
+            Code::INVALID_ARGUMENT => HandlerException::fromCause(ErrorType::BadRequest, $e),
+            Code::ALREADY_EXISTS,
+            Code::FAILED_PRECONDITION,
+            Code::OUT_OF_RANGE => HandlerException::fromCause(ErrorType::Internal, $e, RetryBehavior::NonRetryable),
+            Code::ABORTED,
+            Code::UNAVAILABLE => HandlerException::fromCause(ErrorType::Unavailable, $e),
+            // Unauthenticated/PermissionDenied collapse to Internal: a handler-side auth failure against Temporal, not a Nexus-caller auth error.
+            Code::CANCELLED,
+            Code::DATA_LOSS,
+            Code::INTERNAL,
+            Code::UNKNOWN,
+            Code::UNAUTHENTICATED,
+            Code::PERMISSION_DENIED => HandlerException::fromCause(ErrorType::Internal, $e),
+            Code::NOT_FOUND => HandlerException::fromCause(ErrorType::NotFound, $e),
+            Code::RESOURCE_EXHAUSTED => HandlerException::fromCause(ErrorType::ResourceExhausted, $e),
+            Code::UNIMPLEMENTED => HandlerException::fromCause(ErrorType::NotImplemented, $e),
+            Code::DEADLINE_EXCEEDED => HandlerException::fromCause(ErrorType::UpstreamTimeout, $e),
+            default => HandlerException::fromCause(ErrorType::Internal, $e),
+        };
+    }
+}
diff --git a/src/Internal/Nexus/NexusContext.php b/src/Internal/Nexus/NexusContext.php
new file mode 100644
index 000000000..7aba8047b
--- /dev/null
+++ b/src/Internal/Nexus/NexusContext.php
@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Nexus;
+
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Internal\Interceptor\Pipeline;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\NexusOperationContext;
+
+/**
+ * {@see $startDetails} and {@see $cancelDetails} are mutually exclusive.
+ */
+final class NexusContext
+{
+    /**
+     * @param null|Pipeline<\Temporal\Interceptor\NexusOperationOutboundCallsInterceptor, mixed> $outboundPipeline
+     */
+    public function __construct(
+        public readonly OperationContext $current,
+        public readonly ?NexusOperationContext $operation = null,
+        public readonly ?WorkflowClientInterface $workflowClient = null,
+        public readonly ?OperationStartDetails $startDetails = null,
+        public readonly ?OperationCancelDetails $cancelDetails = null,
+        public readonly ?Pipeline $outboundPipeline = null,
+    ) {}
+}
diff --git a/src/Internal/Nexus/NexusInvocationRegistry.php b/src/Internal/Nexus/NexusInvocationRegistry.php
new file mode 100644
index 000000000..1fd6aec7a
--- /dev/null
+++ b/src/Internal/Nexus/NexusInvocationRegistry.php
@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Nexus;
+
+use Temporal\Nexus\Handler\MethodCanceller;
+
+/**
+ * Maps RR `InvocationID` → MethodCanceller for in-flight handlers.
+ * Lookup miss = late cancel after the handler finished, treat as no-op.
+ */
+final class NexusInvocationRegistry
+{
+    /** @var array<int, MethodCanceller> */
+    private array $cancellers = [];
+
+    public function register(int $invocationId, MethodCanceller $canceller): void
+    {
+        $this->cancellers[$invocationId] = $canceller;
+    }
+
+    public function unregister(int $invocationId): void
+    {
+        unset($this->cancellers[$invocationId]);
+    }
+
+    public function get(int $invocationId): ?MethodCanceller
+    {
+        return $this->cancellers[$invocationId] ?? null;
+    }
+}
diff --git a/src/Internal/Nexus/NexusLinkConverter.php b/src/Internal/Nexus/NexusLinkConverter.php
new file mode 100644
index 000000000..902c8408e
--- /dev/null
+++ b/src/Internal/Nexus/NexusLinkConverter.php
@@ -0,0 +1,321 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Nexus;
+
+use Temporal\Api\Common\V1\Link;
+use Temporal\Api\Common\V1\Link\WorkflowEvent;
+use Temporal\Api\Common\V1\Link\WorkflowEvent\EventReference;
+use Temporal\Api\Common\V1\Link\WorkflowEvent\RequestIdReference;
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Api\Nexus\V1\Link as NexusProtoLink;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Link as NexusLink;
+
+/**
+ * @internal
+ */
+final class NexusLinkConverter
+{
+    private const SCHEME = 'temporal';
+    private const PATH_REGEX = '#^/namespaces/([^/]+)/workflows/([^/]+)/([^/]+)/history$#';
+    public const TYPE_WORKFLOW_EVENT = 'temporal.api.common.v1.Link.WorkflowEvent';
+    private const REF_TYPE_EVENT = 'EventReference';
+    private const REF_TYPE_REQUEST_ID = 'RequestIdReference';
+    private const QUERY_REFERENCE_TYPE = 'referenceType';
+    private const QUERY_EVENT_ID       = 'eventID';
+    private const QUERY_EVENT_TYPE     = 'eventType';
+    private const QUERY_REQUEST_ID     = 'requestID';
+
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    /**
+     * @param iterable<NexusLink> $links
+     * @return list<Link>
+     * @throws InvalidArgumentException on malformed WorkflowEvent URI.
+     */
+    public static function toProtoLinks(iterable $links): array
+    {
+        $out = [];
+        foreach ($links as $link) {
+            if ($link->type !== self::TYPE_WORKFLOW_EVENT) {
+                continue;
+            }
+            $out[] = self::convertOne($link);
+        }
+        return $out;
+    }
+
+    /**
+     * Bare wire form: only `url` + `type`, no parsed `WorkflowEvent`; non-WorkflowEvent types pass through.
+     *
+     * @param iterable<NexusLink> $links
+     * @return list<NexusProtoLink>
+     */
+    public static function toNexusProtoLinks(iterable $links): array
+    {
+        $out = [];
+        foreach ($links as $link) {
+            $proto = new NexusProtoLink();
+            $proto->setUrl($link->uri);
+            $proto->setType($link->type);
+            $out[] = $proto;
+        }
+        return $out;
+    }
+
+    /**
+     * Wire `eventType` is written in PascalCase (`WorkflowExecutionStarted`); decoder accepts both forms.
+     *
+     * @throws InvalidArgumentException when WorkflowEvent has neither
+     *         event_ref nor request_id_ref set, or carries an unknown
+     *         EventType enum value.
+     */
+    public static function workflowEventToNexusLink(WorkflowEvent $event): NexusLink
+    {
+        $path = \sprintf(
+            '/namespaces/%s/workflows/%s/%s/history',
+            \rawurlencode($event->getNamespace()),
+            \rawurlencode($event->getWorkflowId()),
+            \rawurlencode($event->getRunId()),
+        );
+
+        $query = self::buildEventQuery($event);
+        $uri = 'temporal://' . $path . '?' . self::encodeQuery($query);
+
+        return new NexusLink($uri, self::TYPE_WORKFLOW_EVENT);
+    }
+
+    private static function convertOne(NexusLink $link): Link
+    {
+        // Manual scheme/path/query split — parse_url rejects the `scheme:///path` (empty authority) form.
+        if (!\preg_match('~^([a-zA-Z][a-zA-Z0-9+.\-]*):(?://[^/?\#]*)?(/[^?\#]*)(?:\?([^\#]*))?(?:\#.*)?$~', $link->uri, $uriParts)) {
+            throw new InvalidArgumentException(\sprintf(
+                'malformed Nexus link URI: "%s"',
+                $link->uri,
+            ));
+        }
+        $scheme = $uriParts[1];
+        $path = $uriParts[2];
+        $queryString = $uriParts[3] ?? '';
+
+        if ($scheme !== self::SCHEME) {
+            throw new InvalidArgumentException(\sprintf(
+                'Nexus link URI scheme must be "temporal", got "%s" in "%s"',
+                $scheme,
+                $link->uri,
+            ));
+        }
+        if (!\preg_match(self::PATH_REGEX, $path, $pathMatches)) {
+            throw new InvalidArgumentException(\sprintf(
+                'Nexus link URI path does not match /namespaces/{ns}/workflows/{wf}/{run}/history: "%s"',
+                $path,
+            ));
+        }
+        $namespace = \rawurldecode($pathMatches[1]);
+        $workflowId = \rawurldecode($pathMatches[2]);
+        $runId = \rawurldecode($pathMatches[3]);
+
+        $query = [];
+        if ($queryString !== '') {
+            \parse_str($queryString, $query);
+        }
+
+        $event = (new WorkflowEvent())
+            ->setNamespace($namespace)
+            ->setWorkflowId($workflowId)
+            ->setRunId($runId);
+
+        $referenceType = (string) ($query[self::QUERY_REFERENCE_TYPE] ?? '');
+        $eventTypeName = (string) ($query[self::QUERY_EVENT_TYPE] ?? '');
+        $eventTypeValue = self::resolveEventType($eventTypeName);
+        if ($eventTypeValue === null) {
+            throw new InvalidArgumentException(\sprintf(
+                'unknown EventType "%s" in Nexus link URI "%s"',
+                $eventTypeName,
+                $link->uri,
+            ));
+        }
+
+        match ($referenceType) {
+            self::REF_TYPE_EVENT => $event->setEventRef(self::buildEventRef($query, $eventTypeValue, $link->uri)),
+            self::REF_TYPE_REQUEST_ID => $event->setRequestIdRef(self::buildRequestIdRef($query, $eventTypeValue)),
+            default => throw new InvalidArgumentException(\sprintf(
+                'unknown referenceType "%s" in Nexus link URI "%s"',
+                $referenceType,
+                $link->uri,
+            )),
+        };
+
+        $proto = new Link();
+        $proto->setWorkflowEvent($event);
+        return $proto;
+    }
+
+    /**
+     * Accepts both legacy `EVENT_TYPE_*` and modern PascalCase wire forms.
+     */
+    private static function resolveEventType(string $name): ?int
+    {
+        if ($name === '') {
+            return null;
+        }
+
+        if (\str_starts_with($name, 'EVENT_TYPE_')) {
+            return self::lookupEventTypeValue($name);
+        }
+
+        if (!\preg_match('/^[A-Z]/', $name)) {
+            return null;
+        }
+
+        return self::lookupEventTypeValue('EVENT_TYPE_' . self::pascalCaseToConstantCase($name));
+    }
+
+    private static function lookupEventTypeValue(string $screamingName): ?int
+    {
+        try {
+            return EventType::value($screamingName);
+        } catch (\UnexpectedValueException) {
+            return null;
+        }
+    }
+
+    /**
+     * "WorkflowExecutionStarted" → "WORKFLOW_EXECUTION_STARTED".
+     */
+    private static function pascalCaseToConstantCase(string $pascal): string
+    {
+        if ($pascal === '') {
+            return '';
+        }
+        $withUnderscores = \preg_replace('/(?<!^)([A-Z])/', '_$1', $pascal);
+        return \strtoupper($withUnderscores ?? $pascal);
+    }
+
+    /**
+     * @param array<string,mixed> $query
+     */
+    private static function buildEventRef(array $query, int $eventType, string $uri): EventReference
+    {
+        $eventReference = new EventReference();
+        $eventReference->setEventType($eventType);
+        if (isset($query[self::QUERY_EVENT_ID]) && $query[self::QUERY_EVENT_ID] !== '') {
+            if (!\preg_match('/^\\d+$/', (string) $query[self::QUERY_EVENT_ID])) {
+                throw new InvalidArgumentException(\sprintf(
+                    'eventID is not an integer in Nexus link URI "%s"',
+                    $uri,
+                ));
+            }
+            $eventReference->setEventId((int) $query[self::QUERY_EVENT_ID]);
+        }
+        return $eventReference;
+    }
+
+    /**
+     * @param array<string,mixed> $query
+     */
+    private static function buildRequestIdRef(array $query, int $eventType): RequestIdReference
+    {
+        $requestId = $query[self::QUERY_REQUEST_ID] ?? '';
+        if (!\is_string($requestId)) {
+            $requestId = '';
+        }
+        $requestIdReference = new RequestIdReference();
+        $requestIdReference->setRequestId($requestId);
+        $requestIdReference->setEventType($eventType);
+        return $requestIdReference;
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    private static function buildEventQuery(WorkflowEvent $event): array
+    {
+        if ($event->hasEventRef()) {
+            $eventRef = $event->getEventRef();
+            \assert($eventRef !== null);
+            $query = [self::QUERY_REFERENCE_TYPE => self::REF_TYPE_EVENT];
+            $eventId = (int) $eventRef->getEventId();
+            if ($eventId > 0) {
+                $query[self::QUERY_EVENT_ID] = (string) $eventId;
+            }
+            $query[self::QUERY_EVENT_TYPE] = self::encodeEventTypeName($eventRef->getEventType(), $event);
+            return $query;
+        }
+        if ($event->hasRequestIdRef()) {
+            $requestRef = $event->getRequestIdRef();
+            \assert($requestRef !== null);
+            $query = [self::QUERY_REFERENCE_TYPE => self::REF_TYPE_REQUEST_ID];
+            $requestId = $requestRef->getRequestId();
+            if ($requestId !== '') {
+                $query[self::QUERY_REQUEST_ID] = $requestId;
+            }
+            $query[self::QUERY_EVENT_TYPE] = self::encodeEventTypeName($requestRef->getEventType(), $event);
+            return $query;
+        }
+        throw new InvalidArgumentException(
+            'WorkflowEvent must have either event_ref or request_id_ref set',
+        );
+    }
+
+    /**
+     * @param array<string, string> $query
+     */
+    private static function encodeQuery(array $query): string
+    {
+        $parts = [];
+        foreach ($query as $key => $value) {
+            $parts[] = \rawurlencode($key) . '=' . \rawurlencode($value);
+        }
+        return \implode('&', $parts);
+    }
+
+    /**
+     * Convert protobuf int → PascalCase wire form (`WorkflowExecutionStarted`).
+     *
+     * @throws InvalidArgumentException when $value is not a known EventType.
+     */
+    private static function encodeEventTypeName(int $value, WorkflowEvent $event): string
+    {
+        try {
+            $screaming = EventType::name($value);
+        } catch (\UnexpectedValueException) {
+            $screaming = null;
+        }
+        if ($screaming === null) {
+            throw new InvalidArgumentException(\sprintf(
+                'unknown EventType enum value %d in WorkflowEvent (workflow_id="%s")',
+                $value,
+                $event->getWorkflowId(),
+            ));
+        }
+        if (!\str_starts_with($screaming, 'EVENT_TYPE_')) {
+            return $screaming;
+        }
+        return self::constantCaseToPascalCase(\substr($screaming, \strlen('EVENT_TYPE_')));
+    }
+
+    /**
+     * "WORKFLOW_EXECUTION_STARTED" → "WorkflowExecutionStarted".
+     */
+    private static function constantCaseToPascalCase(string $screaming): string
+    {
+        if ($screaming === '') {
+            return '';
+        }
+        $segments = \explode('_', \strtolower($screaming));
+        return \implode('', \array_map(\ucfirst(...), $segments));
+    }
+}
diff --git a/src/Internal/Nexus/NexusTaskHandler.php b/src/Internal/Nexus/NexusTaskHandler.php
new file mode 100644
index 000000000..2431476d3
--- /dev/null
+++ b/src/Internal/Nexus/NexusTaskHandler.php
@@ -0,0 +1,252 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Nexus;
+
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Exception\OperationException;
+use Temporal\Nexus\Exception\RetryBehavior;
+use Temporal\Nexus\Handler\AsyncOperationStartResult;
+use Temporal\Nexus\Handler\MethodCanceller;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\Internal\ServiceHandler;
+use Temporal\Nexus\Handler\SyncOperationStartResult;
+use Temporal\Nexus\Header as NexusHeader;
+use Temporal\Nexus\LinkParser;
+use Temporal\Nexus\NexusOperationContext;
+use Temporal\Api\Nexus\V1\CancelOperationRequest;
+use Temporal\Api\Nexus\V1\CancelOperationResponse;
+use Temporal\Api\Nexus\V1\Request;
+use Temporal\Api\Nexus\V1\Response;
+use Temporal\Api\Nexus\V1\StartOperationRequest;
+use Temporal\Api\Nexus\V1\StartOperationResponse;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\DataConverter\DataConverterInterface;
+use Temporal\Interceptor\PipelineProvider;
+use Temporal\Interceptor\SimplePipelineProvider;
+use Temporal\Internal\Declaration\Instantiator\NexusServiceInstantiator;
+use Temporal\Internal\Declaration\Prototype\NexusServiceCollection;
+use Temporal\DataConverter\EncodedValues;
+use Temporal\DataConverter\ValuesInterface;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Worker\Environment\EnvironmentInterface;
+
+/**
+ * Bridges Temporal RoadRunner tasks to the Nexus SDK ServiceHandler; ServiceHandler is built lazily.
+ */
+final class NexusTaskHandler
+{
+    private ?ServiceHandler $serviceHandler = null;
+
+    public function __construct(
+        private readonly NexusServiceCollection $repository,
+        private readonly DataConverterInterface $dataConverter,
+        private readonly EnvironmentInterface $env,
+        private readonly PipelineProvider $interceptorProvider = new SimplePipelineProvider(),
+        private readonly ?WorkflowClientInterface $workflowClient = null,
+    ) {}
+
+    /**
+     * Absolute deadline from Request-Timeout (how long the handler has to act); absent or unparseable yields null.
+     * Operation-Timeout is the total operation budget and is left in the headers forwarded to the handler.
+     *
+     * @param array<string, string> $headers
+     */
+    public static function deadlineFromHeaders(array $headers): ?\DateTimeImmutable
+    {
+        $lowerHeaders = \array_change_key_case($headers, \CASE_LOWER);
+
+        $value = NexusHeader::get($lowerHeaders, NexusHeader::REQUEST_TIMEOUT);
+
+        if ($value === null || $value === '') {
+            return null;
+        }
+
+        try {
+            return NexusHeader::deadlineFromTimeout($value);
+        } catch (InvalidArgumentException) {
+            return null;
+        }
+    }
+
+    public function handleStartOperation(
+        Request $request,
+        NexusOperationContext $operationContext,
+        ?MethodCanceller $methodCanceller = null,
+    ): Response {
+        $startRequest = $request->getStartOperation();
+        \assert($startRequest instanceof StartOperationRequest);
+
+        $headers = [];
+        foreach ($request->getHeader() as $key => $value) {
+            $headers[(string) $key] = (string) $value;
+        }
+
+        $links = LinkParser::fromProto($startRequest->getLinks());
+
+        $callbackHeaders = [];
+        foreach ($startRequest->getCallbackHeader() as $key => $value) {
+            $callbackHeaders[(string) $key] = (string) $value;
+        }
+
+        $context = new OperationContext(
+            service: $startRequest->getService(),
+            operation: $startRequest->getOperation(),
+            headers: $headers,
+            deadline: self::deadlineFromHeaders($headers),
+            methodCanceller: $methodCanceller,
+            env: $this->env,
+        );
+
+        $input = EncodedValues::fromPayload($startRequest->getPayload(), $this->dataConverter);
+
+        try {
+            $details = new OperationStartDetails(
+                requestId: $startRequest->getRequestId(),
+                callbackUrl: $startRequest->getCallback() ?: null,
+                callbackHeaders: $callbackHeaders,
+                links: $links,
+            );
+
+            $result = $this->getServiceHandler()->startOperation(
+                $context,
+                $details,
+                $input,
+                $this->workflowClient,
+                $operationContext,
+            );
+
+            $startResponse = new StartOperationResponse();
+
+            if ($result instanceof SyncOperationStartResult) {
+                $syncResponse = new StartOperationResponse\Sync();
+
+                if (!$result->value instanceof ValuesInterface) {
+                    throw new \LogicException('sync start result must be ValuesInterface');
+                }
+                $resultPayload = EncodedValues::firstPayload($result->value);
+                if ($resultPayload !== null) {
+                    $syncResponse->setPayload($resultPayload);
+                }
+
+                $contextLinks = $context->links->all();
+                if ($contextLinks !== []) {
+                    $syncResponse->setLinks(NexusLinkConverter::toNexusProtoLinks($contextLinks));
+                }
+
+                $startResponse->setSyncSuccess($syncResponse);
+            } else {
+                \assert($result instanceof AsyncOperationStartResult);
+                $asyncResponse = new StartOperationResponse\Async();
+                /** @psalm-suppress DeprecatedMethod */
+                $asyncResponse->setOperationId($result->info->token);
+                $asyncResponse->setOperationToken($result->info->token);
+
+                $contextLinks = $context->links->all();
+                if ($contextLinks !== []) {
+                    $asyncResponse->setLinks(NexusLinkConverter::toNexusProtoLinks($contextLinks));
+                }
+
+                $startResponse->setAsyncSuccess($asyncResponse);
+            }
+
+            $response = new Response();
+            $response->setStartOperation($startResponse);
+            return $response;
+        } catch (OperationException $e) {
+            throw $e;
+        } catch (\Throwable $e) {
+            throw $this->toHandlerException($e);
+        }
+    }
+
+    public function handleCancelOperation(
+        Request $request,
+        NexusOperationContext $operationContext,
+    ): Response {
+        $cancelRequest = $request->getCancelOperation();
+        \assert($cancelRequest instanceof CancelOperationRequest);
+
+        $headers = [];
+        foreach ($request->getHeader() as $key => $value) {
+            $headers[(string) $key] = (string) $value;
+        }
+
+        $context = new OperationContext(
+            service: $cancelRequest->getService(),
+            operation: $cancelRequest->getOperation(),
+            headers: $headers,
+            deadline: self::deadlineFromHeaders($headers),
+            env: $this->env,
+        );
+
+        $token = $cancelRequest->getOperationToken();
+        if ($token === '') {
+            /** @psalm-suppress DeprecatedMethod — back-compat fallback */
+            $token = $cancelRequest->getOperationId();
+        }
+
+        try {
+            $details = new OperationCancelDetails(operationToken: $token);
+
+            $this->getServiceHandler()->cancelOperation(
+                $context,
+                $details,
+                $this->workflowClient,
+                $operationContext,
+            );
+
+            $response = new Response();
+            $response->setCancelOperation(new CancelOperationResponse());
+            return $response;
+        } catch (\Throwable $e) {
+            throw $this->toHandlerException($e);
+        }
+    }
+
+    private function getServiceHandler(): ServiceHandler
+    {
+        if ($this->serviceHandler === null) {
+            $instantiator = new NexusServiceInstantiator();
+            $instances = [];
+            foreach ($this->repository as $prototype) {
+                $instances[] = $instantiator->instantiate($prototype);
+            }
+            if ($instances === []) {
+                throw new \RuntimeException('No Nexus service implementations registered');
+            }
+
+            $this->serviceHandler = ServiceHandler::create(
+                dataConverter: $this->dataConverter,
+                instances: $instances,
+                interceptorProvider: $this->interceptorProvider,
+            );
+        }
+
+        return $this->serviceHandler;
+    }
+
+    private function toHandlerException(\Throwable $e): HandlerException
+    {
+        if ($e instanceof HandlerException) {
+            return $e;
+        }
+
+        if ($e instanceof InvalidArgumentException) {
+            return HandlerException::fromCause(ErrorType::BadRequest, $e, RetryBehavior::NonRetryable);
+        }
+
+        return HandlerErrorMapper::mapToHandlerException($e) ?? HandlerException::fromCause(ErrorType::Internal, $e);
+    }
+}
diff --git a/src/Internal/ServiceContainer.php b/src/Internal/ServiceContainer.php
index 5e6e1e9ac..72b62a8f7 100644
--- a/src/Internal/ServiceContainer.php
+++ b/src/Internal/ServiceContainer.php
@@ -13,14 +13,19 @@
 
 use Psr\Log\LoggerInterface;
 use Spiral\Attributes\ReaderInterface;
+use Temporal\Client\WorkflowClientInterface;
 use Temporal\DataConverter\DataConverterInterface;
 use Temporal\Exception\ExceptionInterceptorInterface;
 use Temporal\Interceptor\PipelineProvider;
 use Temporal\Internal\Declaration\Prototype\ActivityCollection;
+use Temporal\Internal\Declaration\Prototype\NexusServiceCollection;
 use Temporal\Internal\Declaration\Prototype\WorkflowCollection;
 use Temporal\Internal\Declaration\Prototype\WorkflowPrototype;
 use Temporal\Internal\Declaration\Reader\ActivityReader;
+use Temporal\Internal\Declaration\Reader\NexusServiceReader;
 use Temporal\Internal\Declaration\Reader\WorkflowReader;
+use Temporal\Internal\Nexus\NexusInvocationRegistry;
+use Temporal\Internal\Nexus\NexusTaskHandler;
 use Temporal\Internal\Marshaller\MarshallerInterface;
 use Temporal\Internal\Queue\QueueInterface;
 use Temporal\Internal\Repository\RepositoryInterface;
@@ -39,6 +44,10 @@ final class ServiceContainer
     public readonly ActivityCollection $activities;
     public readonly WorkflowReader $workflowsReader;
     public readonly ActivityReader $activitiesReader;
+    public readonly NexusServiceCollection $nexusServices;
+    public readonly NexusInvocationRegistry $nexusInvocations;
+    public readonly NexusTaskHandler $nexusTaskHandler;
+    public readonly NexusServiceReader $nexusServicesReader;
 
     /**
      * @param MarshallerInterface<array> $marshaller
@@ -54,12 +63,24 @@ public function __construct(
         public readonly ExceptionInterceptorInterface $exceptionInterceptor,
         public readonly PipelineProvider $interceptorProvider,
         public readonly LoggerInterface $logger,
+        public readonly ?WorkflowClientInterface $workflowClient = null,
     ) {
         $this->workflows = new WorkflowCollection();
-        $this->activities = new ActivityCollection();
         $this->running = new ProcessCollection();
+        $this->activities = new ActivityCollection();
         $this->workflowsReader = new WorkflowReader($this->reader);
         $this->activitiesReader = new ActivityReader($this->reader);
+
+        $this->nexusServices = new NexusServiceCollection();
+        $this->nexusInvocations = new NexusInvocationRegistry();
+        $this->nexusTaskHandler = new NexusTaskHandler(
+            $this->nexusServices,
+            $this->dataConverter,
+            interceptorProvider: $this->interceptorProvider,
+            workflowClient: $workflowClient,
+            env: $this->env,
+        );
+        $this->nexusServicesReader = new NexusServiceReader($this->reader);
     }
 
     public static function fromWorkerFactory(
@@ -67,6 +88,7 @@ public static function fromWorkerFactory(
         ExceptionInterceptorInterface $exceptionInterceptor,
         PipelineProvider $interceptorProvider,
         LoggerInterface $logger,
+        ?WorkflowClientInterface $workflowClient = null,
     ): self {
         return new self(
             $worker,
@@ -79,6 +101,7 @@ public static function fromWorkerFactory(
             $exceptionInterceptor,
             $interceptorProvider,
             $logger,
+            $workflowClient,
         );
     }
 }
diff --git a/src/Internal/Support/DateInterval.php b/src/Internal/Support/DateInterval.php
index 2863aded0..a6a36614b 100644
--- a/src/Internal/Support/DateInterval.php
+++ b/src/Internal/Support/DateInterval.php
@@ -53,7 +53,6 @@ final class DateInterval
     /**
      * @psalm-param DateIntervalFormat $format
      *
-     * @psalm-assert DateIntervalValue|null $interval
      * @psalm-suppress InvalidOperand
      */
     public static function parse(mixed $interval, string $format = self::FORMAT_MILLISECONDS): CarbonInterval
diff --git a/src/Internal/Support/SystemClock.php b/src/Internal/Support/SystemClock.php
new file mode 100644
index 000000000..95e49076d
--- /dev/null
+++ b/src/Internal/Support/SystemClock.php
@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Support;
+
+use Psr\Clock\ClockInterface;
+
+/**
+ * Default PSR-20 {@see ClockInterface}: reads the system wall-clock in UTC.
+ */
+final class SystemClock implements ClockInterface
+{
+    public function now(): \DateTimeImmutable
+    {
+        return new \DateTimeImmutable('now', new \DateTimeZone('UTC'));
+    }
+}
diff --git a/src/Internal/Transport/Request/ExecuteNexusOperation.php b/src/Internal/Transport/Request/ExecuteNexusOperation.php
new file mode 100644
index 000000000..89a73e604
--- /dev/null
+++ b/src/Internal/Transport/Request/ExecuteNexusOperation.php
@@ -0,0 +1,59 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Transport\Request;
+
+use Temporal\DataConverter\ValuesInterface;
+use Temporal\Interceptor\HeaderInterface;
+use Temporal\Worker\Transport\Command\Client\Request;
+use Temporal\Worker\Transport\Command\RequestInterface;
+
+/**
+ * @psalm-import-type RequestOptions from RequestInterface
+ * @psalm-immutable
+ */
+final class ExecuteNexusOperation extends Request implements RejectedOnCancelInterface
+{
+    public const NAME = 'ExecuteNexusOperation';
+
+    /**
+     * @param non-empty-string $endpoint Nexus Endpoint name
+     * @param non-empty-string $service Service name
+     * @param non-empty-string $operation Operation name
+     * @param RequestOptions $options
+     * @param array<string, string> $nexusHeaders Raw-string Nexus headers
+     *        forwarded to the handler via the wire — distinct from `$header`
+     *        (Temporal interceptor header, payload-typed values).
+     */
+    public function __construct(
+        string $endpoint,
+        string $service,
+        string $operation,
+        ValuesInterface $args,
+        array $options,
+        HeaderInterface $header,
+        array $nexusHeaders = [],
+    ) {
+        parent::__construct(
+            self::NAME,
+            [
+                'endpoint' => $endpoint,
+                'service' => $service,
+                'operation' => $operation,
+                'options' => $options,
+                // Force `{}` over `[]` on the wire — Go side decodes as map[string]string.
+                'nexusHeaders' => $nexusHeaders === [] ? new \stdClass() : $nexusHeaders,
+            ],
+            $args,
+            header: $header,
+        );
+    }
+}
diff --git a/src/Internal/Transport/Request/GetNexusOperationStarted.php b/src/Internal/Transport/Request/GetNexusOperationStarted.php
new file mode 100644
index 000000000..6833e52a4
--- /dev/null
+++ b/src/Internal/Transport/Request/GetNexusOperationStarted.php
@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Transport\Request;
+
+use Temporal\Worker\Transport\Command\Client\Request;
+
+/**
+ * `id` is the original ExecuteNexusOperation message ID.
+ *
+ * @psalm-immutable
+ */
+final class GetNexusOperationStarted extends Request
+{
+    public const NAME = 'GetNexusOperationStarted';
+
+    public function __construct(int $id)
+    {
+        parent::__construct(self::NAME, ['id' => $id]);
+    }
+}
diff --git a/src/Internal/Transport/Request/RejectedOnCancelInterface.php b/src/Internal/Transport/Request/RejectedOnCancelInterface.php
new file mode 100644
index 000000000..658defef5
--- /dev/null
+++ b/src/Internal/Transport/Request/RejectedOnCancelInterface.php
@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Transport\Request;
+
+use Temporal\Worker\Transport\Command\RequestInterface;
+
+/**
+ * Marks non-cancellable requests that must be locally rejected with a CanceledFailure when their scope is cancelled.
+ */
+interface RejectedOnCancelInterface extends RequestInterface {}
diff --git a/src/Internal/Transport/Router/CancelNexusOperation.php b/src/Internal/Transport/Router/CancelNexusOperation.php
new file mode 100644
index 000000000..107da9047
--- /dev/null
+++ b/src/Internal/Transport/Router/CancelNexusOperation.php
@@ -0,0 +1,63 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Transport\Router;
+
+use React\Promise\Deferred;
+use Temporal\Api\Nexus\V1\CancelOperationRequest;
+use Temporal\Api\Nexus\V1\Request;
+use Temporal\DataConverter\EncodedValues;
+use Temporal\Internal\Marshaller\MarshallerInterface;
+use Temporal\Internal\Nexus\NexusTaskHandler;
+use Temporal\Nexus\NexusOperationContext;
+use Temporal\Worker\Transport\Command\ServerRequestInterface;
+
+/**
+ * Cancel routines are not interruptible; no canceller is registered for them.
+ */
+final class CancelNexusOperation extends Route
+{
+    public function __construct(
+        private readonly NexusTaskHandler $taskHandler,
+        private readonly MarshallerInterface $marshaller,
+    ) {}
+
+    public function handle(ServerRequestInterface $request, array $headers, Deferred $resolver): void
+    {
+        try {
+            $options = $request->getOptions();
+            $operationContext = $this->marshaller->unmarshal($options, new NexusOperationContext());
+            $protoRequest = self::buildProtoRequest($options);
+            $this->taskHandler->handleCancelOperation(
+                $protoRequest,
+                $operationContext,
+            );
+            $resolver->resolve(EncodedValues::fromValues([]));
+        } catch (\Throwable $e) {
+            $resolver->reject($e);
+        }
+    }
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    private static function buildProtoRequest(array $options): Request
+    {
+        $cancelRequest = (new CancelOperationRequest())
+            ->setService((string) ($options['service'] ?? ''))
+            ->setOperation((string) ($options['operation'] ?? ''))
+            ->setOperationToken((string) ($options['operationToken'] ?? ''));
+
+        return (new Request())
+            ->setHeader((array) ($options['headers'] ?? []))
+            ->setCancelOperation($cancelRequest);
+    }
+}
diff --git a/src/Internal/Transport/Router/CancelNexusOperationMethod.php b/src/Internal/Transport/Router/CancelNexusOperationMethod.php
new file mode 100644
index 000000000..8dbbe0350
--- /dev/null
+++ b/src/Internal/Transport/Router/CancelNexusOperationMethod.php
@@ -0,0 +1,44 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Transport\Router;
+
+use React\Promise\Deferred;
+use Temporal\DataConverter\EncodedValues;
+use Temporal\Internal\Nexus\NexusInvocationRegistry;
+use Temporal\Worker\Transport\Command\ServerRequestInterface;
+
+/**
+ * Cancels the in-flight handler method (vs CancelNexusOperation which uses the
+ * operation token). Late cancel = no-op. Cancellation is cooperative — handlers
+ * must poll {@see \Temporal\Nexus\Handler\OperationContext::isMethodCancelled()}.
+ *
+ * Options: {invocationId: uint64, reason: string}.
+ */
+final class CancelNexusOperationMethod extends Route
+{
+    public function __construct(
+        private readonly NexusInvocationRegistry $invocations,
+    ) {}
+
+    public function handle(ServerRequestInterface $request, array $headers, Deferred $resolver): void
+    {
+        $options = $request->getOptions();
+        $invocationId = (int) ($options['invocationId'] ?? 0);
+        $reason = (string) ($options['reason'] ?? '');
+
+        if ($invocationId !== 0) {
+            $this->invocations->get($invocationId)?->cancel($reason);
+        }
+
+        $resolver->resolve(EncodedValues::fromValues([]));
+    }
+}
diff --git a/src/Internal/Transport/Router/GetWorkerInfo.php b/src/Internal/Transport/Router/GetWorkerInfo.php
index 596c214d4..e0710a879 100644
--- a/src/Internal/Transport/Router/GetWorkerInfo.php
+++ b/src/Internal/Transport/Router/GetWorkerInfo.php
@@ -15,6 +15,7 @@
 use Temporal\Common\SdkVersion;
 use Temporal\DataConverter\EncodedValues;
 use Temporal\Internal\Declaration\Prototype\ActivityPrototype;
+use Temporal\Internal\Declaration\Prototype\NexusServicePrototype;
 use Temporal\Internal\Declaration\Prototype\WorkflowPrototype;
 use Temporal\Internal\Marshaller\MarshallerInterface;
 use Temporal\Internal\Repository\RepositoryInterface;
@@ -57,7 +58,12 @@ private function workerToArray(WorkerInterface $worker): array
             'Name' => $activity->getID(),
         ];
 
-        $map = $this->map($this->pluginRegistry->getPlugins(PluginInterface::class), static fn(PluginInterface $plugin): array => [
+        $nexusServiceMap = static fn(NexusServicePrototype $service): array => [
+            'name' => $service->getID(),
+            'operations' => \array_keys($service->getOperations()),
+        ];
+
+        $plugins = $this->map($this->pluginRegistry->getPlugins(PluginInterface::class), static fn(PluginInterface $plugin): array => [
             'Name' => $plugin->getName(),
             'Version' => null,
         ]);
@@ -69,8 +75,9 @@ private function workerToArray(WorkerInterface $worker): array
             // ActivityInfo[]
             'Activities' => $this->map($worker->getActivities(), $activityMap),
             'PhpSdkVersion' => SdkVersion::getSdkVersion(),
-            'Plugins' => $map,
+            'Plugins' => $plugins,
             'Flags' => (object) $this->prepareFlags(),
+            'NexusServices' => $this->map($worker->getNexusServices(), $nexusServiceMap),
         ];
     }
 
diff --git a/src/Internal/Transport/Router/InvokeNexusOperation.php b/src/Internal/Transport/Router/InvokeNexusOperation.php
new file mode 100644
index 000000000..adf5215ae
--- /dev/null
+++ b/src/Internal/Transport/Router/InvokeNexusOperation.php
@@ -0,0 +1,149 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Transport\Router;
+
+use React\Promise\Deferred;
+use Temporal\Api\Nexus\V1\Request;
+use Temporal\Api\Nexus\V1\StartOperationRequest;
+use Temporal\DataConverter\DataConverterInterface;
+use Temporal\DataConverter\EncodedValues;
+use Temporal\Common\Uuid;
+use Temporal\DataConverter\ValuesInterface;
+use Temporal\Internal\Marshaller\MarshallerInterface;
+use Temporal\Internal\Nexus\NexusInvocationRegistry;
+use Temporal\Internal\Nexus\NexusLinkConverter;
+use Temporal\Internal\Nexus\NexusTaskHandler;
+use Temporal\Nexus\Handler\MethodCanceller;
+use Temporal\Nexus\LinkParser;
+use Temporal\Nexus\NexusOperationContext;
+use Temporal\Worker\Environment\EnvironmentInterface;
+use Temporal\Worker\Transport\Command\Client\CommandResponse;
+use Temporal\Worker\Transport\Command\ServerRequestInterface;
+
+final class InvokeNexusOperation extends Route
+{
+    private const COMMAND = 'NexusOperationStarted';
+
+    public function __construct(
+        private readonly NexusTaskHandler $taskHandler,
+        private readonly NexusInvocationRegistry $invocations,
+        private readonly DataConverterInterface $dataConverter,
+        private readonly MarshallerInterface $marshaller,
+        private readonly EnvironmentInterface $env,
+    ) {}
+
+    public function handle(ServerRequestInterface $request, array $headers, Deferred $resolver): void
+    {
+        $options = $request->getOptions();
+        $invocationId = (int) ($options['invocationId'] ?? 0);
+        $operationContext = $this->marshaller->unmarshal($options, new NexusOperationContext());
+
+        $canceller = null;
+        if ($invocationId !== 0) {
+            $canceller = new MethodCanceller(
+                $this->env,
+                NexusTaskHandler::deadlineFromHeaders((array) ($options['headers'] ?? [])),
+            );
+            $this->invocations->register($invocationId, $canceller);
+        }
+
+        try {
+            $protoRequest = self::buildProtoRequest($options, $request->getPayloads());
+            $response = $this->taskHandler->handleStartOperation(
+                $protoRequest,
+                $operationContext,
+                $canceller,
+            );
+
+            $startResponse = $response->getStartOperation();
+            \assert($startResponse !== null);
+
+            if ($startResponse->hasSyncSuccess()) {
+                $sync = $startResponse->getSyncSuccess();
+                \assert($sync !== null);
+                $responseOptions = ['async' => false];
+                $protoLinks = $sync->getLinks();
+                $payloads = EncodedValues::fromPayload($sync->getPayload(), $this->dataConverter);
+            } elseif ($startResponse->hasAsyncSuccess()) {
+                $async = $startResponse->getAsyncSuccess();
+                \assert($async !== null);
+                $responseOptions = ['async' => true];
+                $token = $async->getOperationToken();
+                if ($token !== '') {
+                    $responseOptions['token'] = $token;
+                }
+                $protoLinks = $async->getLinks();
+                $payloads = null;
+            } else {
+                $resolver->reject(new \LogicException('NexusTaskHandler returned a response with no success variant'));
+                return;
+            }
+
+            $links = self::linksToWire($protoLinks);
+            if ($links !== []) {
+                $responseOptions['links'] = $links;
+            }
+
+            $resolver->resolve(new CommandResponse(
+                command: self::COMMAND,
+                options: $responseOptions,
+                payloads: $payloads,
+            ));
+        } catch (\Throwable $e) {
+            $resolver->reject($e);
+        } finally {
+            if ($invocationId !== 0) {
+                $this->invocations->unregister($invocationId);
+            }
+        }
+    }
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    private static function buildProtoRequest(array $options, ValuesInterface $payloads): Request
+    {
+        $requestId = ((string) ($options['requestId'] ?? '')) ?: Uuid::v4();
+
+        $startRequest = (new StartOperationRequest())
+            ->setService((string) ($options['service'] ?? ''))
+            ->setOperation((string) ($options['operation'] ?? ''))
+            ->setRequestId($requestId)
+            ->setCallback((string) ($options['callback'] ?? ''))
+            ->setCallbackHeader((array) ($options['callbackHeaders'] ?? []))
+            ->setLinks(NexusLinkConverter::toNexusProtoLinks(
+                LinkParser::fromRaw($options['links'] ?? null),
+            ));
+
+        $inputPayload = EncodedValues::firstPayload($payloads);
+        if ($inputPayload !== null) {
+            $startRequest->setPayload($inputPayload);
+        }
+
+        return (new Request())
+            ->setHeader((array) ($options['headers'] ?? []))
+            ->setStartOperation($startRequest);
+    }
+
+    /**
+     * @param iterable<\Temporal\Api\Nexus\V1\Link> $links
+     * @return list<array{url: string, type: string}>
+     */
+    private static function linksToWire(iterable $links): array
+    {
+        $out = [];
+        foreach ($links as $link) {
+            $out[] = ['url' => $link->getUrl(), 'type' => $link->getType()];
+        }
+        return $out;
+    }
+}
diff --git a/src/Internal/Transport/Router/InvokeUpdate.php b/src/Internal/Transport/Router/InvokeUpdate.php
index 5f228d324..107c4d077 100644
--- a/src/Internal/Transport/Router/InvokeUpdate.php
+++ b/src/Internal/Transport/Router/InvokeUpdate.php
@@ -16,12 +16,14 @@
 use Temporal\DataConverter\EncodedValues;
 use Temporal\Interceptor\WorkflowInbound\UpdateInput;
 use Temporal\Internal\Declaration\WorkflowInstance\UpdateDispatcher;
-use Temporal\Worker\Transport\Command\Client\UpdateResponse;
+use Temporal\Worker\Transport\Command\Client\CommandResponse;
 use Temporal\Worker\Transport\Command\ServerRequestInterface;
 
 final class InvokeUpdate extends WorkflowProcessAwareRoute
 {
     private const ERROR_HANDLER_NOT_FOUND = 'unknown update method %s. KnownUpdateNames=[%s]';
+    private const COMMAND_VALIDATED = 'UpdateValidated';
+    private const COMMAND_COMPLETED = 'UpdateCompleted';
 
     public function handle(ServerRequestInterface $request, array $headers, Deferred $resolver): void
     {
@@ -54,32 +56,34 @@ public function handle(ServerRequestInterface $request, array $headers, Deferred
             $isReplay = (bool) ($request->getOptions()['replay'] ?? false);
             if ($isReplay) {
                 // On replay, we don't need to execute validation handlers
-                $context->getClient()->send(new UpdateResponse(
-                    command: UpdateResponse::COMMAND_VALIDATED,
-                    values: null,
+                $context->getClient()->send(new CommandResponse(
+                    command: self::COMMAND_VALIDATED,
+                    options: ['id' => $updateId],
+                    payloads: null,
                     failure: null,
-                    updateId: $updateId,
                 ));
             } else {
                 $validator = $updateDispatcher->findValidateUpdateHandler($name);
 
                 // Validation will be passed if no validation handler is found
-                $validator === null or $validator($input);
-
-                $context->getClient()->send(new UpdateResponse(
-                    command: UpdateResponse::COMMAND_VALIDATED,
-                    values: null,
+                if ($validator !== null) {
+                    $validator($input);
+                }
+
+                $context->getClient()->send(new CommandResponse(
+                    command: self::COMMAND_VALIDATED,
+                    options: ['id' => $updateId],
+                    payloads: null,
                     failure: null,
-                    updateId: $updateId,
                 ));
             }
         } catch (\Throwable $e) {
             $context->getClient()->send(
-                new UpdateResponse(
-                    command: UpdateResponse::COMMAND_VALIDATED,
-                    values: null,
+                new CommandResponse(
+                    command: self::COMMAND_VALIDATED,
+                    options: ['id' => $updateId],
+                    payloads: null,
                     failure: $e,
-                    updateId: $updateId,
                 ),
             );
             return;
@@ -90,19 +94,19 @@ public function handle(ServerRequestInterface $request, array $headers, Deferred
         $deferred = new Deferred();
         $deferred->promise()->then(
             static function (mixed $value) use ($updateId, $context): void {
-                $context->getClient()->send(new UpdateResponse(
-                    command: UpdateResponse::COMMAND_COMPLETED,
-                    values: EncodedValues::fromValues([$value]),
+                $context->getClient()->send(new CommandResponse(
+                    command: self::COMMAND_COMPLETED,
+                    options: ['id' => $updateId],
+                    payloads: EncodedValues::fromValues([$value]),
                     failure: null,
-                    updateId: $updateId,
                 ));
             },
             static function (\Throwable $err) use ($updateId, $context): void {
-                $context->getClient()->send(new UpdateResponse(
-                    command: UpdateResponse::COMMAND_COMPLETED,
-                    values: null,
+                $context->getClient()->send(new CommandResponse(
+                    command: self::COMMAND_COMPLETED,
+                    options: ['id' => $updateId],
+                    payloads: null,
                     failure: $err,
-                    updateId: $updateId,
                 ));
             },
         );
diff --git a/src/Internal/Transport/Server.php b/src/Internal/Transport/Server.php
index c902232a0..08af54368 100644
--- a/src/Internal/Transport/Server.php
+++ b/src/Internal/Transport/Server.php
@@ -20,10 +20,10 @@
 use Temporal\Plugin\WorkerPluginInterface;
 use Temporal\Worker\Transport\Command\Client\FailedClientResponse;
 use Temporal\Worker\Transport\Command\Client\SuccessClientResponse;
+use Temporal\Worker\Transport\Command\CommandInterface;
 use Temporal\Worker\Transport\Command\FailureResponseInterface;
-use Temporal\Worker\Transport\Command\RequestInterface;
+use Temporal\Worker\Transport\Command\ResponseInterface;
 use Temporal\Worker\Transport\Command\ServerRequestInterface;
-use Temporal\Worker\Transport\Command\SuccessResponseInterface;
 
 /**
  * @psalm-import-type OnMessageHandler from ServerInterface
@@ -57,9 +57,6 @@ public function onMessage(callable $then): void
         $this->onMessage = $then(...);
     }
 
-    /**
-     * @param RequestInterface $request
-     */
     public function dispatch(ServerRequestInterface $request, array $headers): void
     {
         try {
@@ -74,22 +71,30 @@ public function dispatch(ServerRequestInterface $request, array $headers): void
             return;
         }
 
-        $result instanceof PromiseInterface or throw new \BadMethodCallException(\sprintf(
-            self::ERROR_INVALID_RETURN_TYPE,
-            PromiseInterface::class,
-            \get_debug_type($result),
-        ));
+        if (!$result instanceof PromiseInterface) {
+            throw new \BadMethodCallException(\sprintf(
+                self::ERROR_INVALID_RETURN_TYPE,
+                PromiseInterface::class,
+                \get_debug_type($result),
+            ));
+        }
 
         $result->then($this->onFulfilled($request), $this->onRejected($request));
     }
 
     /**
-     * @return \Closure(mixed): SuccessResponseInterface
+     * Routes that need a typed reply command (e.g. {@see \Temporal\Worker\Transport\Command\Client\CommandResponse})
+     * resolve directly with a {@see ResponseInterface} instance and it is
+     * pushed verbatim. Anything else is wrapped as a {@see SuccessClientResponse}.
+     *
+     * @return \Closure(mixed): CommandInterface
      */
     private function onFulfilled(ServerRequestInterface $request): \Closure
     {
-        return function ($result) use ($request) {
-            $response = new SuccessClientResponse($request->getID(), $result);
+        return function ($result) use ($request): CommandInterface {
+            $response = $result instanceof ResponseInterface
+                ? $result
+                : new SuccessClientResponse($request->getID(), $result);
             $this->queue->push($response);
 
             return $response;
diff --git a/src/Internal/Workflow/NexusOperationStub.php b/src/Internal/Workflow/NexusOperationStub.php
new file mode 100644
index 000000000..cbfb4d5a2
--- /dev/null
+++ b/src/Internal/Workflow/NexusOperationStub.php
@@ -0,0 +1,185 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Workflow;
+
+use React\Promise\PromiseInterface;
+use Temporal\DataConverter\EncodedValues;
+use Temporal\DataConverter\Type;
+use Temporal\DataConverter\ValuesInterface;
+use Temporal\Exception\Failure\CanceledFailure;
+use Temporal\Exception\Failure\NexusOperationFailure;
+use Temporal\Interceptor\HeaderInterface;
+use Temporal\Internal\Marshaller\MarshallerInterface;
+use Temporal\Internal\Transport\Request\ExecuteNexusOperation;
+use Temporal\Internal\Transport\Request\GetNexusOperationStarted;
+use Temporal\Nexus\Internal\Headers;
+use Temporal\Worker\Transport\Command\RequestInterface;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationCancellationType;
+use Temporal\Workflow\NexusOperationHandle;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\NexusOperationStubInterface;
+
+class NexusOperationStub implements NexusOperationStubInterface
+{
+    /**
+     * @param MarshallerInterface<array> $marshaller
+     */
+    public function __construct(
+        private readonly MarshallerInterface $marshaller,
+        private readonly NexusOperationOptions $options,
+        private readonly HeaderInterface $header,
+    ) {}
+
+    public function getOptions(): NexusOperationOptions
+    {
+        return $this->options;
+    }
+
+    public function execute(
+        string $operation,
+        array $args = [],
+        Type|string|\ReflectionClass|\ReflectionType|null $returnType = null,
+        array $nexusHeaders = [],
+    ): PromiseInterface {
+        return $this
+            ->start($operation, $args, $returnType, $nexusHeaders)
+            ->then(static fn(NexusOperationHandle $handle): PromiseInterface => $handle->getResult());
+    }
+
+    public function start(
+        string $operation,
+        array $args = [],
+        Type|string|\ReflectionClass|\ReflectionType|null $returnType = null,
+        array $nexusHeaders = [],
+    ): PromiseInterface {
+        $endpoint = $this->options->endpoint;
+        $service = $this->options->service;
+        $this->assertOperationParams($endpoint, $service, $operation);
+
+        $startRequest = new ExecuteNexusOperation(
+            endpoint: $endpoint,
+            service: $service,
+            operation: $operation,
+            args: EncodedValues::fromValues($args),
+            options: $this->marshaller->marshal($this->options),
+            header: $this->header,
+            nexusHeaders: Headers::normalize($nexusHeaders),
+        );
+
+        $startId = $startRequest->getID();
+
+        $cancellable = $this->options->cancellationType !== NexusOperationCancellationType::Abandon;
+
+        $operationToken = '';
+        $resultPromise = $this->normalizeFailure(
+            $this->request($startRequest, cancellable: $cancellable),
+            $endpoint,
+            $service,
+            $operation,
+            $operationToken,
+        );
+        $startedPromise = $this->normalizeFailure(
+            $this->request(new GetNexusOperationStarted($startId)),
+            $endpoint,
+            $service,
+            $operation,
+            $operationToken,
+        );
+
+        return $this->handleFromStarted($startedPromise, $resultPromise, $returnType, $operationToken);
+    }
+
+    protected function request(RequestInterface $request, bool $cancellable = true): PromiseInterface
+    {
+        return Workflow::getCurrentContext()->request($request, $cancellable);
+    }
+
+    private function handleFromStarted(
+        PromiseInterface $startedPromise,
+        PromiseInterface $resultPromise,
+        Type|string|\ReflectionClass|\ReflectionType|null $returnType,
+        string &$operationToken,
+    ): PromiseInterface {
+        return $startedPromise->then(
+            static function (ValuesInterface $values) use (
+                &$operationToken,
+                $resultPromise,
+                $returnType
+            ): NexusOperationHandle {
+                $envelope = $values->getValue(0, NexusStartEnvelope::class);
+                if ($envelope->async) {
+                    $operationToken = $envelope->token;
+                }
+
+                return new NexusOperationHandle(
+                    operationToken: $envelope->async ? $envelope->token : null,
+                    rawResult: $resultPromise,
+                    returnType: $returnType,
+                );
+            },
+            static function (\Throwable $e) use ($resultPromise): never {
+                // Start failed: the handle is never built, so consume the result promise
+                // to keep its rejection from being left unhandled.
+                $resultPromise->then(null, static fn(): null => null);
+                throw $e;
+            },
+        );
+    }
+
+    private function assertOperationParams(string $endpoint, string $service, string $operation): void
+    {
+        if ($endpoint === '') {
+            throw new \InvalidArgumentException(\sprintf(
+                "Nexus stub for %s has no endpoint set. Call NexusOperationOptions::withEndpoint('your-endpoint') before passing options to newNexusServiceStub() or newUntypedNexusOperationStub().",
+                $service !== '' ? "service '{$service}'" : 'this operation',
+            ));
+        }
+        if ($service === '') {
+            throw new \InvalidArgumentException(
+                'Nexus service is empty; call NexusOperationOptions::withService() or pass a #[Service]-annotated interface to newNexusServiceStub()',
+            );
+        }
+        if ($operation === '') {
+            throw new \InvalidArgumentException('Nexus operation name must be a non-empty string');
+        }
+    }
+
+    private function normalizeFailure(
+        PromiseInterface $promise,
+        string $endpoint,
+        string $service,
+        string $operation,
+        string &$operationToken,
+    ): PromiseInterface {
+        return $promise->then(
+            null,
+            static function (\Throwable $e) use ($endpoint, $service, $operation, &$operationToken): never {
+                if ($e instanceof NexusOperationFailure) {
+                    throw $e;
+                }
+                $message = $e instanceof CanceledFailure
+                    ? 'nexus operation cancelled'
+                    : 'nexus operation completed unsuccessfully';
+                throw new NexusOperationFailure(
+                    message: $message,
+                    scheduledEventId: 0,
+                    endpoint: $endpoint,
+                    service: $service,
+                    operation: $operation,
+                    operationToken: $operationToken,
+                    previous: $e,
+                );
+            },
+        );
+    }
+}
diff --git a/src/Internal/Workflow/NexusServiceProxy.php b/src/Internal/Workflow/NexusServiceProxy.php
new file mode 100644
index 000000000..ff3b3c2c1
--- /dev/null
+++ b/src/Internal/Workflow/NexusServiceProxy.php
@@ -0,0 +1,80 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Workflow;
+
+use React\Promise\PromiseInterface;
+use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteNexusOperationInput;
+use Temporal\Interceptor\WorkflowOutboundCallsInterceptor;
+use Temporal\Internal\Declaration\Prototype\NexusOperationPrototype;
+use Temporal\Internal\Declaration\Prototype\NexusServicePrototype;
+use Temporal\Internal\Interceptor\Pipeline;
+use Temporal\Workflow\NexusOperationOptions;
+
+/**
+ * @template-covariant T of object
+ * @mixin T
+ * @internal
+ */
+final class NexusServiceProxy extends Proxy
+{
+    /** @var array<string, NexusOperationPrototype> Keyed by PHP method name. */
+    private readonly array $operationsByMethod;
+
+    /**
+     * @param class-string<T> $class
+     * @param Pipeline<WorkflowOutboundCallsInterceptor, PromiseInterface> $callsInterceptor
+     */
+    public function __construct(
+        private readonly string $class,
+        NexusServicePrototype $prototype,
+        private readonly NexusOperationOptions $options,
+        private readonly WorkflowContext $ctx,
+        private readonly Pipeline $callsInterceptor,
+    ) {
+        $byMethod = [];
+        foreach ($prototype->getOperations() as $operation) {
+            $byMethod[$operation->methodName] = $operation;
+        }
+        $this->operationsByMethod = $byMethod;
+    }
+
+    public function __call(string $method, array $args = []): PromiseInterface
+    {
+        $operation = $this->operationsByMethod[$method] ?? null;
+
+        if ($operation === null) {
+            throw new \BadMethodCallException(\sprintf(
+                'Nexus service "%s" has no operation method "%s". '
+                . 'Did you forget the #[Operation] attribute on the method?',
+                $this->class,
+                $method,
+            ));
+        }
+
+        return $this->callsInterceptor->with(
+            fn(ExecuteNexusOperationInput $input): PromiseInterface => $this->ctx
+                ->newUntypedNexusOperationStub($input->effectiveOptions())
+                ->execute($input->operation, $input->args, $input->returnType, $input->nexusHeaders),
+            /** @see WorkflowOutboundCallsInterceptor::executeNexusOperation() */
+            'executeNexusOperation',
+        )(
+            new ExecuteNexusOperationInput(
+                $this->options->endpoint,
+                $this->options->service,
+                $operation->name,
+                $args,
+                $this->options,
+                $operation->outputType,
+            ),
+        );
+    }
+}
diff --git a/src/Internal/Workflow/NexusStartEnvelope.php b/src/Internal/Workflow/NexusStartEnvelope.php
new file mode 100644
index 000000000..b4f8bead6
--- /dev/null
+++ b/src/Internal/Workflow/NexusStartEnvelope.php
@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Internal\Workflow;
+
+use Temporal\Internal\Marshaller\Meta\Marshal;
+
+/**
+ * Nexus start-handshake outcome pushed by RoadRunner for {@see \Temporal\Internal\Transport\Request\GetNexusOperationStarted}: `$token` is set only when `$async` is true.
+ *
+ * @internal
+ */
+final class NexusStartEnvelope
+{
+    #[Marshal(name: 'async')]
+    public bool $async = false;
+
+    #[Marshal(name: 'token')]
+    public string $token = '';
+}
diff --git a/src/Internal/Workflow/Process/Scope.php b/src/Internal/Workflow/Process/Scope.php
index 8981b3161..52bc7f151 100644
--- a/src/Internal/Workflow/Process/Scope.php
+++ b/src/Internal/Workflow/Process/Scope.php
@@ -24,6 +24,7 @@
 use Temporal\Internal\Declaration\MethodHandler;
 use Temporal\Internal\ServiceContainer;
 use Temporal\Internal\Transport\Request\Cancel;
+use Temporal\Internal\Transport\Request\RejectedOnCancelInterface;
 use Temporal\Internal\Workflow\ScopeContext;
 use Temporal\Internal\Workflow\WorkflowContext;
 use Temporal\Worker\FeatureFlags;
@@ -385,7 +386,10 @@ protected function onRequest(RequestInterface $request, PromiseInterface $promis
             }
 
             if (!$cancellable) {
-                // non-cancellable request
+                if ($request instanceof RejectedOnCancelInterface) {
+                    $client->reject($request, new CanceledFailure('nexus operation cancelled'));
+                }
+
                 return;
             }
 
diff --git a/src/Internal/Workflow/WorkflowContext.php b/src/Internal/Workflow/WorkflowContext.php
index b32c0c9b2..20454e4bc 100644
--- a/src/Internal/Workflow/WorkflowContext.php
+++ b/src/Internal/Workflow/WorkflowContext.php
@@ -35,6 +35,7 @@
 use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteActivityInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteChildWorkflowInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteLocalActivityInput;
+use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteNexusOperationInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\GetVersionInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\PanicInput;
 use Temporal\Interceptor\WorkflowOutboundCalls\SideEffectInput;
@@ -75,6 +76,7 @@
 use Temporal\Workflow\ContinueAsNewOptions;
 use Temporal\Workflow\ExternalWorkflowStubInterface;
 use Temporal\Workflow\Mutex;
+use Temporal\Workflow\NexusOperationOptions;
 use Temporal\Workflow\TimerOptions;
 use Temporal\Workflow\WorkflowContextInterface;
 use Temporal\Workflow\WorkflowExecution;
@@ -471,6 +473,65 @@ public function newActivityStub(
         );
     }
 
+    /**
+     * @template T of object
+     * @param class-string<T> $class
+     * @return NexusServiceProxy<T>
+     */
+    public function newNexusServiceStub(
+        string $class,
+        NexusOperationOptions $options,
+    ): object {
+        $prototype = $this->services->nexusServicesReader->fromClass($class);
+
+        if ($options->service === '') {
+            $options = $options->withService($prototype->getID());
+        }
+
+        return new NexusServiceProxy(
+            $class,
+            $prototype,
+            $options,
+            $this,
+            $this->callsInterceptor,
+        );
+    }
+
+    public function newUntypedNexusOperationStub(
+        NexusOperationOptions $options,
+    ): NexusOperationStub {
+        return new NexusOperationStub(
+            $this->services->marshaller,
+            $options,
+            $this->getHeader(),
+        );
+    }
+
+    public function executeNexusOperation(
+        string $operation,
+        array $args = [],
+        ?NexusOperationOptions $options = null,
+        Type|string|\ReflectionClass|\ReflectionType|null $returnType = null,
+    ): PromiseInterface {
+        $options ??= NexusOperationOptions::new();
+
+        return $this->callsInterceptor->with(
+            fn(ExecuteNexusOperationInput $input): PromiseInterface => $this
+                ->newUntypedNexusOperationStub($input->effectiveOptions())
+                ->execute($input->operation, $input->args, $input->returnType, $input->nexusHeaders),
+            /** @see WorkflowOutboundCallsInterceptor::executeNexusOperation() */
+            'executeNexusOperation',
+        )(new ExecuteNexusOperationInput(
+            $options->endpoint,
+            $options->service,
+            $operation,
+            $args,
+            $options,
+            $returnType,
+            [],
+        ));
+    }
+
     public function timer($interval, ?TimerOptions $options = null): PromiseInterface
     {
         $dateInterval = DateInterval::parse($interval, DateInterval::FORMAT_SECONDS);
diff --git a/src/Nexus/Attribute/AsyncOperation.php b/src/Nexus/Attribute/AsyncOperation.php
new file mode 100644
index 000000000..f6e4d205e
--- /dev/null
+++ b/src/Nexus/Attribute/AsyncOperation.php
@@ -0,0 +1,42 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Attribute;
+
+use Doctrine\Common\Annotations\Annotation\Target;
+use Spiral\Attributes\NamedArgumentConstructor;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\WorkflowHandle;
+
+/**
+ * Marks a method on a {@see Service}-annotated type (interface or class) as an asynchronous
+ * Nexus operation. The method returns a {@see WorkflowHandle} (SDK-managed workflow run) or,
+ * for full manual control, an {@see OperationHandlerInterface} implementation.
+ *
+ * @Annotation
+ * @NamedArgumentConstructor
+ * @Target({ "METHOD" })
+ */
+#[\Attribute(\Attribute::TARGET_METHOD), NamedArgumentConstructor]
+final class AsyncOperation
+{
+    /**
+     * @param string $name Operation name as exposed over the wire. Empty means "use the method name".
+     * @param string $output Wire output type the async operation eventually produces. Empty means "void".
+     * @param string $input Wire input type; used only for {@see OperationHandlerInterface} factories,
+     *        whose zero-parameter signature cannot carry it. Empty means "mixed".
+     */
+    public function __construct(
+        public readonly string $name = '',
+        public readonly string $output = '',
+        public readonly string $input = '',
+    ) {}
+}
diff --git a/src/Nexus/Attribute/Operation.php b/src/Nexus/Attribute/Operation.php
new file mode 100644
index 000000000..a28941851
--- /dev/null
+++ b/src/Nexus/Attribute/Operation.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Attribute;
+
+use Doctrine\Common\Annotations\Annotation\Target;
+use Spiral\Attributes\NamedArgumentConstructor;
+
+/**
+ * Marks a method on a {@see Service}-annotated type (interface or class) as a Nexus operation.
+ *
+ * The method signature defines the operation's input and output types. By default, the
+ * operation name is the method name; override it via {@see self::$name}.
+ *
+ * @Annotation
+ * @NamedArgumentConstructor
+ * @Target({ "METHOD" })
+ */
+#[\Attribute(\Attribute::TARGET_METHOD), NamedArgumentConstructor]
+final class Operation
+{
+    /**
+     * @param string $name Operation name as exposed over the wire. Empty means "use the method name".
+     */
+    public function __construct(
+        public readonly string $name = '',
+    ) {}
+}
diff --git a/src/Nexus/Attribute/Service.php b/src/Nexus/Attribute/Service.php
new file mode 100644
index 000000000..cfc3d2110
--- /dev/null
+++ b/src/Nexus/Attribute/Service.php
@@ -0,0 +1,42 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Attribute;
+
+use Doctrine\Common\Annotations\Annotation\Target;
+use Spiral\Attributes\NamedArgumentConstructor;
+
+/**
+ * Marks a class or interface as a Nexus service.
+ *
+ * The annotated type is the service contract: every method carrying {@see Operation} or
+ * {@see AsyncOperation} declares a separate Nexus operation. The attribute is accepted on
+ * either a `#[Service]`-annotated interface (with a separate impl class implementing it)
+ * or directly on the implementation class — when applied to a class, that class is its own
+ * contract.
+ *
+ * By default, the service name is the type's short name; override it via {@see self::$name}
+ * to decouple the wire contract from the PHP class name.
+ *
+ * @Annotation
+ * @NamedArgumentConstructor
+ * @Target({ "CLASS" })
+ */
+#[\Attribute(\Attribute::TARGET_CLASS), NamedArgumentConstructor]
+final class Service
+{
+    /**
+     * @param string $name Service name as exposed over the wire. Empty means "use the contract's short name".
+     */
+    public function __construct(
+        public readonly string $name = '',
+    ) {}
+}
diff --git a/src/Nexus/Exception/ErrorType.php b/src/Nexus/Exception/ErrorType.php
new file mode 100644
index 000000000..d42d66b43
--- /dev/null
+++ b/src/Nexus/Exception/ErrorType.php
@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Exception;
+
+/**
+ * Nexus handler-error wire types. `Unknown` is a local fallback for an unrecognized incoming
+ * type (never emitted on the wire); every other case is a spec-defined value.
+ *
+ * @see https://github.com/nexus-rpc/api/blob/main/SPEC.md
+ */
+enum ErrorType: string
+{
+    case Unknown = 'UNKNOWN';
+    case BadRequest = 'BAD_REQUEST';
+    case Unauthenticated = 'UNAUTHENTICATED';
+    case Unauthorized = 'UNAUTHORIZED';
+    case NotFound = 'NOT_FOUND';
+    case Conflict = 'CONFLICT';
+    case RequestTimeout = 'REQUEST_TIMEOUT';
+    case ResourceExhausted = 'RESOURCE_EXHAUSTED';
+    case Internal = 'INTERNAL';
+    case NotImplemented = 'NOT_IMPLEMENTED';
+    case Unavailable = 'UNAVAILABLE';
+    case UpstreamTimeout = 'UPSTREAM_TIMEOUT';
+}
diff --git a/src/Nexus/Exception/HandlerException.php b/src/Nexus/Exception/HandlerException.php
new file mode 100644
index 000000000..ece2e9c0f
--- /dev/null
+++ b/src/Nexus/Exception/HandlerException.php
@@ -0,0 +1,73 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Exception;
+
+/**
+ * Thrown from a handler.
+ */
+final class HandlerException extends NexusException
+{
+    public readonly ErrorType $errorType;
+    public readonly RetryBehavior $retryBehavior;
+
+    private function __construct(
+        ErrorType $errorType,
+        string $message,
+        ?\Throwable $cause,
+        RetryBehavior $retryBehavior,
+    ) {
+        $this->errorType = $errorType;
+        $this->retryBehavior = $retryBehavior;
+
+        parent::__construct($message, 0, $cause);
+    }
+
+    public static function create(
+        ErrorType $errorType,
+        string $message,
+        ?\Throwable $cause = null,
+        RetryBehavior $retryBehavior = RetryBehavior::Unspecified,
+    ): self {
+        return new self($errorType, $message, $cause, $retryBehavior);
+    }
+
+    /**
+     * Message is derived from the cause's own message.
+     */
+    public static function fromCause(
+        ErrorType $errorType,
+        \Throwable $cause,
+        RetryBehavior $retryBehavior = RetryBehavior::Unspecified,
+    ): self {
+        $message = $cause->getMessage() !== ''
+            ? "handler error: {$cause->getMessage()}"
+            : 'handler error';
+        return new self($errorType, $message, $cause, $retryBehavior);
+    }
+
+    public function isRetryable(): bool
+    {
+        if ($this->retryBehavior !== RetryBehavior::Unspecified) {
+            return $this->retryBehavior === RetryBehavior::Retryable;
+        }
+
+        return match ($this->errorType) {
+            ErrorType::BadRequest,
+            ErrorType::Unauthenticated,
+            ErrorType::Unauthorized,
+            ErrorType::NotFound,
+            ErrorType::Conflict,
+            ErrorType::NotImplemented => false,
+            default => true,
+        };
+    }
+}
diff --git a/src/Nexus/Exception/InvalidArgumentException.php b/src/Nexus/Exception/InvalidArgumentException.php
new file mode 100644
index 000000000..07feb0753
--- /dev/null
+++ b/src/Nexus/Exception/InvalidArgumentException.php
@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Exception;
+
+class InvalidArgumentException extends NexusException {}
diff --git a/src/Nexus/Exception/NexusException.php b/src/Nexus/Exception/NexusException.php
new file mode 100644
index 000000000..cbbedaf73
--- /dev/null
+++ b/src/Nexus/Exception/NexusException.php
@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Exception;
+
+/**
+ * Root exception for all errors thrown by the Nexus RPC SDK.
+ *
+ * Catch this to intercept any SDK-originated error without coupling to specific subclasses.
+ */
+class NexusException extends \RuntimeException {}
diff --git a/src/Nexus/Exception/OperationException.php b/src/Nexus/Exception/OperationException.php
new file mode 100644
index 000000000..338159d84
--- /dev/null
+++ b/src/Nexus/Exception/OperationException.php
@@ -0,0 +1,50 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Exception;
+
+use Temporal\Nexus\OperationState;
+
+final class OperationException extends NexusException
+{
+    private function __construct(
+        public readonly OperationState $state,
+        string $message,
+        ?\Throwable $cause = null,
+    ) {
+        parent::__construct($message, 0, $cause);
+    }
+
+    public static function failed(string $message, ?\Throwable $cause = null): self
+    {
+        return new self(OperationState::Failed, $message, $cause);
+    }
+
+    public static function failedFromCause(\Throwable $cause): self
+    {
+        return new self(OperationState::Failed, self::messageFromCause($cause, 'operation failed'), $cause);
+    }
+
+    public static function canceled(string $message, ?\Throwable $cause = null): self
+    {
+        return new self(OperationState::Canceled, $message, $cause);
+    }
+
+    public static function canceledFromCause(\Throwable $cause): self
+    {
+        return new self(OperationState::Canceled, self::messageFromCause($cause, 'operation canceled'), $cause);
+    }
+
+    private static function messageFromCause(\Throwable $cause, string $fallback): string
+    {
+        return $cause->getMessage() !== '' ? $cause->getMessage() : $fallback;
+    }
+}
diff --git a/src/Nexus/Exception/RetryBehavior.php b/src/Nexus/Exception/RetryBehavior.php
new file mode 100644
index 000000000..cfd30ee63
--- /dev/null
+++ b/src/Nexus/Exception/RetryBehavior.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Exception;
+
+/**
+ * Allows handlers to explicitly set the retry behavior of a {@see HandlerException}.
+ */
+enum RetryBehavior: string
+{
+    case Unspecified = 'UNSPECIFIED';
+    case Retryable = 'RETRYABLE';
+    case NonRetryable = 'NON_RETRYABLE';
+}
diff --git a/src/Nexus/Handler/AsyncOperationStartResult.php b/src/Nexus/Handler/AsyncOperationStartResult.php
new file mode 100644
index 000000000..09eb95d9e
--- /dev/null
+++ b/src/Nexus/Handler/AsyncOperationStartResult.php
@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+
+/**
+ * Construct via {@see OperationStartResult::async()}.
+ *
+ * @extends OperationStartResult<never>
+ */
+final readonly class AsyncOperationStartResult extends OperationStartResult
+{
+    /**
+     * @internal
+     */
+    public function __construct(public OperationInfo $info)
+    {
+        if ($info->state !== OperationState::Running) {
+            throw new InvalidArgumentException(\sprintf(
+                'Async operation start must report a running operation, got state "%s".',
+                $info->state->value,
+            ));
+        }
+
+        parent::__construct();
+    }
+}
diff --git a/src/Nexus/Handler/ClosureMethodCancellationListener.php b/src/Nexus/Handler/ClosureMethodCancellationListener.php
new file mode 100644
index 000000000..903ec33fb
--- /dev/null
+++ b/src/Nexus/Handler/ClosureMethodCancellationListener.php
@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler;
+
+final class ClosureMethodCancellationListener implements MethodCancellationListenerInterface
+{
+    private function __construct(
+        private readonly \Closure $closure,
+    ) {}
+
+    public static function fromCallable(callable $callable): self
+    {
+        return new self($callable(...));
+    }
+
+    public function cancelled(): void
+    {
+        ($this->closure)();
+    }
+}
diff --git a/src/Nexus/Handler/HeaderCollection.php b/src/Nexus/Handler/HeaderCollection.php
new file mode 100644
index 000000000..6a1e9fcee
--- /dev/null
+++ b/src/Nexus/Handler/HeaderCollection.php
@@ -0,0 +1,49 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler;
+
+use Temporal\Nexus\Internal\Headers;
+
+/**
+ * Case-insensitive string map. Keys are normalized to lowercase (last wins).
+ */
+final class HeaderCollection
+{
+    /** @var array<string, string> Lowercased keys. */
+    private array $headers;
+
+    /**
+     * @param array<string, string> $initial
+     */
+    public function __construct(array $initial = [])
+    {
+        $this->headers = Headers::normalize($initial);
+    }
+
+    public function get(string $name): ?string
+    {
+        return $this->headers[\strtolower($name)] ?? null;
+    }
+
+    public function has(string $name): bool
+    {
+        return \array_key_exists(\strtolower($name), $this->headers);
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public function all(): array
+    {
+        return $this->headers;
+    }
+}
diff --git a/src/Nexus/Handler/Internal/HandlerInterface.php b/src/Nexus/Handler/Internal/HandlerInterface.php
new file mode 100644
index 000000000..95a235a73
--- /dev/null
+++ b/src/Nexus/Handler/Internal/HandlerInterface.php
@@ -0,0 +1,55 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler\Internal;
+
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\DataConverter\ValuesInterface;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\OperationException;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\NexusOperationContext;
+
+/**
+ * @internal
+ */
+interface HandlerInterface
+{
+    /**
+     * @return OperationStartResult<ValuesInterface>
+     *
+     * @throws OperationException
+     * @throws HandlerException
+     */
+    public function startOperation(
+        OperationContext $context,
+        OperationStartDetails $details,
+        ValuesInterface $input,
+        ?WorkflowClientInterface $workflowClient,
+        NexusOperationContext $operationContext,
+    ): OperationStartResult;
+
+    /**
+     * Idempotent per Nexus spec: repeat or already-terminal cancels must return successfully;
+     * throw {@see HandlerException} only for genuine routing/permission/transport errors.
+     *
+     * @throws HandlerException
+     */
+    public function cancelOperation(
+        OperationContext $context,
+        OperationCancelDetails $details,
+        ?WorkflowClientInterface $workflowClient,
+        NexusOperationContext $operationContext,
+    ): void;
+}
diff --git a/src/Nexus/Handler/Internal/MethodOperationHandler.php b/src/Nexus/Handler/Internal/MethodOperationHandler.php
new file mode 100644
index 000000000..be3c80107
--- /dev/null
+++ b/src/Nexus/Handler/Internal/MethodOperationHandler.php
@@ -0,0 +1,55 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler\Internal;
+
+use Temporal\Internal\Declaration\Prototype\NexusOperationPrototype;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\WorkflowRunOperation;
+
+/**
+ * @internal
+ * @implements OperationHandlerInterface<mixed, mixed>
+ */
+final class MethodOperationHandler implements OperationHandlerInterface
+{
+    public function __construct(
+        private readonly object $instance,
+        private readonly \ReflectionMethod $startMethod,
+        private readonly NexusOperationPrototype $operation,
+    ) {}
+
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        $args = $this->startMethod->getNumberOfParameters() === 0 ? [] : [$param];
+        $result = $this->startMethod->invoke($this->instance, ...$args);
+
+        if ($this->operation->async) {
+            return OperationStartResult::async(WorkflowRunStarter::start($result, $details));
+        }
+
+        return OperationStartResult::sync($result);
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {
+        WorkflowRunOperation::cancel($details->operationToken);
+    }
+}
diff --git a/src/Nexus/Handler/Internal/ServiceHandler.php b/src/Nexus/Handler/Internal/ServiceHandler.php
new file mode 100644
index 000000000..6304aefe6
--- /dev/null
+++ b/src/Nexus/Handler/Internal/ServiceHandler.php
@@ -0,0 +1,258 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler\Internal;
+
+use Temporal\Api\Common\V1\Payloads;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\DataConverter\DataConverterInterface;
+use Temporal\DataConverter\Type;
+use Temporal\DataConverter\EncodedValues;
+use Temporal\DataConverter\ValuesInterface;
+use Temporal\Interceptor\NexusOperationInbound\CancelOperationInput;
+use Temporal\Interceptor\NexusOperationInbound\StartOperationInput;
+use Temporal\Interceptor\NexusOperationInboundCallsInterceptor;
+use Temporal\Interceptor\NexusOperationOutboundCallsInterceptor;
+use Temporal\Interceptor\PipelineProvider;
+use Temporal\Interceptor\SimplePipelineProvider;
+use Temporal\Internal\Declaration\NexusServiceInstance;
+use Temporal\Internal\Nexus\NexusContext;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\Handler\SyncOperationStartResult;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\NexusOperationContext;
+
+/**
+ * @internal
+ */
+final class ServiceHandler implements HandlerInterface
+{
+    /**
+     * @param array<string, NexusServiceInstance> $instances
+     */
+    private function __construct(
+        private readonly array $instances,
+        private readonly DataConverterInterface $dataConverter,
+        private readonly PipelineProvider $interceptorProvider = new SimplePipelineProvider(),
+    ) {}
+
+    /**
+     * @param NexusServiceInstance[] $instances
+     */
+    public static function create(
+        DataConverterInterface $dataConverter,
+        array $instances,
+        PipelineProvider $interceptorProvider = new SimplePipelineProvider(),
+    ): self {
+        if (\count($instances) === 0) {
+            throw new InvalidArgumentException('No service instances defined');
+        }
+
+        $instancesByName = [];
+        foreach ($instances as $instance) {
+            $name = $instance->prototype->getID();
+            if (isset($instancesByName[$name])) {
+                throw new InvalidArgumentException(
+                    "Multiple instances registered for service name '{$name}'",
+                );
+            }
+            $instancesByName[$name] = $instance;
+        }
+
+        return new self($instancesByName, $dataConverter, $interceptorProvider);
+    }
+
+    public function startOperation(
+        OperationContext $context,
+        OperationStartDetails $details,
+        ValuesInterface $input,
+        ?WorkflowClientInterface $workflowClient,
+        NexusOperationContext $operationContext,
+    ): OperationStartResult {
+        [$instance, $handler] = $this->resolveHandler($context);
+
+        $operations = $instance->prototype->getOperations();
+        $definition = $operations[$context->operation];
+
+        $result = $this->dispatch(
+            new NexusContext(
+                operation: self::publicOperationContext($operationContext),
+                workflowClient: $workflowClient,
+                current: $context,
+                startDetails: $details,
+                outboundPipeline: $this->interceptorProvider
+                    ->getPipeline(NexusOperationOutboundCallsInterceptor::class),
+            ),
+            static fn(StartOperationInput $input): OperationStartResult => $handler->start(
+                $input->operationContext,
+                $input->startDetails,
+                $input->input instanceof ValuesInterface
+                    ? self::decodeInput($input->input, $input->operationContext, $definition->inputType)
+                    : $input->input,
+            ),
+            'startOperation',
+            new StartOperationInput($context, $details, $input),
+        );
+
+        \assert($result instanceof OperationStartResult);
+
+        if (!$result instanceof SyncOperationStartResult) {
+            return $result;
+        }
+
+        return OperationStartResult::sync(
+            $this->encodeResult(
+                $result->value,
+                $context,
+                $definition->outputType,
+            ),
+        );
+    }
+
+    public function cancelOperation(
+        OperationContext $context,
+        OperationCancelDetails $details,
+        ?WorkflowClientInterface $workflowClient,
+        NexusOperationContext $operationContext,
+    ): void {
+        [$instance, $handler] = $this->resolveHandler($context);
+
+        $definition = $instance->prototype->getOperations()[$context->operation];
+        if (!$definition->async) {
+            throw HandlerException::create(
+                ErrorType::NotImplemented,
+                \sprintf(
+                    'Operation %s/%s is synchronous and cannot be cancelled',
+                    $context->service,
+                    $context->operation,
+                ),
+            );
+        }
+
+        $this->dispatch(
+            new NexusContext(
+                operation: self::publicOperationContext($operationContext),
+                workflowClient: $workflowClient,
+                current: $context,
+                cancelDetails: $details,
+                outboundPipeline: $this->interceptorProvider
+                    ->getPipeline(NexusOperationOutboundCallsInterceptor::class),
+            ),
+            static function (CancelOperationInput $input) use ($handler): void {
+                $handler->cancel($input->operationContext, $input->cancelDetails);
+            },
+            'cancelOperation',
+            new CancelOperationInput($context, $details),
+        );
+    }
+
+    private static function publicOperationContext(NexusOperationContext $operationContext): ?NexusOperationContext
+    {
+        if ($operationContext->namespace === '' || $operationContext->taskQueue === '') {
+            return null;
+        }
+        return $operationContext;
+    }
+
+    private static function decodeInput(
+        ValuesInterface $input,
+        OperationContext $context,
+        Type $inputType,
+    ): mixed {
+        try {
+            return $inputType->getName() === Type::TYPE_VOID
+                ? null
+                : $input->getValue(0, $inputType);
+        } catch (\Throwable $e) {
+            throw HandlerException::create(
+                ErrorType::BadRequest,
+                \sprintf(
+                    'Failed deserializing input for %s/%s as %s: %s',
+                    $context->service,
+                    $context->operation,
+                    $inputType->getName(),
+                    $e->getMessage(),
+                ),
+                $e,
+            );
+        }
+    }
+
+    /**
+     * @param non-empty-string $method
+     */
+    private function dispatch(NexusContext $dispatchContext, \Closure $terminal, string $method, object $input): mixed
+    {
+        Nexus::setCurrentContext($dispatchContext);
+        try {
+            return $this->interceptorProvider
+                ->getPipeline(NexusOperationInboundCallsInterceptor::class)
+                ->with($terminal, $method)($input);
+        } finally {
+            Nexus::setCurrentContext(null);
+        }
+    }
+
+    /**
+     * @return array{NexusServiceInstance, OperationHandlerInterface}
+     */
+    private function resolveHandler(OperationContext $context): array
+    {
+        $instance = $this->instances[$context->service] ?? null;
+        if ($instance === null) {
+            throw HandlerException::create(
+                ErrorType::NotFound,
+                "Unrecognized service '{$context->service}'",
+            );
+        }
+
+        $handler = $instance->operationHandlers[$context->operation] ?? null;
+        if ($handler === null) {
+            throw HandlerException::create(
+                ErrorType::NotFound,
+                "Service '{$context->service}' has no operation '{$context->operation}'",
+            );
+        }
+
+        return [$instance, $handler];
+    }
+
+    private function encodeResult(
+        mixed $result,
+        OperationContext $context,
+        Type $outputType,
+    ): ValuesInterface {
+        try {
+            $payload = $this->dataConverter->toPayload($result);
+            $payloads = new Payloads(['payloads' => [$payload]]);
+            return EncodedValues::fromPayloads($payloads, $this->dataConverter);
+        } catch (\Throwable $e) {
+            throw HandlerException::create(
+                ErrorType::Internal,
+                \sprintf(
+                    'Failed serializing result for %s/%s as %s: %s',
+                    $context->service,
+                    $context->operation,
+                    $outputType->getName(),
+                    $e->getMessage(),
+                ),
+                $e,
+            );
+        }
+    }
+}
diff --git a/src/Nexus/Handler/Internal/WorkflowRunStarter.php b/src/Nexus/Handler/Internal/WorkflowRunStarter.php
new file mode 100644
index 000000000..5be178ee6
--- /dev/null
+++ b/src/Nexus/Handler/Internal/WorkflowRunStarter.php
@@ -0,0 +1,111 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler\Internal;
+
+use Temporal\Api\Common\V1\Link\WorkflowEvent;
+use Temporal\Api\Common\V1\Link\WorkflowEvent\EventReference;
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Internal\Client\OnConflictOptions;
+use Temporal\Internal\Nexus\NexusLinkConverter;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Header;
+use Temporal\Nexus\Internal\Headers;
+use Temporal\Nexus\Internal\WorkflowRunOperationToken;
+use Temporal\Nexus\Link;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Worker\WorkerFactoryInterface;
+use Temporal\Workflow\CompletionCallback;
+use Temporal\Workflow\WorkflowExecution;
+
+/**
+ * Starts the backing workflow for a {@see WorkflowHandle} returned from an #[AsyncOperation] method.
+ *
+ * @internal
+ */
+final class WorkflowRunStarter
+{
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    public static function start(WorkflowHandle $handle, OperationStartDetails $details): OperationInfo
+    {
+        $client = Nexus::getWorkflowClient();
+        $info = Nexus::getOperationContext();
+
+        $options = $handle->options;
+        if ($options->workflowId === '') {
+            throw new \LogicException(\sprintf(
+                'Async Nexus operation: workflow ID is required for %s — '
+                . 'set it via WorkflowOptions::withWorkflowId($details->requestId) inside your handler.',
+                $handle->workflowClass,
+            ));
+        }
+
+        // Default task queue to the handler's queue; avoids silent hang on `default`.
+        if ($options->taskQueue === WorkerFactoryInterface::DEFAULT_TASK_QUEUE) {
+            $options = $options->withTaskQueue($info->taskQueue);
+        }
+
+        $token = WorkflowRunOperationToken::generate(
+            $info->namespace,
+            $options->workflowId,
+        );
+
+        if ($details->callbackUrl !== null && $details->callbackUrl !== '') {
+            $headers = $details->callbackHeaders;
+            $present = Headers::normalize($headers);
+            // Send both header names for pre/post-1.27 server compatibility.
+            if (!\array_key_exists(\strtolower(Header::OPERATION_TOKEN), $present)) {
+                $headers[Header::OPERATION_TOKEN] = $token;
+            }
+            if (!\array_key_exists(\strtolower(Header::OPERATION_ID), $present)) {
+                $headers[Header::OPERATION_ID] = $token;
+            }
+
+            $callback = CompletionCallback::fromNexusLinks($details->callbackUrl, $headers, $details->links);
+            $options = $options->withCompletionCallbacks($callback);
+        }
+
+        $options = $options
+            ->withLinks($details->links)
+            ->withOnConflictOptionsInternal(new OnConflictOptions())
+        // Pin requestId so retried Nexus starts dedupe server-side.
+            ->withRequestId($details->requestId);
+
+        $stub = $client->newWorkflowStub($handle->workflowClass, $options);
+        $run = $client->start($stub, ...$handle->args);
+
+        Nexus::getCurrentOperationContext()
+            ->links
+            ->add(self::buildStartedEventSelfLink($info->namespace, $run->getExecution()));
+
+        return new OperationInfo($token, OperationState::Running);
+    }
+
+    private static function buildStartedEventSelfLink(string $namespace, WorkflowExecution $execution): Link
+    {
+        $event = (new WorkflowEvent())
+            ->setNamespace($namespace)
+            ->setWorkflowId($execution->getID())
+            ->setRunId($execution->getRunID() ?? '')
+            ->setEventRef(
+                (new EventReference())
+                    ->setEventType(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED),
+            );
+        return NexusLinkConverter::workflowEventToNexusLink($event);
+    }
+}
diff --git a/src/Nexus/Handler/LinkCollection.php b/src/Nexus/Handler/LinkCollection.php
new file mode 100644
index 000000000..35c4367ce
--- /dev/null
+++ b/src/Nexus/Handler/LinkCollection.php
@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler;
+
+use Temporal\Nexus\Link;
+
+/**
+ * Mutable. Created by transport, filled by handler/middleware, read by
+ * transport after the handler returns.
+ */
+final class LinkCollection
+{
+    /** @var list<Link> */
+    private array $links;
+
+    /**
+     * @param list<Link> $initial
+     */
+    public function __construct(array $initial = [])
+    {
+        Link::assertAll($initial, 'LinkCollection: initial');
+        $this->links = \array_values($initial);
+    }
+
+    public function add(Link ...$links): void
+    {
+        foreach ($links as $link) {
+            $this->links[] = $link;
+        }
+    }
+
+    /**
+     * @return list<Link>
+     */
+    public function all(): array
+    {
+        return $this->links;
+    }
+}
diff --git a/src/Nexus/Handler/MethodCancellationListenerInterface.php b/src/Nexus/Handler/MethodCancellationListenerInterface.php
new file mode 100644
index 000000000..a86270fa3
--- /dev/null
+++ b/src/Nexus/Handler/MethodCancellationListenerInterface.php
@@ -0,0 +1,26 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler;
+
+/**
+ * Listener for handler-method cancellation (not Nexus operation cancel).
+ * Object form (not Closure) so it can be removed by identity. Must be
+ * non-blocking and must not throw.
+ */
+interface MethodCancellationListenerInterface
+{
+    /**
+     * Invoked exactly once. To get the reason, read it from the owning
+     * {@see MethodCanceller}.
+     */
+    public function cancelled(): void;
+}
diff --git a/src/Nexus/Handler/MethodCanceller.php b/src/Nexus/Handler/MethodCanceller.php
new file mode 100644
index 000000000..690fc7f2c
--- /dev/null
+++ b/src/Nexus/Handler/MethodCanceller.php
@@ -0,0 +1,94 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler;
+
+use Temporal\Worker\Environment\EnvironmentInterface;
+
+/**
+ * Idempotent cancellation of an in-flight handler *method* (not the Nexus
+ * operation). Optional `$deadline` auto-trips on the next inspection.
+ * Listeners notified once, by identity.
+ */
+final class MethodCanceller
+{
+    private ?string $reason = null;
+
+    /** @var \SplObjectStorage<MethodCancellationListenerInterface, null> */
+    private readonly \SplObjectStorage $listeners;
+
+    public function __construct(
+        private readonly EnvironmentInterface $env,
+        private readonly ?\DateTimeImmutable $deadline = null,
+    ) {
+        $this->listeners = new \SplObjectStorage();
+    }
+
+    public function isCancelled(): bool
+    {
+        $this->checkDeadline();
+        return $this->reason !== null;
+    }
+
+    public function getReason(): ?string
+    {
+        $this->checkDeadline();
+        return $this->reason;
+    }
+
+    /**
+     * Idempotent. Listeners run in registration order. Not reentrant.
+     */
+    public function cancel(string $reason): void
+    {
+        if ($this->reason !== null) {
+            return;
+        }
+        $this->reason = $reason;
+        foreach ($this->listeners as $listener) {
+            $listener->cancelled();
+        }
+    }
+
+    /**
+     * If already cancelled, the listener is invoked synchronously and not stored.
+     */
+    public function addListener(MethodCancellationListenerInterface $listener): void
+    {
+        $this->checkDeadline();
+        if ($this->reason !== null) {
+            $listener->cancelled();
+            return;
+        }
+        $this->listeners->offsetSet($listener);
+    }
+
+    public function removeListener(MethodCancellationListenerInterface $listener): void
+    {
+        $this->listeners->offsetUnset($listener);
+    }
+
+    private static function formatDeadlineReason(\DateTimeImmutable $deadline): string
+    {
+        return \sprintf('deadline exceeded (%s)', $deadline->format(\DATE_ATOM));
+    }
+
+    private function checkDeadline(): void
+    {
+        if ($this->reason !== null || $this->deadline === null) {
+            return;
+        }
+        if ($this->deadline > $this->env->now()) {
+            return;
+        }
+        $this->cancel(self::formatDeadlineReason($this->deadline));
+    }
+}
diff --git a/src/Nexus/Handler/OperationCancelDetails.php b/src/Nexus/Handler/OperationCancelDetails.php
new file mode 100644
index 000000000..0c55efbb7
--- /dev/null
+++ b/src/Nexus/Handler/OperationCancelDetails.php
@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler;
+
+use Temporal\Nexus\Validation\OperationTokenValidator;
+
+final class OperationCancelDetails
+{
+    public function __construct(
+        public readonly string $operationToken,
+    ) {
+        OperationTokenValidator::assert($operationToken);
+    }
+}
diff --git a/src/Nexus/Handler/OperationContext.php b/src/Nexus/Handler/OperationContext.php
new file mode 100644
index 000000000..f8c065d87
--- /dev/null
+++ b/src/Nexus/Handler/OperationContext.php
@@ -0,0 +1,77 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler;
+
+use Temporal\Nexus\Link;
+use Temporal\Worker\Environment\EnvironmentInterface;
+
+/**
+ * Context for operation handling.
+ */
+final class OperationContext
+{
+    public readonly HeaderCollection $headers;
+    public readonly LinkCollection $links;
+    private readonly ?MethodCanceller $methodCanceller;
+
+    /**
+     * @param array<string, string>|HeaderCollection $headers Reused if a collection, wrapped if an array (keys lowercased).
+     * @param list<Link>|LinkCollection $links Reused if a collection, wrapped if a list.
+     */
+    public function __construct(
+        public readonly string $service,
+        public readonly string $operation,
+        EnvironmentInterface $env,
+        array|HeaderCollection $headers = [],
+        public readonly ?\DateTimeImmutable $deadline = null,
+        array|LinkCollection $links = [],
+        ?MethodCanceller $methodCanceller = null,
+    ) {
+        $this->headers = $headers instanceof HeaderCollection ? $headers : new HeaderCollection($headers);
+        $this->links = $links instanceof LinkCollection ? $links : new LinkCollection($links);
+        $this->methodCanceller = $methodCanceller
+            ?? ($deadline !== null ? new MethodCanceller($env, $deadline) : null);
+    }
+
+    /**
+     * True if the canceller fired or the deadline has passed. Not the same as
+     * Nexus operation cancellation.
+     */
+    public function isMethodCancelled(): bool
+    {
+        return $this->methodCanceller?->isCancelled() === true;
+    }
+
+    /**
+     * Reason from {@see MethodCanceller::cancel()} or `"deadline exceeded (...)"`.
+     */
+    public function getMethodCancellationReason(): ?string
+    {
+        return $this->methodCanceller?->getReason();
+    }
+
+    /**
+     * No-op when no canceller (and no deadline) attached. If already
+     * cancelled, the listener runs synchronously here.
+     */
+    public function addMethodCancellationListener(MethodCancellationListenerInterface $listener): self
+    {
+        $this->methodCanceller?->addListener($listener);
+        return $this;
+    }
+
+    public function removeMethodCancellationListener(MethodCancellationListenerInterface $listener): self
+    {
+        $this->methodCanceller?->removeListener($listener);
+        return $this;
+    }
+}
diff --git a/src/Nexus/Handler/OperationHandlerInterface.php b/src/Nexus/Handler/OperationHandlerInterface.php
new file mode 100644
index 000000000..0ba267cc0
--- /dev/null
+++ b/src/Nexus/Handler/OperationHandlerInterface.php
@@ -0,0 +1,49 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler;
+
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\OperationException;
+
+/**
+ * Full control over a Nexus operation: one object owns both start and cancel.
+ *
+ * Return an implementation from an `#[AsyncOperation]` method with no parameters
+ * to register a manual operation (e.g. backed by an external system). The
+ * factory method is invoked once at worker registration.
+ *
+ * @template T The parameter type of the operation.
+ * @template R The return type of the operation.
+ */
+interface OperationHandlerInterface
+{
+    /**
+     * @param T|null $param
+     * @return OperationStartResult<R>
+     *
+     * @throws OperationException
+     * @throws HandlerException
+     */
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult;
+
+    /**
+     * @throws HandlerException
+     */
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void;
+}
diff --git a/src/Nexus/Handler/OperationStartDetails.php b/src/Nexus/Handler/OperationStartDetails.php
new file mode 100644
index 000000000..b6358ccb2
--- /dev/null
+++ b/src/Nexus/Handler/OperationStartDetails.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Link;
+
+final class OperationStartDetails
+{
+    /**
+     * @param array<string, string> $callbackHeaders Headers to attach as-is on
+     *        the async callback POST. Transport must strip the inbound
+     *        `Nexus-Callback-` prefix first (see {@see \Temporal\Nexus\Header::CALLBACK_PREFIX}).
+     * @param Link[] $links
+     */
+    public function __construct(
+        public readonly string $requestId,
+        public readonly ?string $callbackUrl = null,
+        public readonly array $callbackHeaders = [],
+        public readonly array $links = [],
+    ) {
+        if ($requestId === '') {
+            throw new InvalidArgumentException('OperationStartDetails requires a non-empty requestId');
+        }
+        Link::assertAll($links, 'OperationStartDetails: links');
+    }
+}
diff --git a/src/Nexus/Handler/OperationStartResult.php b/src/Nexus/Handler/OperationStartResult.php
new file mode 100644
index 000000000..7a81c7208
--- /dev/null
+++ b/src/Nexus/Handler/OperationStartResult.php
@@ -0,0 +1,43 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler;
+
+use Temporal\Nexus\OperationInfo;
+
+/**
+ * Sealed: every instance is {@see SyncOperationStartResult} or
+ * {@see AsyncOperationStartResult}. Use {@see self::sync()} / {@see self::async()}.
+ *
+ * @template R
+ */
+abstract readonly class OperationStartResult
+{
+    /**
+     * @internal
+     */
+    protected function __construct() {}
+
+    /**
+     * @template T
+     * @param T|null $value
+     * @return SyncOperationStartResult<T>
+     */
+    public static function sync(mixed $value = null): SyncOperationStartResult
+    {
+        return new SyncOperationStartResult($value);
+    }
+
+    public static function async(OperationInfo $info): AsyncOperationStartResult
+    {
+        return new AsyncOperationStartResult($info);
+    }
+}
diff --git a/src/Nexus/Handler/SyncOperationStartResult.php b/src/Nexus/Handler/SyncOperationStartResult.php
new file mode 100644
index 000000000..ec42d389c
--- /dev/null
+++ b/src/Nexus/Handler/SyncOperationStartResult.php
@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Handler;
+
+/**
+ * Construct via {@see OperationStartResult::sync()}, not `new`.
+ *
+ * @template R
+ * @extends OperationStartResult<R>
+ */
+final readonly class SyncOperationStartResult extends OperationStartResult
+{
+    /**
+     * @internal
+     * @param R|null $value
+     */
+    public function __construct(
+        public mixed $value,
+    ) {
+        parent::__construct();
+    }
+}
diff --git a/src/Nexus/Header.php b/src/Nexus/Header.php
new file mode 100644
index 000000000..6ed2cf339
--- /dev/null
+++ b/src/Nexus/Header.php
@@ -0,0 +1,126 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus;
+
+use Temporal\Internal\Support\DateInterval;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+
+/**
+ * Well-known Nexus header names + small utilities. Values are wire-level keys.
+ * Use {@see self::get()} for case-insensitive lookup against lowercased maps.
+ *
+ * @see https://github.com/nexus-rpc/api/blob/main/SPEC.md
+ */
+final class Header
+{
+    /** Total time per HTTP request, format `<number><ms|s|m>`. */
+    public const REQUEST_TIMEOUT = 'Request-Timeout';
+
+    /** Total time per Nexus operation (may span callbacks). Same format as {@see self::REQUEST_TIMEOUT}. */
+    public const OPERATION_TIMEOUT = 'Operation-Timeout';
+
+    /** @deprecated Use {@see self::OPERATION_TOKEN}. */
+    public const OPERATION_ID = 'Nexus-Operation-Id';
+
+    /** Async operation token returned from StartOperation. */
+    public const OPERATION_TOKEN = 'Nexus-Operation-Token';
+
+    /** IMF-fixdate (RFC 9110 §5.6.7) timestamp; optional on async callback POST (defaults to reception time). */
+    public const OPERATION_START_TIME = 'Nexus-Operation-Start-Time';
+
+    /** RFC 3339 ms-precision timestamp; required on async callback POST. */
+    public const OPERATION_CLOSE_TIME = 'Nexus-Operation-Close-Time';
+
+    /**
+     * Terminal state on callback POST. One of {@see OperationState} values.
+     * Deprecated on `424 Failed Dependency` — modern callers read the body.
+     */
+    public const OPERATION_STATE = 'Nexus-Operation-State';
+
+    /** Caller-provided opaque non-empty id for retry de-duplication. */
+    public const REQUEST_ID = 'Nexus-Request-Id';
+
+    /** RFC 8288 link header; `<uri>; type="..."`. May repeat. */
+    public const LINK = 'Nexus-Link';
+
+    /**
+     * Prefix on caller headers that the handler must forward (with prefix
+     * stripped) on the async callback POST. Compare case-insensitively.
+     */
+    public const CALLBACK_PREFIX = 'Nexus-Callback-';
+
+    /** URL the handler POSTs to on async-operation terminal state. */
+    public const CALLBACK_URL = self::CALLBACK_PREFIX . 'Url';
+
+    /** Inbound name of the opaque auth token; outbound it is sent as `Token: ...` (secret). */
+    public const CALLBACK_TOKEN = self::CALLBACK_PREFIX . 'Token';
+
+    /** Standard HTTP `Content-Type` header. */
+    public const CONTENT_TYPE = 'Content-Type';
+
+    /** Required `Content-Type` for spec JSON envelopes (see {@see \Temporal\Nexus\OperationInfo} and the Nexus `Failure` shape). */
+    public const CONTENT_TYPE_JSON = 'application/json';
+
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    /**
+     * Case-insensitive lookup over a lowercase-normalized header map.
+     *
+     * @param array<string, string> $headers Must be lowercase-normalized.
+     */
+    public static function get(array $headers, string $name): ?string
+    {
+        return $headers[\strtolower($name)] ?? null;
+    }
+
+    /**
+     * Parse `"30s"` / `"250ms"` / `"2m"`. Empty → null.
+     *
+     * @throws InvalidArgumentException
+     */
+    public static function parseTimeout(string $value): ?\DateInterval
+    {
+        $trimmed = \trim($value);
+        if ($trimmed === '') {
+            return null;
+        }
+
+        if (!\preg_match('/^[+-]?\d/', $trimmed)) {
+            throw new InvalidArgumentException("Invalid Nexus timeout '{$value}'");
+        }
+
+        try {
+            return DateInterval::parse($trimmed, DateInterval::FORMAT_SECONDS);
+        } catch (\Throwable $e) {
+            throw new InvalidArgumentException("Invalid Nexus timeout '{$value}'", 0, $e);
+        }
+    }
+
+    /**
+     * `$now + parseTimeout($value)`. Empty → null. `$now` defaults to UTC now.
+     *
+     * @throws InvalidArgumentException
+     */
+    public static function deadlineFromTimeout(
+        string $value,
+        ?\DateTimeImmutable $now = null,
+    ): ?\DateTimeImmutable {
+        $interval = self::parseTimeout($value);
+        if ($interval === null) {
+            return null;
+        }
+        return ($now ?? new \DateTimeImmutable('now', new \DateTimeZone('UTC')))->add($interval);
+    }
+}
diff --git a/src/Nexus/Internal/Failure/NexusFailureConverter.php b/src/Nexus/Internal/Failure/NexusFailureConverter.php
new file mode 100644
index 000000000..e6a056ac6
--- /dev/null
+++ b/src/Nexus/Internal/Failure/NexusFailureConverter.php
@@ -0,0 +1,35 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Internal\Failure;
+
+use Temporal\Api\Enums\V1\NexusHandlerErrorRetryBehavior;
+use Temporal\Nexus\Exception\RetryBehavior;
+
+/**
+ * @internal
+ */
+final class NexusFailureConverter
+{
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    public static function mapRetryBehavior(RetryBehavior $behavior): int
+    {
+        return match ($behavior) {
+            RetryBehavior::Retryable => NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE,
+            RetryBehavior::NonRetryable => NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE,
+            RetryBehavior::Unspecified => NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_UNSPECIFIED,
+        };
+    }
+}
diff --git a/src/Nexus/Internal/Headers.php b/src/Nexus/Internal/Headers.php
new file mode 100644
index 000000000..6893fb31e
--- /dev/null
+++ b/src/Nexus/Internal/Headers.php
@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Internal;
+
+/**
+ * @internal
+ */
+final class Headers
+{
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    /**
+     * Lowercase keys; last value wins on collision.
+     *
+     * @param array<string, string> $headers
+     * @return array<string, string>
+     */
+    public static function normalize(array $headers): array
+    {
+        $normalized = [];
+        foreach ($headers as $key => $value) {
+            $normalized[\strtolower($key)] = $value;
+        }
+        return $normalized;
+    }
+}
diff --git a/src/Nexus/Internal/WorkflowRunOperationToken.php b/src/Nexus/Internal/WorkflowRunOperationToken.php
new file mode 100644
index 000000000..3f530eb6a
--- /dev/null
+++ b/src/Nexus/Internal/WorkflowRunOperationToken.php
@@ -0,0 +1,99 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Internal;
+
+/**
+ * Workflow-run operation token: base64url(JSON{t:1, ns, wid}).
+ * Java/Go-compatible. Non-zero `v` field on decode = newer producer, rejected.
+ *
+ * @internal
+ */
+final class WorkflowRunOperationToken
+{
+    private const TYPE_WORKFLOW_RUN = 1;
+
+    public function __construct(
+        public readonly string $namespace,
+        public readonly string $workflowId,
+    ) {}
+
+    public static function generate(string $namespace, string $workflowId): string
+    {
+        $payload = [
+            't' => self::TYPE_WORKFLOW_RUN,
+            'ns' => $namespace,
+            'wid' => $workflowId,
+        ];
+
+        $json = \json_encode($payload, \JSON_UNESCAPED_SLASHES | \JSON_UNESCAPED_UNICODE | \JSON_THROW_ON_ERROR);
+
+        return \rtrim(\strtr(\base64_encode($json), '+/', '-_'), '=');
+    }
+
+    /**
+     * @throws \InvalidArgumentException on malformed input.
+     */
+    public static function load(string $token): self
+    {
+        if ($token === '') {
+            throw new \InvalidArgumentException('invalid workflow run token: token is empty');
+        }
+
+        $decoded = \base64_decode(\strtr($token, '-_', '+/'), true);
+        if ($decoded === false) {
+            throw new \InvalidArgumentException('failed to decode token');
+        }
+
+        try {
+            $parsed = \json_decode($decoded, true, 16, \JSON_THROW_ON_ERROR);
+        } catch (\JsonException $e) {
+            throw new \InvalidArgumentException(
+                'failed to unmarshal workflow run operation token: ' . $e->getMessage(),
+                previous: $e,
+            );
+        }
+
+        if (!\is_array($parsed)) {
+            throw new \InvalidArgumentException('failed to unmarshal workflow run operation token: not an object');
+        }
+
+        $type = $parsed['t'] ?? null;
+        if ($type !== self::TYPE_WORKFLOW_RUN) {
+            throw new \InvalidArgumentException(
+                \sprintf(
+                    'invalid workflow token type: %s, expected: %d',
+                    \var_export($type, true),
+                    self::TYPE_WORKFLOW_RUN,
+                ),
+            );
+        }
+
+        if (\array_key_exists('v', $parsed) && $parsed['v'] !== 0) {
+            throw new \InvalidArgumentException(\sprintf(
+                'invalid workflow run token: unsupported version %s',
+                \var_export($parsed['v'], true),
+            ));
+        }
+
+        $workflowId = $parsed['wid'] ?? '';
+        if (!\is_string($workflowId) || $workflowId === '') {
+            throw new \InvalidArgumentException('invalid workflow run token: missing workflow ID (wid)');
+        }
+
+        $namespace = $parsed['ns'] ?? '';
+        if (!\is_string($namespace)) {
+            throw new \InvalidArgumentException('invalid workflow run token: namespace must be a string');
+        }
+
+        return new self($namespace, $workflowId);
+    }
+}
diff --git a/src/Nexus/Link.php b/src/Nexus/Link.php
new file mode 100644
index 000000000..616a3bacc
--- /dev/null
+++ b/src/Nexus/Link.php
@@ -0,0 +1,58 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+
+/**
+ * URI + type that decodes it. Constructor rejects empty values.
+ *
+ * @see https://github.com/nexus-rpc/api/blob/main/SPEC.md (Nexus-Link header)
+ */
+final class Link implements \Stringable
+{
+    public function __construct(
+        public readonly string $uri,
+        public readonly string $type,
+    ) {
+        if ($uri === '') {
+            throw new InvalidArgumentException('Link URI must not be empty');
+        }
+        if ($type === '') {
+            throw new InvalidArgumentException('Link type must not be empty');
+        }
+    }
+
+    /**
+     * @param iterable<array-key, mixed> $links
+     * @param non-empty-string $where Label used in the error message, e.g. `Foo: links`.
+     */
+    public static function assertAll(iterable $links, string $where): void
+    {
+        foreach ($links as $i => $link) {
+            if (!$link instanceof self) {
+                throw new InvalidArgumentException(\sprintf(
+                    '%s[%s] must be a %s, got %s',
+                    $where,
+                    \is_int($i) ? (string) $i : \var_export($i, true),
+                    self::class,
+                    \get_debug_type($link),
+                ));
+            }
+        }
+    }
+
+    public function __toString(): string
+    {
+        return "Link{uri='{$this->uri}', type='{$this->type}'}";
+    }
+}
diff --git a/src/Nexus/LinkParser.php b/src/Nexus/LinkParser.php
new file mode 100644
index 000000000..38f9ca0ce
--- /dev/null
+++ b/src/Nexus/LinkParser.php
@@ -0,0 +1,107 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus;
+
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+
+/**
+ * Parses Nexus links from raw JSON / proto into `Link[]`.
+ * Strict: malformed input throws {@see HandlerException} (BadRequest).
+ * Absent input returns `[]`.
+ */
+final class LinkParser
+{
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    /**
+     * @return Link[]
+     * @throws HandlerException
+     */
+    public static function fromRaw(mixed $raw): array
+    {
+        if ($raw === null) {
+            return [];
+        }
+        if (!\is_array($raw)) {
+            throw HandlerException::create(
+                ErrorType::BadRequest,
+                \sprintf('Nexus links must be an array, got %s', \get_debug_type($raw)),
+            );
+        }
+
+        $links = [];
+        foreach ($raw as $index => $entry) {
+            if (!\is_array($entry)) {
+                throw HandlerException::create(
+                    ErrorType::BadRequest,
+                    \sprintf(
+                        'Nexus link at index %s is not an object (got %s)',
+                        self::formatIndex($index),
+                        \get_debug_type($entry),
+                    ),
+                );
+            }
+            $links[] = self::buildLink(
+                url: $entry['url'] ?? null,
+                type: $entry['type'] ?? null,
+                context: 'index ' . self::formatIndex($index),
+            );
+        }
+        return $links;
+    }
+
+    /**
+     * @param iterable<\Temporal\Api\Nexus\V1\Link> $protoLinks
+     * @return Link[]
+     * @throws HandlerException
+     */
+    public static function fromProto(iterable $protoLinks): array
+    {
+        $links = [];
+        $index = 0;
+        foreach ($protoLinks as $protoLink) {
+            $links[] = self::buildLink(
+                url: $protoLink->getUrl(),
+                type: $protoLink->getType(),
+                context: 'proto index ' . $index,
+            );
+            $index++;
+        }
+        return $links;
+    }
+
+    private static function buildLink(mixed $url, mixed $type, string $context): Link
+    {
+        if (!\is_string($url) || $url === '') {
+            throw HandlerException::create(
+                ErrorType::BadRequest,
+                \sprintf('Nexus link at %s has missing or empty "url"', $context),
+            );
+        }
+        if (!\is_string($type) || $type === '') {
+            throw HandlerException::create(
+                ErrorType::BadRequest,
+                \sprintf('Nexus link at %s has missing or empty "type"', $context),
+            );
+        }
+        return new Link($url, $type);
+    }
+
+    private static function formatIndex(mixed $index): string
+    {
+        return \is_int($index) ? (string) $index : \var_export($index, true);
+    }
+}
diff --git a/src/Nexus/Nexus.php b/src/Nexus/Nexus.php
new file mode 100644
index 000000000..e44941c17
--- /dev/null
+++ b/src/Nexus/Nexus.php
@@ -0,0 +1,113 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus;
+
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Interceptor\NexusOperationOutbound\GetInfoInput;
+use Temporal\Internal\Nexus\NexusContext;
+use Temporal\Internal\Support\Facade;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationStartDetails;
+
+/**
+ * Static accessors for the active Nexus dispatch state. Use these inside operation method bodies instead of threading the context through parameters.
+ */
+final class Nexus extends Facade
+{
+    /**
+     * Guard accessor for the active {@see NexusContext} of the current dispatch.
+     *
+     * @throws \LogicException when called outside a Nexus operation dispatch.
+     */
+    public static function getCurrentContext(): NexusContext
+    {
+        $context = parent::getCurrentContext();
+        if (!$context instanceof NexusContext) {
+            throw new \LogicException('The Nexus facade can be used only inside a Nexus operation handler.');
+        }
+
+        return $context;
+    }
+
+    /**
+     * Handler-side {@see OperationContext} for the current dispatch (links, headers,
+     * deadline, service definition). Guarded accessor for {@see NexusContext::$current}.
+     *
+     * @throws \LogicException when called outside a Nexus operation dispatch.
+     */
+    public static function getCurrentOperationContext(): OperationContext
+    {
+        return self::getCurrentContext()->current;
+    }
+
+    /**
+     * Temporal-side context (namespace, taskQueue, workflowClient).
+     *
+     * @throws \LogicException when called outside a Nexus operation dispatch.
+     */
+    public static function getOperationContext(): NexusOperationContext
+    {
+        $dispatch = self::getCurrentContext();
+        $info = $dispatch->operation ?? throw new \LogicException(
+            'Temporal operation context is not available for this dispatch.',
+        );
+
+        $pipeline = $dispatch->outboundPipeline;
+        if ($pipeline === null) {
+            return $info;
+        }
+
+        return $pipeline->with(
+            /**
+             * @psalm-suppress UnusedClosureParam The terminal call ignores the empty input DTO.
+             * @see \Temporal\Interceptor\NexusOperationOutboundCallsInterceptor::getInfo()
+             */
+            static fn(GetInfoInput $input): NexusOperationContext => $info,
+            'getInfo',
+        )(new GetInfoInput());
+    }
+
+    /**
+     * Per-start details (requestId, callbackUrl, callbackHeaders, caller links).
+     *
+     * @throws \LogicException when called outside a start-operation dispatch.
+     */
+    public static function getStartDetails(): OperationStartDetails
+    {
+        return self::getCurrentContext()->startDetails ?? throw new \LogicException(
+            'Nexus::getStartDetails() called outside a start-operation dispatch.',
+        );
+    }
+
+    /**
+     * @throws \LogicException when called outside a cancel-operation dispatch.
+     */
+    public static function getCancelDetails(): OperationCancelDetails
+    {
+        return self::getCurrentContext()->cancelDetails ?? throw new \LogicException(
+            'Nexus::getCancelDetails() called outside a cancel-operation dispatch.',
+        );
+    }
+
+    /**
+     * @internal Plumbing for {@see \Temporal\Nexus\WorkflowRunOperation}; user code should drive
+     *           backing workflows through the helper API rather than reaching for the client.
+     * @throws \LogicException when no WorkflowClient is available (async Nexus needs cluster access).
+     */
+    public static function getWorkflowClient(): WorkflowClientInterface
+    {
+        return self::getCurrentContext()->workflowClient ?? throw new \LogicException(
+            'Nexus::getWorkflowClient() requires a WorkflowClient. Async Nexus operations (WorkflowRunOperation) need cluster access; provide a WorkflowClient to the WorkerFactory.',
+        );
+    }
+}
diff --git a/src/Nexus/NexusOperationContext.php b/src/Nexus/NexusOperationContext.php
new file mode 100644
index 000000000..8aeeac5ff
--- /dev/null
+++ b/src/Nexus/NexusOperationContext.php
@@ -0,0 +1,24 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus;
+
+use Temporal\Internal\Marshaller\Meta\Marshal;
+
+final class NexusOperationContext
+{
+    public function __construct(
+        #[Marshal(name: 'namespace')]
+        public string $namespace = '',
+        #[Marshal(name: 'taskQueue')]
+        public string $taskQueue = '',
+    ) {}
+}
diff --git a/src/Nexus/OperationInfo.php b/src/Nexus/OperationInfo.php
new file mode 100644
index 000000000..dd6d1581f
--- /dev/null
+++ b/src/Nexus/OperationInfo.php
@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus;
+
+use Temporal\Nexus\Validation\OperationTokenValidator;
+
+/**
+ * Identifies an operation by its token together with its current state.
+ *
+ * Wire schema per Nexus SPEC.md §OperationInfo:
+ * https://github.com/nexus-rpc/api/blob/main/SPEC.md
+ */
+final class OperationInfo
+{
+    public function __construct(
+        public readonly string $token,
+        public readonly OperationState $state,
+    ) {
+        OperationTokenValidator::assert($token);
+    }
+}
diff --git a/src/Nexus/OperationState.php b/src/Nexus/OperationState.php
new file mode 100644
index 000000000..2abc0a5af
--- /dev/null
+++ b/src/Nexus/OperationState.php
@@ -0,0 +1,21 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus;
+
+enum OperationState: string
+{
+    // Wire values — must match the Nexus spec verbatim.
+    case Running = 'running';
+    case Succeeded = 'succeeded';
+    case Failed = 'failed';
+    case Canceled = 'canceled';
+}
diff --git a/src/Nexus/Validation/OperationNameValidator.php b/src/Nexus/Validation/OperationNameValidator.php
new file mode 100644
index 000000000..df4ee70d6
--- /dev/null
+++ b/src/Nexus/Validation/OperationNameValidator.php
@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Validation;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+
+/**
+ * Operation name — printable non-whitespace ASCII (Nexus spec).
+ */
+final class OperationNameValidator
+{
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    /**
+     * @throws InvalidArgumentException
+     */
+    public static function assert(string $name): void
+    {
+        PrintableAsciiValidator::assert($name, 'Operation Name');
+        ReservedPrefixValidator::assert($name, 'Operation Name');
+    }
+}
diff --git a/src/Nexus/Validation/OperationTokenValidator.php b/src/Nexus/Validation/OperationTokenValidator.php
new file mode 100644
index 000000000..887a0fbcd
--- /dev/null
+++ b/src/Nexus/Validation/OperationTokenValidator.php
@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Validation;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+
+/**
+ * Operation token — printable non-whitespace ASCII (Nexus spec).
+ */
+final class OperationTokenValidator
+{
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    /**
+     * @throws InvalidArgumentException
+     */
+    public static function assert(string $token): void
+    {
+        PrintableAsciiValidator::assert($token, 'Operation Token');
+    }
+}
diff --git a/src/Nexus/Validation/PrintableAsciiValidator.php b/src/Nexus/Validation/PrintableAsciiValidator.php
new file mode 100644
index 000000000..c12373562
--- /dev/null
+++ b/src/Nexus/Validation/PrintableAsciiValidator.php
@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Validation;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+
+/**
+ * @internal Shared check for printable non-whitespace ASCII (0x21–0x7E).
+ */
+final class PrintableAsciiValidator
+{
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    /**
+     * @throws InvalidArgumentException when $value is empty or contains a byte
+     *         outside the printable ASCII range 0x21–0x7E.
+     *
+     * @psalm-mutation-free
+     */
+    public static function assert(string $value, string $label): void
+    {
+        if ($value === '') {
+            throw new InvalidArgumentException("{$label} must not be empty");
+        }
+
+        if (\preg_match('/[^\x21-\x7E]/', $value, $matches, \PREG_OFFSET_CAPTURE) === 1) {
+            throw new InvalidArgumentException(\sprintf(
+                '%s must contain only printable non-whitespace ASCII (0x21–0x7E); got %d bytes, first bad char at offset %d',
+                $label,
+                \strlen($value),
+                $matches[0][1],
+            ));
+        }
+    }
+}
diff --git a/src/Nexus/Validation/ReservedPrefixValidator.php b/src/Nexus/Validation/ReservedPrefixValidator.php
new file mode 100644
index 000000000..dad7381be
--- /dev/null
+++ b/src/Nexus/Validation/ReservedPrefixValidator.php
@@ -0,0 +1,44 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Validation;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+
+/**
+ * @internal Shared check for the `__temporal_` prefix reserved by the Temporal server.
+ */
+final class ReservedPrefixValidator
+{
+    public const PREFIX = '__temporal_';
+
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    /**
+     * @throws InvalidArgumentException when $value starts with {@see self::PREFIX}.
+     *
+     * @psalm-mutation-free
+     */
+    public static function assert(string $value, string $label): void
+    {
+        if (\str_starts_with($value, self::PREFIX)) {
+            throw new InvalidArgumentException(\sprintf(
+                '%s "%s" must not start with "%s"',
+                $label,
+                $value,
+                self::PREFIX,
+            ));
+        }
+    }
+}
diff --git a/src/Nexus/Validation/ServiceNameValidator.php b/src/Nexus/Validation/ServiceNameValidator.php
new file mode 100644
index 000000000..e9902740b
--- /dev/null
+++ b/src/Nexus/Validation/ServiceNameValidator.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus\Validation;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+
+/**
+ * Service name — printable non-whitespace ASCII (Nexus spec).
+ */
+final class ServiceNameValidator
+{
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    /**
+     * @throws InvalidArgumentException
+     *
+     * @psalm-mutation-free
+     */
+    public static function assert(string $name): void
+    {
+        PrintableAsciiValidator::assert($name, 'Service Name');
+        ReservedPrefixValidator::assert($name, 'Service Name');
+    }
+}
diff --git a/src/Nexus/WorkflowHandle.php b/src/Nexus/WorkflowHandle.php
new file mode 100644
index 000000000..5e7729563
--- /dev/null
+++ b/src/Nexus/WorkflowHandle.php
@@ -0,0 +1,41 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus;
+
+use Temporal\Client\WorkflowOptions;
+
+/**
+ * Description of the workflow that backs a Nexus operation.
+ */
+final class WorkflowHandle
+{
+    /**
+     * @param class-string $workflowClass Workflow interface annotated with #[WorkflowInterface].
+     * @param list<mixed> $args Arguments forwarded to the workflow method.
+     */
+    private function __construct(
+        public readonly string $workflowClass,
+        public readonly WorkflowOptions $options,
+        public readonly array $args,
+    ) {}
+
+    /**
+     * @param class-string $workflowClass
+     */
+    public static function fromWorkflowMethod(
+        string $workflowClass,
+        WorkflowOptions $options,
+        mixed ...$args,
+    ): self {
+        return new self($workflowClass, $options, \array_values($args));
+    }
+}
diff --git a/src/Nexus/WorkflowRunOperation.php b/src/Nexus/WorkflowRunOperation.php
new file mode 100644
index 000000000..11dddbc4a
--- /dev/null
+++ b/src/Nexus/WorkflowRunOperation.php
@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Nexus;
+
+use Temporal\Nexus\Internal\WorkflowRunOperationToken;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+
+/**
+ * Helpers for Nexus operations backed by a Temporal workflow run (SDK-minted tokens only).
+ */
+final class WorkflowRunOperation
+{
+    /**
+     * @codeCoverageIgnore
+     */
+    private function __construct() {}
+
+    /**
+     * Cancel the workflow corresponding to the given operation token.
+     *
+     * Decodes the token and asks the workflow client to cancel by workflow ID.
+     */
+    public static function cancel(string $operationToken): void
+    {
+        $client = Nexus::getWorkflowClient();
+
+        try {
+            $decoded = WorkflowRunOperationToken::load($operationToken);
+        } catch (\InvalidArgumentException $e) {
+            throw HandlerException::create(ErrorType::BadRequest, 'failed to parse operation token', $e);
+        }
+
+        $client->newUntypedRunningWorkflowStub($decoded->workflowId)->cancel();
+    }
+}
diff --git a/src/Worker/Transport/Codec/ProtoCodec/Encoder.php b/src/Worker/Transport/Codec/ProtoCodec/Encoder.php
index f059074a8..90b3024e6 100644
--- a/src/Worker/Transport/Codec/ProtoCodec/Encoder.php
+++ b/src/Worker/Transport/Codec/ProtoCodec/Encoder.php
@@ -15,7 +15,7 @@
 use Temporal\DataConverter\DataConverterInterface;
 use Temporal\Exception\Failure\FailureConverter;
 use Temporal\Interceptor\Header;
-use Temporal\Worker\Transport\Command\Client\UpdateResponse;
+use Temporal\Worker\Transport\Command\Client\CommandResponse;
 use Temporal\Worker\Transport\Command\CommandInterface;
 use Temporal\Worker\Transport\Command\FailureResponseInterface;
 use Temporal\Worker\Transport\Command\RequestInterface;
@@ -51,7 +51,7 @@ public function encode(CommandInterface $cmd): Message
                 }
 
                 $msg->setCommand($cmd->getName());
-                $msg->setOptions(\json_encode($options));
+                $msg->setOptions(\json_encode($options, \JSON_THROW_ON_ERROR));
                 $msg->setPayloads($cmd->getPayloads()->toPayloads());
                 $msg->setHeader($header->toHeader());
 
@@ -62,21 +62,30 @@ public function encode(CommandInterface $cmd): Message
                 return $msg;
 
             case $cmd instanceof FailureResponseInterface:
-                \is_int($cmd->getID()) and $msg->setId($cmd->getID());
+                if (\is_int($cmd->getID())) {
+                    $msg->setId($cmd->getID());
+                }
                 $msg->setFailure(FailureConverter::mapExceptionToFailure($cmd->getFailure(), $this->converter));
 
                 return $msg;
 
             case $cmd instanceof SuccessResponseInterface:
-                \is_int($cmd->getID()) and $msg->setId($cmd->getID());
+                if (\is_int($cmd->getID())) {
+                    $msg->setId($cmd->getID());
+                }
                 $cmd->getPayloads()->setDataConverter($this->converter);
                 $msg->setPayloads($cmd->getPayloads()->toPayloads());
 
                 return $msg;
 
-            case $cmd instanceof UpdateResponse:
+            case $cmd instanceof CommandResponse:
+                $options = $cmd->getOptions();
+                if ($options === []) {
+                    $options = new \stdClass();
+                }
+
                 $msg->setCommand($cmd->getCommand());
-                $msg->setOptions(\json_encode($cmd->getOptions(), JSON_INVALID_UTF8_IGNORE | JSON_UNESCAPED_UNICODE));
+                $msg->setOptions(\json_encode($options, \JSON_THROW_ON_ERROR));
 
                 if ($cmd->getFailure() !== null) {
                     $msg->setFailure(FailureConverter::mapExceptionToFailure($cmd->getFailure(), $this->converter));
diff --git a/src/Worker/Transport/Command/Client/UpdateResponse.php b/src/Worker/Transport/Command/Client/CommandResponse.php
similarity index 67%
rename from src/Worker/Transport/Command/Client/UpdateResponse.php
rename to src/Worker/Transport/Command/Client/CommandResponse.php
index 1b10adcaa..6889c62e8 100644
--- a/src/Worker/Transport/Command/Client/UpdateResponse.php
+++ b/src/Worker/Transport/Command/Client/CommandResponse.php
@@ -14,16 +14,16 @@
 use Temporal\DataConverter\ValuesInterface;
 use Temporal\Worker\Transport\Command\ResponseInterface;
 
-final class UpdateResponse implements ResponseInterface
+final class CommandResponse implements ResponseInterface
 {
-    public const COMMAND_VALIDATED = 'UpdateValidated';
-    public const COMMAND_COMPLETED = 'UpdateCompleted';
-
+    /**
+     * @param array<string, mixed> $options
+     */
     public function __construct(
         private readonly string $command,
-        private ?ValuesInterface $values,
-        private readonly ?\Throwable $failure,
-        private string|int $updateId,
+        private readonly array $options = [],
+        private readonly ?ValuesInterface $payloads = null,
+        private readonly ?\Throwable $failure = null,
     ) {}
 
     public function getID(): int
@@ -36,18 +36,21 @@ public function getCommand(): string
         return $this->command;
     }
 
-    public function getPayloads(): ?ValuesInterface
+    /**
+     * @return array<string, mixed>
+     */
+    public function getOptions(): array
     {
-        return $this->values;
+        return $this->options;
     }
 
-    public function getFailure(): ?\Throwable
+    public function getPayloads(): ?ValuesInterface
     {
-        return $this->failure;
+        return $this->payloads;
     }
 
-    public function getOptions(): array
+    public function getFailure(): ?\Throwable
     {
-        return ['id' => $this->updateId];
+        return $this->failure;
     }
 }
diff --git a/src/Worker/Transport/Command/Client/FailedClientResponse.php b/src/Worker/Transport/Command/Client/FailedClientResponse.php
index a834f2b4f..4ec0c0c2b 100644
--- a/src/Worker/Transport/Command/Client/FailedClientResponse.php
+++ b/src/Worker/Transport/Command/Client/FailedClientResponse.php
@@ -17,7 +17,7 @@ final class FailedClientResponse implements FailureResponseInterface
 {
     public function __construct(
         private readonly int|string $id,
-        private readonly ?\Throwable $failure = null,
+        private readonly \Throwable $failure,
     ) {}
 
     public function getID(): string|int
diff --git a/src/Worker/Worker.php b/src/Worker/Worker.php
index 391fa02c0..3b4d4a787 100644
--- a/src/Worker/Worker.php
+++ b/src/Worker/Worker.php
@@ -13,6 +13,7 @@
 
 use React\Promise\PromiseInterface;
 use Temporal\Internal\Declaration\EntityNameValidator;
+use Temporal\Internal\Declaration\Reader\NexusServiceReader;
 use Temporal\Internal\Events\EventEmitterTrait;
 use Temporal\Internal\Events\EventListenerInterface;
 use Temporal\Internal\Repository\RepositoryInterface;
@@ -115,6 +116,37 @@ public function getActivities(): RepositoryInterface
         return $this->services->activities;
     }
 
+    public function registerNexusServiceImplementation(object ...$services): WorkerInterface
+    {
+        $hasClient = $this->services->workflowClient !== null;
+
+        foreach ($services as $service) {
+            $prototype = $this->services->nexusServicesReader->fromClass($service::class);
+
+            if (!$hasClient) {
+                foreach ($prototype->getOperations() as $operation) {
+                    if ($operation->async && !NexusServiceReader::returnsOperationHandler($operation->handler)) {
+                        throw new \LogicException(\sprintf(
+                            'Nexus service %s declares async operation "%s", which needs cluster access. '
+                            . 'Pass a WorkflowClient to the worker: WorkerFactory::create(client: $workflowClient).',
+                            $service::class,
+                            $operation->name,
+                        ));
+                    }
+                }
+            }
+
+            $this->services->nexusServices->add($prototype->withInstance($service), false);
+        }
+
+        return $this;
+    }
+
+    public function getNexusServices(): RepositoryInterface
+    {
+        return $this->services->nexusServices;
+    }
+
     protected function createRouter(): RouterInterface
     {
         $router = new Router();
@@ -132,6 +164,20 @@ protected function createRouter(): RouterInterface
         $router->add(new Router\DestroyWorkflow($this->services->running, $this->services->loop));
         $router->add(new Router\StackTrace($this->services->running));
 
+        // Nexus routes
+        $router->add(new Router\InvokeNexusOperation(
+            $this->services->nexusTaskHandler,
+            $this->services->nexusInvocations,
+            $this->services->dataConverter,
+            $this->services->marshaller,
+            $this->services->env,
+        ));
+        $router->add(new Router\CancelNexusOperation(
+            $this->services->nexusTaskHandler,
+            $this->services->marshaller,
+        ));
+        $router->add(new Router\CancelNexusOperationMethod($this->services->nexusInvocations));
+
         return $router;
     }
 }
diff --git a/src/Worker/WorkerInterface.php b/src/Worker/WorkerInterface.php
index 893cff752..5a37e0a3e 100644
--- a/src/Worker/WorkerInterface.php
+++ b/src/Worker/WorkerInterface.php
@@ -12,6 +12,7 @@
 namespace Temporal\Worker;
 
 use Temporal\Internal\Declaration\Prototype\ActivityPrototype;
+use Temporal\Internal\Declaration\Prototype\NexusServicePrototype;
 use Temporal\Internal\Declaration\Prototype\WorkflowPrototype;
 use Temporal\Internal\Repository\Identifiable;
 
@@ -79,4 +80,18 @@ public function registerActivity(string $type, ?callable $factory = null): self;
      * @return iterable<ActivityPrototype>
      */
     public function getActivities(): iterable;
+
+    /**
+     * Register one or multiple Nexus service implementations to be served by this worker.
+     *
+     * @return $this
+     */
+    public function registerNexusServiceImplementation(object ...$services): self;
+
+    /**
+     * Returns list of registered Nexus service prototypes.
+     *
+     * @return iterable<NexusServicePrototype>
+     */
+    public function getNexusServices(): iterable;
 }
diff --git a/src/WorkerFactory.php b/src/WorkerFactory.php
index c64245815..98ad3e165 100644
--- a/src/WorkerFactory.php
+++ b/src/WorkerFactory.php
@@ -113,6 +113,7 @@ class WorkerFactory implements WorkerFactoryInterface, LoopInterface
 
     protected EnvironmentInterface $env;
     protected PluginRegistry $pluginRegistry;
+    protected ?WorkflowClient $workflowClient = null;
 
     public function __construct(
         DataConverterInterface $dataConverter,
@@ -121,6 +122,7 @@ public function __construct(
         ?PluginRegistry $pluginRegistry = null,
         ?WorkflowClient $client = null,
     ) {
+        $this->workflowClient = $client;
         $this->pluginRegistry = new PluginRegistry();
         // Propagate worker plugins from the client first
         if ($client !== null) {
@@ -202,6 +204,7 @@ public function newWorker(
                     $options->enableLoggingInReplay,
                     $taskQueue,
                 ),
+                $this->workflowClient,
             ),
             $this->rpc,
         );
diff --git a/src/Workflow.php b/src/Workflow.php
index 0938d890a..3e3220eba 100644
--- a/src/Workflow.php
+++ b/src/Workflow.php
@@ -28,6 +28,7 @@
 use Temporal\Internal\Workflow\ChildWorkflowProxy;
 use Temporal\Internal\Workflow\ContinueAsNewProxy;
 use Temporal\Internal\Workflow\ExternalWorkflowProxy;
+use Temporal\Internal\Workflow\NexusServiceProxy;
 use Temporal\Workflow\ActivityStubInterface;
 use Temporal\Workflow\CancellationScopeInterface;
 use Temporal\Workflow\ChildWorkflowOptions;
@@ -1013,6 +1014,49 @@ public static function newUntypedActivityStub(
         return self::getCurrentContext()->newUntypedActivityStub($options);
     }
 
+    /**
+     * Returns a typed proxy for a Nexus service interface.
+     * Method calls on the returned object will execute Nexus operations.
+     *
+     * @template T of object
+     *
+     * @param class-string<T> $class Nexus service interface annotated with #[Service]
+     *
+     * @return NexusServiceProxy<T>
+     * @throws OutOfContextException in the absence of the workflow execution context.
+     */
+    public static function newNexusServiceStub(
+        string $class,
+        Workflow\NexusOperationOptions $options,
+    ): object {
+        return self::getCurrentContext()->newNexusServiceStub($class, $options);
+    }
+
+    /**
+     * Returns an untyped Nexus operation stub.
+     *
+     * @throws OutOfContextException in the absence of the workflow execution context.
+     */
+    public static function newUntypedNexusOperationStub(
+        Workflow\NexusOperationOptions $options,
+    ): Workflow\NexusOperationStubInterface {
+        return self::getCurrentContext()->newUntypedNexusOperationStub($options);
+    }
+
+    /**
+     * Execute a Nexus operation directly without a typed stub.
+     *
+     * @throws OutOfContextException in the absence of the workflow execution context.
+     */
+    public static function executeNexusOperation(
+        string $operation,
+        array $args = [],
+        ?Workflow\NexusOperationOptions $options = null,
+        Type|string|\ReflectionClass|\ReflectionType|null $returnType = null,
+    ): PromiseInterface {
+        return self::getCurrentContext()->executeNexusOperation($operation, $args, $options, $returnType);
+    }
+
     /**
      * Returns a complete trace of the last calls (for debugging).
      *
diff --git a/src/Workflow/CompletionCallback.php b/src/Workflow/CompletionCallback.php
new file mode 100644
index 000000000..daa1f639f
--- /dev/null
+++ b/src/Workflow/CompletionCallback.php
@@ -0,0 +1,65 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Workflow;
+
+use Temporal\Api\Common\V1\Link;
+use Temporal\Internal\Nexus\NexusLinkConverter;
+use Temporal\Nexus\Link as NexusLink;
+
+/**
+ * Public value object describing a Nexus-style completion callback registered
+ * at workflow start. Decouples the caller-facing API from the
+ * {@see \Temporal\Api\Common\V1\Callback} protobuf — the proto envelope is
+ * built by {@see \Temporal\Internal\Client\WorkflowStarter} on the way out.
+ */
+final class CompletionCallback
+{
+    /**
+     * Proto Link[] attached to the Callback envelope on the wire. Populated via
+     * {@see self::fromNexusLinks()} from caller-supplied Nexus links; left empty
+     * for non-Nexus completion callbacks.
+     *
+     * @var list<Link>
+     */
+    public readonly array $links;
+
+    /**
+     * @param non-empty-string $url Callback URL the server invokes when the
+     *        workflow reaches a terminal state.
+     * @param array<string, string> $headers Optional headers sent verbatim.
+     * @param list<Link> $links Already-converted proto Links.
+     * @throws \InvalidArgumentException when $url is empty.
+     */
+    public function __construct(
+        public readonly string $url,
+        public readonly array $headers = [],
+        array $links = [],
+    ) {
+        /** @psalm-suppress TypeDoesNotContainType — defensive runtime check */
+        if ($url === '') {
+            throw new \InvalidArgumentException('CompletionCallback: url must be a non-empty string');
+        }
+        $this->links = $links;
+    }
+
+    /**
+     * Build a callback with high-level Nexus links converted to proto Links.
+     *
+     * @param non-empty-string $url
+     * @param array<string, string> $headers
+     * @param iterable<NexusLink> $nexusLinks
+     */
+    public static function fromNexusLinks(string $url, array $headers, iterable $nexusLinks): self
+    {
+        return new self($url, $headers, NexusLinkConverter::toProtoLinks($nexusLinks));
+    }
+}
diff --git a/src/Workflow/NexusOperationCancellationType.php b/src/Workflow/NexusOperationCancellationType.php
new file mode 100644
index 000000000..dcd08bd08
--- /dev/null
+++ b/src/Workflow/NexusOperationCancellationType.php
@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Workflow;
+
+/**
+ * Action for a Nexus operation when the caller is cancelled.
+ * Values match sdk-go `NexusOperationCancellationType` (iota-ordered).
+ */
+enum NexusOperationCancellationType: int
+{
+    /**
+     * No cancellation type was specified. The server treats this as
+     * {@see self::WaitCompleted}, matching the sdk-go default.
+     */
+    case Unspecified = 0;
+
+    /**
+     * Do not request cancellation of the operation. The handler workflow
+     * keeps running server-side; the SDK suppresses the wire-level cancel
+     * command, so the server is never notified of the caller's cancel
+     * request, and the caller's future resolves immediately with a
+     * {@see \Temporal\Exception\Failure\CanceledFailure} (surfaced as a
+     * {@see \Temporal\Exception\Failure\NexusOperationFailure}).
+     */
+    case Abandon = 1;
+    case TryCancel = 2;
+    case WaitRequested = 3;
+    case WaitCompleted = 4;
+}
diff --git a/src/Workflow/NexusOperationHandle.php b/src/Workflow/NexusOperationHandle.php
new file mode 100644
index 000000000..1d3cc96f6
--- /dev/null
+++ b/src/Workflow/NexusOperationHandle.php
@@ -0,0 +1,54 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Workflow;
+
+use React\Promise\PromiseInterface;
+use Temporal\DataConverter\EncodedValues;
+use Temporal\DataConverter\Type;
+
+/**
+ * Handle to an in-flight Nexus operation started from a workflow. Fully populated
+ * on creation — the start response has already arrived, so {@see self::getOperationToken()}
+ * is final (server-issued `string` for async operations, `null` for sync) and
+ * {@see self::getResult()} is wired (already-resolved for sync, pending for async).
+ *
+ * @template T
+ */
+final class NexusOperationHandle
+{
+    private readonly PromiseInterface $resultPromise;
+
+    /**
+     * @param PromiseInterface $rawResult Resolves with a {@see \Temporal\DataConverter\ValuesInterface}
+     *        carrying the wire-level result payloads; rejects on failure.
+     */
+    public function __construct(
+        private readonly ?string $operationToken,
+        PromiseInterface $rawResult,
+        Type|string|\ReflectionClass|\ReflectionType|null $returnType = null,
+    ) {
+        $this->resultPromise = EncodedValues::decodePromise($rawResult, $returnType);
+    }
+
+    /**
+     * @return PromiseInterface<T>
+     */
+    public function getResult(): PromiseInterface
+    {
+        return $this->resultPromise;
+    }
+
+    public function getOperationToken(): ?string
+    {
+        return $this->operationToken;
+    }
+}
diff --git a/src/Workflow/NexusOperationOptions.php b/src/Workflow/NexusOperationOptions.php
new file mode 100644
index 000000000..c003918e2
--- /dev/null
+++ b/src/Workflow/NexusOperationOptions.php
@@ -0,0 +1,163 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Workflow;
+
+use JetBrains\PhpStorm\Pure;
+use Temporal\Internal\Marshaller\Meta\Marshal;
+use Temporal\Internal\Marshaller\Type\DateIntervalType;
+use Temporal\Internal\Marshaller\Type\EnumValueType;
+use Temporal\Internal\Support\DateInterval;
+use Temporal\Internal\Support\Options;
+use Temporal\Nexus\Validation\PrintableAsciiValidator;
+use Temporal\Nexus\Validation\ReservedPrefixValidator;
+use Temporal\Nexus\Validation\ServiceNameValidator;
+
+/**
+ * Options for executing a Nexus operation from a workflow.
+ *
+ * @psalm-import-type DateIntervalValue from DateInterval
+ */
+final class NexusOperationOptions extends Options
+{
+    /**
+     * Name of the Nexus Endpoint as registered in the Temporal server.
+     */
+    #[Marshal(name: 'endpoint')]
+    public string $endpoint = '';
+
+    /**
+     * Service name to call. If empty, derived from the service interface.
+     */
+    #[Marshal(name: 'service')]
+    public string $service = '';
+
+    /**
+     * Overall timeout for the Nexus operation.
+     */
+    #[Marshal(name: 'scheduleToCloseTimeout', type: DateIntervalType::class)]
+    public \DateInterval $scheduleToCloseTimeout;
+
+    /**
+     * Maximum time the operation may wait to be started by the handler.
+     */
+    #[Marshal(name: 'scheduleToStartTimeout', type: DateIntervalType::class)]
+    public \DateInterval $scheduleToStartTimeout;
+
+    /**
+     * Maximum time an asynchronous operation may take to complete after it has started.
+     */
+    #[Marshal(name: 'startToCloseTimeout', type: DateIntervalType::class)]
+    public \DateInterval $startToCloseTimeout;
+
+    /**
+     * Behaviour applied when the caller workflow is cancelled.
+     *
+     * Defaults to {@see NexusOperationCancellationType::Unspecified}, which
+     * the server treats as {@see NexusOperationCancellationType::WaitCompleted}
+     * (the sdk-go default).
+     *
+     * @see NexusOperationCancellationType
+     */
+    #[Marshal(name: 'cancellationType', type: EnumValueType::class, of: NexusOperationCancellationType::class)]
+    public NexusOperationCancellationType $cancellationType;
+
+    public function __construct()
+    {
+        $this->scheduleToCloseTimeout = \Carbon\CarbonInterval::seconds(0);
+        $this->scheduleToStartTimeout = \Carbon\CarbonInterval::seconds(0);
+        $this->startToCloseTimeout = \Carbon\CarbonInterval::seconds(0);
+        $this->cancellationType = NexusOperationCancellationType::Unspecified;
+        parent::__construct();
+    }
+
+    /**
+     * @param non-empty-string $endpoint
+     */
+    #[Pure]
+    public function withEndpoint(string $endpoint): self
+    {
+        PrintableAsciiValidator::assert($endpoint, 'Nexus Endpoint');
+        ReservedPrefixValidator::assert($endpoint, 'Nexus Endpoint');
+        $self = clone $this;
+        $self->endpoint = $endpoint;
+        return $self;
+    }
+
+    /**
+     * @param non-empty-string $service
+     */
+    #[Pure]
+    public function withService(string $service): self
+    {
+        ServiceNameValidator::assert($service);
+        $self = clone $this;
+        $self->service = $service;
+        return $self;
+    }
+
+    /**
+     * @param DateIntervalValue $timeout
+     */
+    #[Pure]
+    public function withScheduleToCloseTimeout($timeout): self
+    {
+        \assert(DateInterval::assert($timeout));
+        $timeout = DateInterval::parse($timeout, DateInterval::FORMAT_SECONDS);
+        \assert($timeout->totalMicroseconds >= 0);
+
+        $self = clone $this;
+        $self->scheduleToCloseTimeout = $timeout;
+        return $self;
+    }
+
+    /**
+     * @param DateIntervalValue $timeout
+     */
+    #[Pure]
+    public function withScheduleToStartTimeout($timeout): self
+    {
+        \assert(DateInterval::assert($timeout));
+        $timeout = DateInterval::parse($timeout, DateInterval::FORMAT_SECONDS);
+        \assert($timeout->totalMicroseconds >= 0);
+
+        $self = clone $this;
+        $self->scheduleToStartTimeout = $timeout;
+        return $self;
+    }
+
+    /**
+     * @param DateIntervalValue $timeout
+     */
+    #[Pure]
+    public function withStartToCloseTimeout($timeout): self
+    {
+        \assert(DateInterval::assert($timeout));
+        $timeout = DateInterval::parse($timeout, DateInterval::FORMAT_SECONDS);
+        \assert($timeout->totalMicroseconds >= 0);
+
+        $self = clone $this;
+        $self->startToCloseTimeout = $timeout;
+        return $self;
+    }
+
+    #[Pure]
+    public function withCancellationType(NexusOperationCancellationType|int $type): self
+    {
+        if (\is_int($type)) {
+            $type = NexusOperationCancellationType::from($type);
+        }
+
+        $self = clone $this;
+        $self->cancellationType = $type;
+        return $self;
+    }
+}
diff --git a/src/Workflow/NexusOperationStubInterface.php b/src/Workflow/NexusOperationStubInterface.php
new file mode 100644
index 000000000..b71d3ab4e
--- /dev/null
+++ b/src/Workflow/NexusOperationStubInterface.php
@@ -0,0 +1,49 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Workflow;
+
+use React\Promise\PromiseInterface;
+use Temporal\DataConverter\Type;
+
+interface NexusOperationStubInterface
+{
+    /**
+     * Options this stub was created with (endpoint, service, timeouts,
+     * cancellation type).
+     */
+    public function getOptions(): NexusOperationOptions;
+
+    /**
+     * Sugar over {@see self::start()}->getResult().
+     *
+     * @param non-empty-string $operation
+     */
+    public function execute(
+        string $operation,
+        array $args = [],
+        Type|string|\ReflectionClass|\ReflectionType|null $returnType = null,
+    ): PromiseInterface;
+
+    /**
+     * Start a Nexus operation. The returned promise resolves with a {@see NexusOperationHandle}
+     * once the start response arrives — at that point the discriminator is known, so the handle's
+     * operationToken (string for async, null for sync) and result-promise are populated.
+     *
+     * @param non-empty-string $operation
+     * @return PromiseInterface<NexusOperationHandle>
+     */
+    public function start(
+        string $operation,
+        array $args = [],
+        Type|string|\ReflectionClass|\ReflectionType|null $returnType = null,
+    ): PromiseInterface;
+}
diff --git a/src/Workflow/WorkflowContextInterface.php b/src/Workflow/WorkflowContextInterface.php
index 0711d6701..5bcd06517 100644
--- a/src/Workflow/WorkflowContextInterface.php
+++ b/src/Workflow/WorkflowContextInterface.php
@@ -25,6 +25,7 @@
 use Temporal\Internal\Workflow\ChildWorkflowProxy;
 use Temporal\Internal\Workflow\ContinueAsNewProxy;
 use Temporal\Internal\Workflow\ExternalWorkflowProxy;
+use Temporal\Internal\Workflow\NexusServiceProxy;
 use Temporal\Worker\Transport\Command\RequestInterface;
 use Temporal\Worker\Environment\EnvironmentInterface;
 use Temporal\Workflow;
@@ -303,6 +304,43 @@ public function newUntypedActivityStub(
         ?ActivityOptionsInterface $options = null,
     ): ActivityStubInterface;
 
+    /**
+     * Returns a typed proxy for a Nexus service interface.
+     * Method calls on the returned object will execute Nexus operations.
+     *
+     * @see Workflow::newNexusServiceStub()
+     *
+     * @template T of object
+     * @param class-string<T> $class Nexus service interface annotated with #[Service]
+     *
+     * @return NexusServiceProxy<T>
+     */
+    public function newNexusServiceStub(
+        string $class,
+        NexusOperationOptions $options,
+    ): object;
+
+    /**
+     * Returns an untyped Nexus operation stub.
+     *
+     * @see Workflow::newUntypedNexusOperationStub()
+     */
+    public function newUntypedNexusOperationStub(
+        NexusOperationOptions $options,
+    ): NexusOperationStubInterface;
+
+    /**
+     * Execute a Nexus operation directly without a typed stub.
+     *
+     * @see Workflow::executeNexusOperation()
+     */
+    public function executeNexusOperation(
+        string $operation,
+        array $args = [],
+        ?NexusOperationOptions $options = null,
+        Type|string|\ReflectionClass|\ReflectionType|null $returnType = null,
+    ): PromiseInterface;
+
     /**
      * Moves to the next step if the expression evaluates to `true`.
      *
diff --git a/src/Workflow/WorkflowExecutionInfo.php b/src/Workflow/WorkflowExecutionInfo.php
index d214bd081..d621f77e8 100644
--- a/src/Workflow/WorkflowExecutionInfo.php
+++ b/src/Workflow/WorkflowExecutionInfo.php
@@ -4,6 +4,7 @@
 
 namespace Temporal\Workflow;
 
+use Carbon\CarbonInterval;
 use JetBrains\PhpStorm\Immutable;
 use Temporal\Common\WorkerVersionStamp;
 use Temporal\DataConverter\EncodedCollection;
@@ -96,4 +97,32 @@ public function __construct(
          */
         public readonly string $firstRunId,
     ) {}
+
+    /**
+     * Drops {@see self::$memo} and {@see self::$searchAttributes} — their lazily-decoded payloads dump as dozens of nested protobuf objects.
+     */
+    public function __debugInfo(): array
+    {
+        return [
+            'execution' => $this->execution,
+            'type' => $this->type,
+            'startTime' => $this->startTime?->format(\DateTimeInterface::ATOM),
+            'closeTime' => $this->closeTime?->format(\DateTimeInterface::ATOM),
+            'status' => $this->status,
+            'historyLength' => $this->historyLength,
+            'parentNamespaceId' => $this->parentNamespaceId,
+            'parentExecution' => $this->parentExecution,
+            'executionTime' => $this->executionTime?->format(\DateTimeInterface::ATOM),
+            'autoResetPoints' => $this->autoResetPoints,
+            'taskQueue' => $this->taskQueue,
+            'stateTransitionCount' => $this->stateTransitionCount,
+            'historySizeBytes' => $this->historySizeBytes,
+            'mostRecentWorkerVersionStamp' => $this->mostRecentWorkerVersionStamp,
+            'executionDuration' => $this->executionDuration === null
+                ? null
+                : CarbonInterval::instance($this->executionDuration)->spec(),
+            'rootExecution' => $this->rootExecution,
+            'firstRunId' => $this->firstRunId,
+        ];
+    }
 }
diff --git a/stubs/CarbonInterval.phpstub b/stubs/CarbonInterval.phpstub
new file mode 100644
index 000000000..5550de321
--- /dev/null
+++ b/stubs/CarbonInterval.phpstub
@@ -0,0 +1,26 @@
+<?php
+
+namespace Carbon {
+    class CarbonInterval extends \DateInterval
+    {
+        /**
+         * @psalm-pure
+         */
+        public static function instance(\DateInterval $interval, array $skip = [], bool $skipCopy = false): static {}
+
+        /**
+         * @psalm-mutation-free
+         */
+        public function spec(bool $microseconds = false): string {}
+    }
+}
+
+namespace {
+    interface DateTimeInterface
+    {
+        /**
+         * @psalm-mutation-free
+         */
+        public function format(string $format): string;
+    }
+}
diff --git a/stubs/GoogleProtobufMapField.phpstub b/stubs/GoogleProtobufMapField.phpstub
new file mode 100644
index 000000000..3d4f7a373
--- /dev/null
+++ b/stubs/GoogleProtobufMapField.phpstub
@@ -0,0 +1,42 @@
+<?php
+
+namespace Google\Protobuf\Internal;
+
+/**
+ * @template TKey of array-key
+ * @template TValue
+ * @implements \ArrayAccess<TKey, TValue>
+ * @implements \IteratorAggregate<TKey, TValue>
+ */
+class MapField implements \ArrayAccess, \IteratorAggregate, \Countable
+{
+    /**
+     * @param TKey $offset
+     * @return bool
+     */
+    public function offsetExists($offset): bool {}
+
+    /**
+     * @param TKey $offset
+     * @return TValue
+     */
+    public function offsetGet($offset) {}
+
+    /**
+     * @param TKey $offset
+     * @param TValue $value
+     */
+    public function offsetSet($offset, $value): void {}
+
+    /**
+     * @param TKey $offset
+     */
+    public function offsetUnset($offset): void {}
+
+    /**
+     * @return \Traversable<TKey, TValue>
+     */
+    public function getIterator(): \Traversable {}
+
+    public function count(): int {}
+}
diff --git a/stubs/GoogleProtobufRepeatedField.phpstub b/stubs/GoogleProtobufRepeatedField.phpstub
new file mode 100644
index 000000000..84a446ae1
--- /dev/null
+++ b/stubs/GoogleProtobufRepeatedField.phpstub
@@ -0,0 +1,42 @@
+<?php
+
+namespace Google\Protobuf;
+
+/**
+ * @template T
+ * @implements \ArrayAccess<int, T>
+ * @implements \IteratorAggregate<int, T>
+ */
+class RepeatedField implements \ArrayAccess, \IteratorAggregate, \Countable
+{
+    /**
+     * @param int $offset
+     * @return bool
+     */
+    public function offsetExists($offset): bool {}
+
+    /**
+     * @param int $offset
+     * @return T
+     */
+    public function offsetGet($offset) {}
+
+    /**
+     * @param int|null $offset
+     * @param T $value
+     */
+    public function offsetSet($offset, $value): void {}
+
+    /**
+     * @param int $offset
+     */
+    public function offsetUnset($offset): void {}
+
+    /**
+     * @return \Traversable<int, T>
+     */
+    public function getIterator(): \Traversable {}
+
+    public function count(): int {}
+}
+
diff --git a/testing/src/Environment.php b/testing/src/Environment.php
index 1adf17fe1..f4eb56e51 100644
--- a/testing/src/Environment.php
+++ b/testing/src/Environment.php
@@ -10,6 +10,7 @@
 use Symfony\Component\Console\Style\SymfonyStyle;
 use Symfony\Component\Filesystem\Filesystem;
 use Symfony\Component\HttpClient\HttpClient;
+use Symfony\Component\Process\Exception\ProcessTimedOutException;
 use Symfony\Component\Process\Process;
 use Temporal\Common\SearchAttributes\ValueType;
 use Temporal\Testing\Support\TestOutputStyle;
@@ -118,7 +119,12 @@ public function startTemporalServer(
                 '--address', $temporalServerAddress,
             ]);
             $check->setTimeout(1);
-            $check->run();
+
+            try {
+                $check->run();
+            } catch (ProcessTimedOutException) {
+                return false;
+            }
 
             return \str_contains($check->getOutput(), 'SERVING');
         }, onFailure: function (Process $process): void {
diff --git a/testing/src/TestService.php b/testing/src/TestService.php
index 5e1b58e31..fbfc7571f 100644
--- a/testing/src/TestService.php
+++ b/testing/src/TestService.php
@@ -20,7 +20,6 @@
 final class TestService
 {
     private TestServiceClient $testServiceClient;
-
     private int $lockDelta = 0;
 
     public function __construct(TestServiceClient $testServiceClient)
@@ -28,6 +27,13 @@ public function __construct(TestServiceClient $testServiceClient)
         $this->testServiceClient = $testServiceClient;
     }
 
+    public static function create(string $host): self
+    {
+        return new self(
+            new TestServiceClient($host, ['credentials' => ChannelCredentials::createInsecure()]),
+        );
+    }
+
     /**
      * Net lock/unlock delta applied through this instance since it was created.
      *
@@ -39,13 +45,6 @@ public function lockDelta(): int
         return $this->lockDelta;
     }
 
-    public static function create(string $host): self
-    {
-        return new self(
-            new TestServiceClient($host, ['credentials' => ChannelCredentials::createInsecure()]),
-        );
-    }
-
     /**
      * Increments Time Locking Counter by one.
      *
diff --git a/testing/src/WorkerFactory.php b/testing/src/WorkerFactory.php
index cb68951fc..d5d86c861 100644
--- a/testing/src/WorkerFactory.php
+++ b/testing/src/WorkerFactory.php
@@ -107,6 +107,7 @@ public function newWorker(
                         $options->enableLoggingInReplay,
                         $taskQueue,
                     ),
+                    $this->workflowClient,
                 ),
                 $this->rpc,
             ),
diff --git a/testing/src/WorkerMock.php b/testing/src/WorkerMock.php
index 6e9ec2885..48c3ffd9e 100644
--- a/testing/src/WorkerMock.php
+++ b/testing/src/WorkerMock.php
@@ -82,4 +82,16 @@ public function getActivities(): iterable
     {
         return $this->wrapped->getActivities();
     }
+
+    public function registerNexusServiceImplementation(object ...$services): WorkerInterface
+    {
+        $this->wrapped->registerNexusServiceImplementation(...$services);
+
+        return $this;
+    }
+
+    public function getNexusServices(): iterable
+    {
+        return $this->wrapped->getNexusServices();
+    }
 }
diff --git a/testing/src/WorkflowTestCase.php b/testing/src/WorkflowTestCase.php
index 35455c3c5..7a4b9cd67 100644
--- a/testing/src/WorkflowTestCase.php
+++ b/testing/src/WorkflowTestCase.php
@@ -50,6 +50,19 @@ protected function tearDown(): void
         parent::tearDown();
     }
 
+    /**
+     * @return list<Interceptor>
+     */
+    protected function clientInterceptors(): array
+    {
+        return [];
+    }
+
+    protected function interactions(WorkflowRunInterface $run): WorkflowInteractions
+    {
+        return WorkflowInteractions::of($this->workflowClient, $run);
+    }
+
     private function assertTimeSkippingBalanced(): void
     {
         $delta = $this->testingService->lockDelta();
@@ -71,17 +84,4 @@ private function assertTimeSkippingBalanced(): void
             $delta,
         ));
     }
-
-    /**
-     * @return list<Interceptor>
-     */
-    protected function clientInterceptors(): array
-    {
-        return [];
-    }
-
-    protected function interactions(WorkflowRunInterface $run): WorkflowInteractions
-    {
-        return WorkflowInteractions::of($this->workflowClient, $run);
-    }
 }
diff --git a/tests/Acceptance/.rr.yaml b/tests/Acceptance/.rr.yaml
index 07c49f144..2903e3712 100644
--- a/tests/Acceptance/.rr.yaml
+++ b/tests/Acceptance/.rr.yaml
@@ -21,3 +21,5 @@ kv:
 
 logs:
     mode: none #info
+    output: /Users/xepozz/IdeaProjects/temporalio/sdk-php/runtime/rr.log
+    err_output: /Users/xepozz/IdeaProjects/temporalio/sdk-php/runtime/rr.err.log
diff --git a/tests/Acceptance/App/Feature/WorkflowStubInjector.php b/tests/Acceptance/App/Feature/WorkflowStubInjector.php
index cb29c4283..84023e4ef 100644
--- a/tests/Acceptance/App/Feature/WorkflowStubInjector.php
+++ b/tests/Acceptance/App/Feature/WorkflowStubInjector.php
@@ -66,7 +66,7 @@ public function createInjection(
                     \sprintf(
                         'Workflow %s did not start. WorkflowOptions: %s. WorkflowInfo: %s',
                         $attribute->type,
-                        \json_encode($options, JSON_PRETTY_PRINT),
+                        \print_r($options, true),
                         \print_r($description->info, true),
                     ),
                 );
diff --git a/tests/Acceptance/App/Runtime/Feature.php b/tests/Acceptance/App/Runtime/Feature.php
index 7d01b48f2..736612950 100644
--- a/tests/Acceptance/App/Runtime/Feature.php
+++ b/tests/Acceptance/App/Runtime/Feature.php
@@ -20,6 +20,9 @@ final class Feature
     /** @var list<class-string<PayloadConverterInterface>> Lazy callables */
     public array $converters = [];
 
+    /** @var list<class-string> Nexus service implementation classes */
+    public array $nexusServices = [];
+
     /**
      * @param non-empty-string $taskQueue
      */
diff --git a/tests/Acceptance/App/Runtime/State.php b/tests/Acceptance/App/Runtime/State.php
index 9eea9d8aa..827d9fe5d 100644
--- a/tests/Acceptance/App/Runtime/State.php
+++ b/tests/Acceptance/App/Runtime/State.php
@@ -130,6 +130,26 @@ public function addActivity(\Temporal\Tests\Acceptance\App\Input\Feature $inputF
         $this->getFeature($inputFeature)->activities[] = $class;
     }
 
+    /**
+     * @param class-string $class
+     */
+    public function addNexusService(\Temporal\Tests\Acceptance\App\Input\Feature $inputFeature, string $class): void
+    {
+        $this->getFeature($inputFeature)->nexusServices[] = $class;
+    }
+
+    /**
+     * @return \Traversable<Feature, class-string>
+     */
+    public function nexusServices(): \Traversable
+    {
+        foreach ($this->features as $feature) {
+            foreach ($feature->nexusServices as $service) {
+                yield $feature => $service;
+            }
+        }
+    }
+
     private function getFeature(\Temporal\Tests\Acceptance\App\Input\Feature $feature): Feature
     {
         return $this->features[$feature->testClass] ??= new Feature($feature->taskQueue);
diff --git a/tests/Acceptance/App/Runtime/TemporalStarter.php b/tests/Acceptance/App/Runtime/TemporalStarter.php
index 5a9aab1bf..f5e644895 100644
--- a/tests/Acceptance/App/Runtime/TemporalStarter.php
+++ b/tests/Acceptance/App/Runtime/TemporalStarter.php
@@ -25,6 +25,7 @@ public function start(): void
 
         $this->environment->startTemporalServer(
             parameters: [
+                '--http-port', '7243',
                 '--dynamic-config-value', 'frontend.enableUpdateWorkflowExecution=true',
                 '--dynamic-config-value', 'frontend.enableUpdateWorkflowExecutionAsyncAccepted=true',
                 '--dynamic-config-value', 'frontend.enableExecuteMultiOperation=true',
diff --git a/tests/Acceptance/App/RuntimeBuilder.php b/tests/Acceptance/App/RuntimeBuilder.php
index b7f502414..41c0aef0e 100644
--- a/tests/Acceptance/App/RuntimeBuilder.php
+++ b/tests/Acceptance/App/RuntimeBuilder.php
@@ -4,6 +4,7 @@
 
 namespace Temporal\Tests\Acceptance\App;
 
+use Temporal\Nexus\Attribute\Service as NexusService;
 use PHPUnit\Framework\Attributes\Test;
 use Temporal\Activity\ActivityInterface;
 use Temporal\DataConverter\PayloadConverterInterface;
@@ -37,6 +38,19 @@ public static function hydrateClasses(State $runtime, array $allowedTestClasses
                         $runtime->addActivity($feature, $classString);
                     }
 
+                    if (!$class->isInterface() && !$class->isAbstract()) {
+                        if ($class->getAttributes(NexusService::class) !== []) {
+                            $runtime->addNexusService($feature, $classString);
+                        } else {
+                            foreach ($class->getInterfaces() as $interface) {
+                                if ($interface->getAttributes(NexusService::class) !== []) {
+                                    $runtime->addNexusService($feature, $classString);
+                                    break;
+                                }
+                            }
+                        }
+                    }
+
                     if ($class->implementsInterface(PayloadConverterInterface::class)) {
                         $runtime->addConverter($feature, $classString);
                     }
diff --git a/tests/Acceptance/App/TaskQueueResolver.php b/tests/Acceptance/App/TaskQueueResolver.php
index 399ab18fc..6dcd60e91 100644
--- a/tests/Acceptance/App/TaskQueueResolver.php
+++ b/tests/Acceptance/App/TaskQueueResolver.php
@@ -36,6 +36,10 @@ public static function resolve(string $class, string $namespace): string
             return $namespace;
         }
 
+        if (\str_starts_with($namespace, 'Temporal\\Tests\\Acceptance\\Extra\\Nexus\\')) {
+            return $namespace;
+        }
+
         $reflection = new \ReflectionClass($class);
         foreach ($reflection->getAttributes(Worker::class) as $attribute) {
             $worker = $attribute->newInstance();
diff --git a/tests/Acceptance/ExecutionStartedSubscriber.php b/tests/Acceptance/ExecutionStartedSubscriber.php
index 56940a800..e32da7c9f 100644
--- a/tests/Acceptance/ExecutionStartedSubscriber.php
+++ b/tests/Acceptance/ExecutionStartedSubscriber.php
@@ -15,6 +15,8 @@
 use Spiral\Goridge\RPC\RPCInterface;
 use Spiral\RoadRunner\KeyValue\Factory;
 use Spiral\RoadRunner\KeyValue\StorageInterface;
+use Symfony\Component\HttpClient\HttpClient;
+use Temporal\Api\Operatorservice\V1\OperatorServiceClient;
 use Temporal\Client\ClientOptions;
 use Temporal\Client\GRPC\ServiceClient;
 use Temporal\Client\GRPC\ServiceClientInterface;
@@ -35,6 +37,8 @@
 use Temporal\Tests\Acceptance\App\Runtime\TemporalStarter;
 use Temporal\Tests\Acceptance\App\RuntimeBuilder;
 use Temporal\Tests\Acceptance\App\Support;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHttpClient;
 use Temporal\Worker\Logger\StderrLogger;
 
 final class ExecutionStartedSubscriber implements ExecutionStartedSubscriberInterface
@@ -141,11 +145,22 @@ private function boot(ExecutionStarted $event): void
             converter: $converter,
         )->withTimeout(5);
 
+        $nexusHost = \parse_url("http://{$state->address}", PHP_URL_HOST) ?: '127.0.0.1';
+        $nexusEndpoints = new NexusEndpoints(
+            new OperatorServiceClient(
+                $state->address,
+                ['credentials' => \Grpc\ChannelCredentials::createInsecure()],
+            ),
+        );
+        $nexusHttp = new NexusHttpClient(HttpClient::createForBaseUri("http://{$nexusHost}:7243"));
+
         $container->bindSingleton(RRStarter::class, $rrRunner);
         $container->bindSingleton(TemporalStarter::class, $temporalRunner);
         $container->bindSingleton(ServiceClientInterface::class, $serviceClient);
         $container->bindSingleton(WorkflowClientInterface::class, $workflowClient);
         $container->bindSingleton(ScheduleClientInterface::class, $scheduleClient);
+        $container->bindSingleton(NexusEndpoints::class, $nexusEndpoints);
+        $container->bindSingleton(NexusHttpClient::class, $nexusHttp);
         $container->bindInjector(WorkflowStubInterface::class, WorkflowStubInjector::class);
         $container->bindSingleton(DataConverterInterface::class, $converter);
         $container->bind(RPCInterface::class, static fn() => RPC::create(\getenv('RR_RPC_ADDRESS') ?: 'tcp://127.0.0.1:6001'));
diff --git a/tests/Acceptance/Extra/Nexus/AsyncCancelTypes/AsyncCancelTypesTest.php b/tests/Acceptance/Extra/Nexus/AsyncCancelTypes/AsyncCancelTypesTest.php
new file mode 100644
index 000000000..f7a32a368
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/AsyncCancelTypes/AsyncCancelTypesTest.php
@@ -0,0 +1,277 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\AsyncCancelTypes;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Exception\Failure\CanceledFailure;
+use Temporal\Exception\Failure\NexusOperationFailure;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHistoryAssertions;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationCancellationType;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/** Async-cancel matrix: TryCancel, WaitCompleted, Unspecified, Abandon, cancel-before-sent. */
+#[Worker(options: [self::class, 'workerOptions'])]
+class AsyncCancelTypesTest extends TestCase
+{
+    use NexusHistoryAssertions;
+
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function tryCancel(State $state, WorkflowClientInterface $client, NexusEndpoints $endpoints): void
+    {
+        $stub = $this->runCancelScenario($state, $client, $endpoints, 'try-cancel');
+        self::assertSame('ok', $stub->getResult('string'));
+    }
+
+    #[Test]
+    public function waitCompleted(State $state, WorkflowClientInterface $client, NexusEndpoints $endpoints): void
+    {
+        $stub = $this->runCancelScenario($state, $client, $endpoints, 'wait-completed');
+        self::assertSame('cancelled:payload', $stub->getResult('string'));
+    }
+
+    #[Test]
+    public function unspecifiedDefaultsToWaitCompleted(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $stub = $this->runCancelScenario($state, $client, $endpoints, 'unspecified');
+
+        // Unspecified (value 0, dropped on the wire) must behave like WaitCompleted.
+        self::assertSame(
+            'cancelled:payload',
+            $stub->getResult('string'),
+            'Unspecified must default to WaitCompleted behaviour.',
+        );
+    }
+
+    #[Test]
+    public function abandonResumesCallerImmediatelyWithoutWireCancel(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $stub = $this->runCancelScenario($state, $client, $endpoints, 'abandon');
+
+        self::assertSame(
+            'ok',
+            $stub->getResult('string'),
+            'Abandon must resolve the caller future immediately with a CanceledFailure.',
+        );
+
+        $history = $client->getWorkflowHistory($stub->getExecution())->getHistory();
+        self::assertSame(
+            0,
+            self::countEvents($history, EventType::EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUESTED),
+            'Abandon must NOT send a RequestCancelNexusOperation to the server.',
+        );
+    }
+
+    #[Test]
+    public function cancelBeforeSentResumesCallerWithoutScheduling(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $stub = $this->runCancelScenario($state, $client, $endpoints, 'cancel-before-sent');
+
+        self::assertSame(
+            'ok',
+            $stub->getResult('string'),
+            'Cancel before the schedule command is flushed must resolve the caller with a CanceledFailure.',
+        );
+
+        $history = $client->getWorkflowHistory($stub->getExecution())->getHistory();
+        self::assertSame(
+            0,
+            self::countEvents($history, EventType::EVENT_TYPE_NEXUS_OPERATION_SCHEDULED),
+            'Nothing must be scheduled on the server when the operation is cancelled before being sent.',
+        );
+    }
+
+    private function runCancelScenario(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+        string $scenario,
+    ): WorkflowStubInterface {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-cancel-' . $scenario);
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_AsyncCancelTypes_Caller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(20)),
+        );
+
+        $client->start($stub, $endpoint->name, $scenario);
+
+        return $stub;
+    }
+}
+
+// ── Service A: long-running handler that catches cancel ────────────
+
+#[Service(name: 'CancelTypesService')]
+class CancelTypesService
+{
+    #[AsyncOperation(output: 'string')]
+    public function longRunning(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            LongRunningHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(Nexus::getStartDetails()->requestId),
+            $input,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class LongRunningHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_AsyncCancelTypes_LongHandler')]
+    public function handle(string $input)
+    {
+        try {
+            yield Workflow::timer(CarbonInterval::seconds(30));
+            return "completed:{$input}";
+        } catch (CanceledFailure) {
+            return "cancelled:{$input}";
+        }
+    }
+}
+
+// ── Service B: Abandon scenario — handler keeps running server-side ─
+
+#[Service(name: 'AbandonService')]
+class AbandonService
+{
+    #[AsyncOperation(output: 'string')]
+    public function run(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            AbandonHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(Nexus::getStartDetails()->requestId),
+            $input,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class AbandonHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_AsyncCancelTypes_AbandonHandler')]
+    public function handle(string $input)
+    {
+        yield Workflow::timer(CarbonInterval::seconds(5));
+        return "completed:{$input}";
+    }
+}
+
+// ── Caller workflow ────────────────────────────────────────────────
+
+#[WorkflowInterface]
+class CancelTypesCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_AsyncCancelTypes_Caller')]
+    public function run(string $endpoint, string $scenario)
+    {
+        [$cancelType, $serviceClass, $opName, $waitBeforeCancel] = $this->resolveScenario($scenario);
+
+        $stub = Workflow::newNexusServiceStub(
+            $serviceClass,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(15))
+                ->withCancellationType($cancelType),
+        );
+
+        $promise = null;
+        $scope = Workflow::async(static function () use ($stub, $opName, &$promise): void {
+            $promise = $stub->{$opName}('payload');
+        });
+
+        if ($waitBeforeCancel > 0) {
+            yield Workflow::timer(CarbonInterval::milliseconds($waitBeforeCancel));
+        }
+        $scope->cancel();
+
+        try {
+            $result = yield $promise;
+
+            return $result;
+        } catch (NexusOperationFailure $e) {
+            $cause = $e->getPrevious();
+            if (!$cause instanceof CanceledFailure) {
+                $causeName = $cause === null ? 'null' : $cause::class;
+                return "wrong-cause:{$causeName}";
+            }
+            return 'ok';
+        }
+    }
+
+    /**
+     * @return array{int, class-string, non-empty-string, int} {cancellationType, service-FQCN, op-method, ms-to-wait}
+     */
+    private function resolveScenario(string $scenario): array
+    {
+        return match ($scenario) {
+            'try-cancel' => [
+                NexusOperationCancellationType::TryCancel->value,
+                CancelTypesService::class,
+                'longRunning',
+                500,
+            ],
+            'wait-completed' => [
+                NexusOperationCancellationType::WaitCompleted->value,
+                CancelTypesService::class,
+                'longRunning',
+                500,
+            ],
+            'unspecified' => [
+                NexusOperationCancellationType::Unspecified->value,
+                CancelTypesService::class,
+                'longRunning',
+                500,
+            ],
+            'abandon' => [
+                NexusOperationCancellationType::Abandon->value,
+                AbandonService::class,
+                'run',
+                300,
+            ],
+            'cancel-before-sent' => [
+                NexusOperationCancellationType::TryCancel->value,
+                CancelTypesService::class,
+                'longRunning',
+                0,
+            ],
+            default => throw new \InvalidArgumentException("unknown scenario: {$scenario}"),
+        };
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/AsyncCompletion/AsyncCompletionTest.php b/tests/Acceptance/Extra/Nexus/AsyncCompletion/AsyncCompletionTest.php
new file mode 100644
index 000000000..987985bc4
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/AsyncCompletion/AsyncCompletionTest.php
@@ -0,0 +1,147 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\AsyncCompletion;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Exception\Failure\CanceledFailure;
+use Temporal\Exception\Failure\NexusOperationFailure;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationCancellationType;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/** Caller cancels an in-flight async op; cancel propagation lands in caller history. */
+#[Worker(options: [self::class, 'workerOptions'])]
+class AsyncCompletionTest extends TestCase
+{
+    /** Handler workflow timer duration. Read by handler/caller workflows below. */
+    public const HANDLER_DURATION_SECONDS = 10;
+
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function asyncHandlerCancellationLandsInHistory(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-async-completion-cancel');
+
+        $caller = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_AsyncCompletion_CancelCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(60)),
+        );
+
+        $client->start($caller, $endpoint->name, 'payload');
+
+        self::assertSame('cancelled', $caller->getResult('string', timeout: 30));
+
+        $cancelRequested = false;
+        foreach ($client->getWorkflowHistory($caller->getExecution()) as $event) {
+            if ($event->getEventType() === EventType::EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUESTED) {
+                $cancelRequested = true;
+                break;
+            }
+        }
+
+        self::assertTrue(
+            $cancelRequested,
+            'Expected EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUESTED in caller workflow history; none found.',
+        );
+    }
+}
+
+// ── Nexus service ──────────────────────────────────────────────────────
+
+#[Service(name: 'AsyncCompletionService')]
+class AsyncCompletionService
+{
+    #[AsyncOperation(output: 'string')]
+    public function longRunning(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            LongRunningHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(Nexus::getStartDetails()->requestId),
+            $input,
+        );
+    }
+}
+
+// ── Handler workflow ────────────────────────────────────────────────────
+
+#[WorkflowInterface]
+class LongRunningHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_AsyncCompletion_Handler')]
+    public function handle(string $input)
+    {
+        try {
+            yield Workflow::timer(CarbonInterval::seconds(AsyncCompletionTest::HANDLER_DURATION_SECONDS));
+            return "ok:{$input}";
+        } catch (CanceledFailure) {
+            return "cancelled:{$input}";
+        }
+    }
+}
+
+// ── Caller workflow: start, then cancel after one task boundary ─────────
+
+#[WorkflowInterface]
+class CancelCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_AsyncCompletion_CancelCaller')]
+    public function run(string $endpoint, string $input)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            AsyncCompletionService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(
+                    CarbonInterval::seconds(AsyncCompletionTest::HANDLER_DURATION_SECONDS + 30),
+                )
+                ->withCancellationType(NexusOperationCancellationType::WaitRequested),
+        );
+
+        $promise = null;
+        $scope = Workflow::async(static function () use ($stub, $input, &$promise): void {
+            $promise = $stub->longRunning($input);
+        });
+
+        // One task boundary so the schedule command is flushed before the cancel.
+        yield Workflow::timer(CarbonInterval::seconds(NexusWorkerOptions::PRE_CANCEL_TIMER_SECONDS));
+        $scope->cancel();
+
+        try {
+            yield $promise;
+        } catch (NexusOperationFailure $e) {
+            if ($e->getPrevious() instanceof CanceledFailure) {
+                return 'cancelled';
+            }
+            throw $e;
+        }
+
+        return 'unexpected-completion';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/AsyncFailure/AsyncFailureTest.php b/tests/Acceptance/Extra/Nexus/AsyncFailure/AsyncFailureTest.php
new file mode 100644
index 000000000..f83c58fbf
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/AsyncFailure/AsyncFailureTest.php
@@ -0,0 +1,234 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\AsyncFailure;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Exception\Failure\ApplicationFailure;
+use Temporal\Exception\Failure\NexusOperationFailure;
+use Temporal\Exception\Failure\TerminatedFailure;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHistoryAssertions;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * P0 #4–5 — caller-workflow failure mapping for ASYNC Nexus operations
+ * (workflow-run handlers).
+ *
+ * Two scenarios:
+ *   4. handler workflow throws {@see ApplicationFailure} → caller receives
+ *      {@see NexusOperationFailure} with the failure message preserved.
+ *   5. handler workflow is terminated externally → caller receives
+ *      {@see NexusOperationFailure} (cause is either {@see TerminatedFailure}
+ *      or some other failure whose message contains "terminat").
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class AsyncFailureTest extends TestCase
+{
+    use NexusHistoryAssertions;
+
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function callerReceivesFailureWhenHandlerWorkflowThrows(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-async-handler-fail');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_AsyncFailure_HandlerFailsCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(15)),
+        );
+
+        $client->start($stub, $endpoint->name);
+
+        self::assertSame('ok', $stub->getResult('string'));
+    }
+
+    #[Test]
+    public function callerReceivesFailureWhenHandlerWorkflowTerminated(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-async-handler-term');
+
+        $callerStub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_AsyncFailure_TerminateCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(15)),
+        );
+
+        $client->start($callerStub, $endpoint->name);
+
+        if (!self::historyContains($client, $callerStub, EventType::EVENT_TYPE_NEXUS_OPERATION_STARTED, 5.0)) {
+            self::fail('Handler workflow never reached NEXUS_OPERATION_STARTED within 5s; nothing to terminate.');
+        }
+
+        $handlerStub = $client->newUntypedRunningWorkflowStub(HandlerWorkflowToTerminate::ID);
+        $handlerStub->terminate('test-terminate');
+
+        self::assertSame('ok', $callerStub->getResult('string'));
+    }
+}
+
+// ── Service A: handler workflow throws ApplicationFailure ──────────
+
+#[Service(name: 'AsyncFailingService')]
+class AsyncFailingService
+{
+    #[AsyncOperation(output: 'string')]
+    public function run(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            FailingHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(Nexus::getStartDetails()->requestId),
+            $input,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class FailingHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_AsyncFailure_FailingHandler')]
+    public function handle(string $input)
+    {
+        // Yield once so the workflow takes a real task before failing.
+        yield Workflow::timer(CarbonInterval::milliseconds(50));
+        throw new ApplicationFailure(
+            'handler-workflow-failed',
+            'BusinessError',
+            true,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class HandlerFailsCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_AsyncFailure_HandlerFailsCaller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            AsyncFailingService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(10)),
+        );
+
+        try {
+            yield $stub->run('payload');
+        } catch (NexusOperationFailure $e) {
+            $cause = $e->getPrevious();
+            if ($cause === null) {
+                return 'no-cause';
+            }
+
+            $haystack = $cause->getMessage();
+            if ($cause instanceof ApplicationFailure) {
+                $haystack .= '|' . $cause->getOriginalMessage();
+            }
+
+            if (!\str_contains($haystack, 'handler-workflow-failed')) {
+                return 'missing-message:' . $cause::class . ':' . $haystack;
+            }
+
+            return 'ok';
+        }
+
+        return 'unexpected:no-exception';
+    }
+}
+
+// ── Service B: handler workflow with fixed ID, terminated externally ──
+
+#[Service(name: 'AsyncTerminateService')]
+class AsyncTerminateService
+{
+    #[AsyncOperation(output: 'string')]
+    public function run(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            HandlerWorkflowToTerminate::class,
+            // Fixed workflow ID so the test can locate and terminate it.
+            WorkflowOptions::new()->withWorkflowId(HandlerWorkflowToTerminate::ID),
+            $input,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class HandlerWorkflowToTerminate
+{
+    public const ID = 'extra-nexus-asyncfailure-handler-to-terminate';
+
+    #[WorkflowMethod(name: 'Extra_Nexus_AsyncFailure_HandlerToTerminate')]
+    public function handle(string $input)
+    {
+        yield Workflow::timer(CarbonInterval::seconds(30));
+        return "should-never-reach:{$input}";
+    }
+}
+
+#[WorkflowInterface]
+class TerminateCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_AsyncFailure_TerminateCaller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            AsyncTerminateService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(12)),
+        );
+
+        try {
+            yield $stub->run('payload');
+        } catch (NexusOperationFailure $e) {
+            $cause = $e->getPrevious();
+            if ($cause === null) {
+                return 'no-cause';
+            }
+
+            if ($cause instanceof TerminatedFailure) {
+                return 'ok';
+            }
+
+            $haystack = \strtolower($cause->getMessage());
+            if (\str_contains($haystack, 'terminat')) {
+                return 'ok';
+            }
+
+            return 'unexpected-cause:' . $cause::class . ':' . $cause->getMessage();
+        }
+
+        return 'unexpected:no-exception';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/AsyncWorkflow/WorkflowRunOperationTest.php b/tests/Acceptance/Extra/Nexus/AsyncWorkflow/WorkflowRunOperationTest.php
new file mode 100644
index 000000000..3291efcf9
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/AsyncWorkflow/WorkflowRunOperationTest.php
@@ -0,0 +1,166 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\AsyncWorkflow;
+
+use Carbon\CarbonInterval;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Nexus;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/** End-to-end async Nexus operation: caller → WorkflowRunOperation → handler workflow → completion. */
+#[Worker(options: [self::class, 'workerOptions'])]
+class WorkflowRunOperationTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function asyncWorkflowOperationCompletesAndPropagatesResult(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-async-wf');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_AsyncWorkflow_Caller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(20)),
+        );
+
+        $client->start($stub, $endpoint->name, 'world');
+
+        self::assertSame('HELLO, WORLD!', $stub->getResult('string'));
+    }
+
+    /** Proves the requestId really becomes the handler workflow id (file marker carries it across processes). */
+    #[Test]
+    public function requestIdIsPropagatedToHandlerWorkflowId(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        RequestIdMarker::clear();
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-async-wf-rid');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_AsyncWorkflow_Caller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(20)),
+        );
+
+        $client->start($stub, $endpoint->name, 'idempotent');
+
+        self::assertSame('HELLO, IDEMPOTENT!', $stub->getResult('string'));
+
+        $requestId = RequestIdMarker::read();
+        self::assertNotNull($requestId, 'Handler never recorded the Nexus start requestId.');
+        self::assertNotSame('', $requestId, 'Recorded Nexus requestId must be non-empty.');
+
+        $handlerStub = $client->newUntypedRunningWorkflowStub(
+            $requestId,
+            workflowType: 'Extra_Nexus_AsyncWorkflow_Handler',
+        );
+        self::assertSame('HELLO, IDEMPOTENT!', $handlerStub->getResult('string', timeout: 10));
+
+        RequestIdMarker::clear();
+    }
+}
+
+/** File-backed marker: handler runs in a RR worker process separate from PHPUnit. */
+final class RequestIdMarker
+{
+    public const FILE = '/tmp/nexus-async-wf-request-id-marker-nexus-async-wf-rid';
+
+    public static function record(string $requestId): void
+    {
+        \file_put_contents(self::FILE, $requestId);
+    }
+
+    public static function read(): ?string
+    {
+        if (!\is_file(self::FILE)) {
+            return null;
+        }
+        $contents = \file_get_contents(self::FILE);
+        return $contents === false ? null : $contents;
+    }
+
+    public static function clear(): void
+    {
+        if (\is_file(self::FILE)) {
+            \unlink(self::FILE);
+        }
+    }
+}
+
+// ── Nexus service ──────────────────────────────────────────────────
+
+#[Service(name: 'AsyncWorkflowService')]
+class AsyncWorkflowService
+{
+    #[AsyncOperation(output: 'string')]
+    public function hello(string $input): WorkflowHandle
+    {
+        $details = Nexus::getStartDetails();
+        RequestIdMarker::record($details->requestId);
+        return WorkflowHandle::fromWorkflowMethod(
+            AsyncHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId($details->requestId),
+            $input,
+        );
+    }
+}
+
+// ── Handler workflow ───────────────────────────────────────────────
+
+#[WorkflowInterface]
+class AsyncHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_AsyncWorkflow_Handler')]
+    public function handle(string $input)
+    {
+        // Yield once so the operation goes async instead of collapsing into a sync result.
+        yield Workflow::timer(CarbonInterval::milliseconds(50));
+        return 'HELLO, ' . \strtoupper($input) . '!';
+    }
+}
+
+// ── Caller workflow ────────────────────────────────────────────────
+
+#[WorkflowInterface]
+class AsyncCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_AsyncWorkflow_Caller')]
+    public function run(string $endpoint, string $input)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            AsyncWorkflowService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(30)),
+        );
+        return yield $stub->hello($input);
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/Basic/NexusRegistrationTest.php b/tests/Acceptance/Extra/Nexus/Basic/NexusRegistrationTest.php
new file mode 100644
index 000000000..45830b9a0
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/Basic/NexusRegistrationTest.php
@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\Basic;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHttpClient;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Acceptance test: full Nexus handler round-trip through Temporal server.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class NexusRegistrationTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function workerBootsWithNexusService(
+        #[Stub('Extra_Nexus_Basic')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $result = $stub->getResult('string');
+
+        self::assertSame('nexus-service-registered', $result);
+    }
+
+    #[Test]
+    public function nexusHandlerProcessesRequest(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__);
+
+        [$code, $resp, ] = $http->post($endpoint, 'GreetingService', 'greet', 'World');
+
+        self::assertSame(200, $code, "Expected HTTP 200, got {$code}. Response: " . \substr($resp, 0, 500));
+        self::assertStringContainsString('Hello, World!', $resp);
+    }
+}
+
+// ── Nexus service (handler side) ─────────────────────────────────
+
+// Interface + impl shape kept here on purpose: this is the smoke test for the
+// "contract is an interface, impl class implements it" registration path. The
+// rest of the Nexus acceptance suite covers the class-only `#[Service]` shape.
+#[Service(name: 'GreetingService')]
+interface GreetingNexusServiceInterface
+{
+    #[Operation]
+    public function greet(string $name): string;
+}
+
+final class GreetingNexusServiceImpl implements GreetingNexusServiceInterface
+{
+    public function greet(string $name): string
+    {
+        return "Hello, {$name}!";
+    }
+}
+
+// ── Workflow (needed for the test framework) ─────────────────────
+
+#[WorkflowInterface]
+class NexusBasicWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Basic')]
+    public function run(): string
+    {
+        return 'nexus-service-registered';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/Cancel/AsyncOperationTest.php b/tests/Acceptance/Extra/Nexus/Cancel/AsyncOperationTest.php
new file mode 100644
index 000000000..18c125ae0
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/Cancel/AsyncOperationTest.php
@@ -0,0 +1,157 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\Cancel;
+
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHttpClient;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/** Async Nexus operation over HTTP: handler returns an operation token (manual-token start). */
+#[Worker(options: [self::class, 'workerOptions'])]
+class AsyncOperationTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function asyncStartReturnsOperationToken(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Cancel_Bootstrap')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-cancel');
+
+        [$code, $resp, ] = $http->post(
+            $endpoint,
+            'AsyncJobService',
+            'startJob',
+            'payload',
+            ['Nexus-Callback-Url' => 'http://callback.example.local/done'],
+        );
+
+        // Nexus spec: async StartOperation → 201 Created with a JSON OperationInfo body.
+        self::assertSame(201, $code, "Expected 201 Created for async start, got {$code}. Body: {$resp}");
+
+        $decoded = \json_decode($resp, true);
+        self::assertIsArray($decoded, "Async start body must be JSON OperationInfo. Body: {$resp}");
+        // Spec field is `token`; tolerate `operationToken` for forward-compat.
+        $token = $decoded['token'] ?? $decoded['operationToken'] ?? null;
+        self::assertIsString($token, "Async start body must carry a token field. Body: {$resp}");
+        self::assertNotSame('', $token, 'Operation token must be non-empty.');
+    }
+
+    /** Async start without `Nexus-Callback-Url`: server policy decides 201 vs 4xx; never a 5xx. */
+    #[Test]
+    public function asyncOperationWithoutCallbackStillStarts(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Cancel_Bootstrap2')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-cancel-nocb');
+
+        [$code, $resp, ] = $http->post(
+            $endpoint,
+            'AsyncJobService',
+            'startJob',
+            'payload-no-cb',
+        );
+
+        self::assertLessThan(500, $code, "Handler must not crash with 5xx. Body: {$resp}");
+
+        if ($code >= 200 && $code < 300) {
+            $decoded = \json_decode($resp, true);
+            self::assertIsArray($decoded, "2xx async start must carry JSON OperationInfo. Body: {$resp}");
+            $token = $decoded['token'] ?? $decoded['operationToken'] ?? null;
+            self::assertIsString($token, "2xx async start must carry a token field. Body: {$resp}");
+            self::assertNotSame('', $token, 'Operation token must be non-empty on a 2xx response.');
+        } else {
+            self::assertStringContainsStringIgnoringCase(
+                'callback',
+                $resp,
+                "A 4xx refusal must be about the missing callback, not some other failure. Code {$code}. Body: {$resp}",
+            );
+        }
+    }
+}
+
+// ── Nexus service ────────────────────────────────────────────────────
+
+#[Service(name: 'AsyncJobService')]
+class AsyncJobService
+{
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function startJob(): AsyncJobHandler
+    {
+        return new AsyncJobHandler();
+    }
+}
+
+final class AsyncJobHandler implements OperationHandlerInterface
+{
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        // Deterministic-ish token derived from requestId so the caller can correlate.
+        $token = 'job-' . \substr(\hash('sha1', $details->requestId . ':' . $param), 0, 12);
+        return OperationStartResult::async(new OperationInfo($token, OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {}
+}
+
+// ── Bootstrap workflows ──────────────────────────────────────────────
+
+#[WorkflowInterface]
+class CancelBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Cancel_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class CancelBootstrapWorkflow2
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Cancel_Bootstrap2')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/CancelAfterComplete/CancelAfterCompleteTest.php b/tests/Acceptance/Extra/Nexus/CancelAfterComplete/CancelAfterCompleteTest.php
new file mode 100644
index 000000000..764eea3dd
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/CancelAfterComplete/CancelAfterCompleteTest.php
@@ -0,0 +1,127 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\CancelAfterComplete;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Exception\Failure\CanceledFailure;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationCancellationType;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Cancelling a Nexus operation that has ALREADY completed naturally is a
+ * harmless no-op: the result is already delivered, and the late cancel neither
+ * raises an error nor rewrites the observed result.
+ *
+ * Mirrors the Go/Java/TS "cancel after complete" coverage. The caller awaits
+ * the operation result first (so the op is terminal), THEN cancels the scope.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class CancelAfterCompleteTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function cancelAfterNaturalCompletionIsNoOp(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-cancel-after-complete');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_Cancel_AfterComplete_Caller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(60)),
+        );
+
+        $client->start($stub, $endpoint->name, 'payload');
+
+        self::assertSame('completed:payload', $stub->getResult('string', timeout: 30));
+    }
+}
+
+// ── Nexus service: handler completes almost immediately ─────────────────
+
+#[Service(name: 'CancelAfterCompleteService')]
+class CancelAfterCompleteService
+{
+    #[AsyncOperation(output: 'string')]
+    public function quick(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            CancelAfterCompleteHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(Nexus::getStartDetails()->requestId),
+            $input,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class CancelAfterCompleteHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Cancel_AfterComplete_Handler')]
+    public function handle(string $input)
+    {
+        yield Workflow::timer(CarbonInterval::milliseconds(50));
+        return "completed:{$input}";
+    }
+}
+
+/**
+ * Awaits the operation result first, then issues a cancel on the (now resolved)
+ * scope. The cancel must be swallowed silently and the result preserved.
+ */
+#[WorkflowInterface]
+class CancelAfterCompleteCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Cancel_AfterComplete_Caller')]
+    public function run(string $endpoint, string $input)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            CancelAfterCompleteService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(30))
+                ->withCancellationType(NexusOperationCancellationType::WaitRequested),
+        );
+
+        $promise = null;
+        $scope = Workflow::async(static function () use ($stub, $input, &$promise): void {
+            $promise = $stub->quick($input);
+        });
+
+        try {
+            $result = yield $promise;
+        } catch (CanceledFailure) {
+            return 'unexpected-cancel-before-completion';
+        }
+
+        $scope->cancel();
+
+        yield Workflow::timer(CarbonInterval::milliseconds(50));
+
+        return $result;
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/Coexistence/CoexistenceTest.php b/tests/Acceptance/Extra/Nexus/Coexistence/CoexistenceTest.php
new file mode 100644
index 000000000..f6969f975
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/Coexistence/CoexistenceTest.php
@@ -0,0 +1,113 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\Coexistence;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Activity;
+use Temporal\Activity\ActivityInterface;
+use Temporal\Activity\ActivityMethod;
+use Temporal\Activity\ActivityOptions;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHttpClient;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Acceptance test: a worker can host workflows, activities AND Nexus services together.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class CoexistenceTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function workflowExecutesWithActivityAlongsideNexus(
+        #[Stub('Extra_Nexus_Coexistence_Wf')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $result = $stub->getResult('string');
+        self::assertSame('activity-result:hello', $result);
+    }
+
+    #[Test]
+    public function nexusOperationStillWorksAfterActivityRegistered(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Coexistence_Wf2')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'test-nexus-coexist');
+
+        [$code, $resp, ] = $http->post($endpoint, 'CoexistService', 'ping', 'pong');
+        self::assertSame(200, $code, "Expected 200, got {$code}. Response: {$resp}");
+        self::assertStringContainsString('pong-pong', $resp);
+    }
+}
+
+// ── Activity ─────────────────────────────────────────────────────
+
+#[ActivityInterface(prefix: 'Extra_Nexus_Coexistence_')]
+class CoexistenceActivity
+{
+    #[ActivityMethod]
+    public function process(string $input): string
+    {
+        return "activity-result:{$input}";
+    }
+}
+
+// ── Workflows ────────────────────────────────────────────────────
+
+#[WorkflowInterface]
+class CoexistenceWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Coexistence_Wf')]
+    public function run()
+    {
+        $activity = Workflow::newActivityStub(
+            CoexistenceActivity::class,
+            ActivityOptions::new()->withStartToCloseTimeout(10),
+        );
+        return yield $activity->process('hello');
+    }
+}
+
+#[WorkflowInterface]
+class CoexistenceBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Coexistence_Wf2')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+// ── Nexus service (coexists with workflow + activity) ─────────────
+
+#[Service(name: 'CoexistService')]
+class CoexistService
+{
+    #[Operation]
+    public function ping(string $word): string
+    {
+        return "pong-{$word}";
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/Errors/ErrorsTest.php b/tests/Acceptance/Extra/Nexus/Errors/ErrorsTest.php
new file mode 100644
index 000000000..16cdc015f
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/Errors/ErrorsTest.php
@@ -0,0 +1,334 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\Errors;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\OperationException;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoint;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHttpClient;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Acceptance test: Nexus error handling — OperationException and HandlerException.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class ErrorsTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function operationFailureReturns424FailedDependency(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Errors_Bootstrap')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $this->endpoint($endpoints, $state->namespace);
+
+        [$code, $resp, ] = $http->post($endpoint, 'ErrorService', 'failOp', 'business-error');
+
+        self::assertSame(424, $code, "OperationException must map to 424, got {$code}. Body: {$resp}");
+        self::assertStringContainsString('business-error', $resp, 'Failure message should be propagated');
+    }
+
+    #[Test]
+    public function handlerInternalErrorReturns500(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Errors_Bootstrap2')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $this->endpoint($endpoints, $state->namespace);
+
+        [$code, $resp, ] = $http->post($endpoint, 'ErrorService', 'handlerErrorOp', 'infra');
+
+        self::assertSame(500, $code, "Internal handler error must map to 500, got {$code}. Body: {$resp}");
+    }
+
+    #[Test]
+    public function handlerBadRequestReturns400(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Errors_Bootstrap3')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $this->endpoint($endpoints, $state->namespace);
+
+        [$code, $resp, ] = $http->post($endpoint, 'ErrorService', 'badRequestOp', 'bad-input');
+
+        self::assertSame(400, $code, "BadRequest handler error must map to 400, got {$code}. Body: {$resp}");
+    }
+
+    #[Test]
+    public function handlerUnauthorizedReturns403(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Errors_Bootstrap4')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $this->endpoint($endpoints, $state->namespace);
+
+        [$code, $resp, ] = $http->post($endpoint, 'ErrorService', 'unauthorizedOp', 'deny');
+
+        self::assertSame(403, $code, "Unauthorized handler error must map to 403, got {$code}. Body: {$resp}");
+    }
+
+    #[Test]
+    public function handlerNotFoundReturns404(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Errors_Bootstrap5')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $this->endpoint($endpoints, $state->namespace);
+
+        [$code, $resp, ] = $http->post($endpoint, 'ErrorService', 'notFoundOp', 'missing');
+
+        self::assertSame(404, $code, "Handler NotFound error must map to 404, got {$code}. Body: {$resp}");
+        self::assertStringContainsString(
+            'missing: missing',
+            $resp,
+            'Body must carry the handler\'s NotFound message — otherwise this 404 may be an endpoint-cache miss.',
+        );
+    }
+
+    #[Test]
+    public function unknownOperationReturns404(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Errors_Bootstrap6')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $this->endpoint($endpoints, $state->namespace);
+
+        // Prove the endpoint is routable first, so the 404 below cannot be an endpoint-cache miss.
+        [$probeCode, $probeResp, ] = $http->post($endpoint, 'ErrorService', 'echoOp', 'probe');
+        self::assertSame(200, $probeCode, "Routability probe failed: {$probeCode}. Body: {$probeResp}");
+
+        [$code, $resp, ] = $http->post($endpoint, 'ErrorService', 'nonExistentOp', 'whatever');
+
+        self::assertSame(404, $code, "Unknown op → NOT_FOUND → 404, got {$code}. Body: {$resp}");
+    }
+
+    #[Test]
+    public function operationCanceledFromHandlerPropagates(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Errors_Bootstrap7')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $this->endpoint($endpoints, $state->namespace);
+
+        [$code, $resp, ] = $http->post($endpoint, 'ErrorService', 'cancelOp', 'bye');
+
+        self::assertSame(424, $code, "Canceled → 424, got {$code}. Body: {$resp}");
+        self::assertStringContainsString('bye', $resp, 'Failure message should be propagated');
+    }
+
+    /**
+     * Verifies the failure cause/stack-trace forwarding (Fix 3).
+     */
+    #[Test]
+    public function handlerExceptionForwardsCauseChainInResponse(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Errors_Bootstrap8')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $this->endpoint($endpoints, $state->namespace);
+
+        [$code, $resp, ] = $http->post($endpoint, 'ErrorService', 'failWithCause', 'outer-fail');
+
+        self::assertSame(500, $code, "Body: {$resp}");
+        self::assertStringContainsString('outer-fail', $resp);
+        self::assertStringContainsString('CAUSE_CHAIN_MARKER', $resp);
+    }
+
+    private function endpoint(NexusEndpoints $endpoints, string $namespace): NexusEndpoint
+    {
+        return $endpoints->register($namespace, __NAMESPACE__, 'test-nexus-err');
+    }
+}
+
+#[Service(name: 'ErrorService')]
+class ErrorService
+{
+    #[Operation]
+    public function echoOp(string $input): string
+    {
+        return $input;
+    }
+
+    #[Operation]
+    public function failOp(string $reason): string
+    {
+        throw OperationException::failed($reason ?: 'unknown');
+    }
+
+    #[Operation]
+    public function handlerErrorOp(string $reason): string
+    {
+        throw HandlerException::create(ErrorType::Internal, "infra: {$reason}");
+    }
+
+    #[Operation]
+    public function badRequestOp(string $reason): string
+    {
+        throw HandlerException::create(ErrorType::BadRequest, "bad: {$reason}");
+    }
+
+    #[Operation]
+    public function unauthorizedOp(string $reason): string
+    {
+        throw HandlerException::create(ErrorType::Unauthorized, "deny: {$reason}");
+    }
+
+    #[Operation]
+    public function notFoundOp(string $reason): string
+    {
+        throw HandlerException::create(ErrorType::NotFound, "missing: {$reason}");
+    }
+
+    #[Operation]
+    public function cancelOp(string $reason): string
+    {
+        throw OperationException::canceled($reason ?: 'canceled');
+    }
+
+    #[Operation]
+    public function failWithCause(string $reason): string
+    {
+        // Two-level cause chain. The marker in the inner cause's
+        // message is what the acceptance test asserts to prove the
+        // chain reached the caller.
+        $inner = new \RuntimeException('CAUSE_CHAIN_MARKER: db unavailable');
+        $middle = new \LogicException("middle of {$reason}", 0, $inner);
+        throw HandlerException::create(
+            ErrorType::Internal,
+            $reason ?: 'unknown',
+            cause: $middle,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class ErrorsBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Errors_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class ErrorsBootstrapWorkflow2
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Errors_Bootstrap2')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class ErrorsBootstrapWorkflow3
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Errors_Bootstrap3')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class ErrorsBootstrapWorkflow4
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Errors_Bootstrap4')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class ErrorsBootstrapWorkflow5
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Errors_Bootstrap5')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class ErrorsBootstrapWorkflow6
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Errors_Bootstrap6')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class ErrorsBootstrapWorkflow7
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Errors_Bootstrap7')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class ErrorsBootstrapWorkflow8
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Errors_Bootstrap8')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/Headers/HeadersTest.php b/tests/Acceptance/Extra/Nexus/Headers/HeadersTest.php
new file mode 100644
index 000000000..c65e0dd15
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/Headers/HeadersTest.php
@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\Headers;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Nexus;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHttpClient;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Acceptance test: HTTP request headers are propagated to the Nexus handler.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class HeadersTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function customHeadersArePropagated(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Headers_Bootstrap')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'test-nexus-hdr');
+
+        [$code, $resp, ] = $http->post(
+            $endpoint,
+            'HeaderEchoService',
+            'echoHeader',
+            'X-Custom-Header',
+            ['X-Custom-Header' => 'my-test-value'],
+        );
+
+        self::assertSame(200, $code, "Expected 200, got {$code}. Response: {$resp}");
+        self::assertStringContainsString('my-test-value', $resp, 'Expected header value in response');
+    }
+}
+
+#[Service(name: 'HeaderEchoService')]
+class HeaderEchoService
+{
+    #[Operation]
+    public function echoHeader(string $headerName): string
+    {
+        // Headers in OperationContext are case-insensitive (lowercased)
+        $context = Nexus::getCurrentOperationContext();
+        return $context->headers->get($headerName) ?? "missing:{$headerName}";
+    }
+}
+
+#[WorkflowInterface]
+class HeadersBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Headers_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/Idempotency/RequestIdIdempotencyTest.php b/tests/Acceptance/Extra/Nexus/Idempotency/RequestIdIdempotencyTest.php
new file mode 100644
index 000000000..0c40c811f
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/Idempotency/RequestIdIdempotencyTest.php
@@ -0,0 +1,174 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\Idempotency;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHttpClient;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/** Two HTTP starts with the same Nexus-Request-Id must yield identical operation tokens. */
+#[Worker(options: [self::class, 'workerOptions'])]
+class RequestIdIdempotencyTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function sameNexusRequestIdYieldsSameOperationToken(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Idempotency_Bootstrap')]
+        WorkflowStubInterface $bootstrapStub,
+    ): void {
+        $bootstrapStub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-idempotent');
+
+        $sharedRequestId = 'idempotency-test-' . \bin2hex(\random_bytes(4));
+
+        $extraHeaders = [
+            'Nexus-Callback-Url' => 'http://callback.example.local/done',
+            'Nexus-Request-Id' => $sharedRequestId,
+        ];
+
+        [$code1, $body1, ] = $http->post(
+            $endpoint,
+            'IdempotentWorkflowService',
+            'longRun',
+            'payload-1',
+            $extraHeaders,
+        );
+        self::assertSame(201, $code1, "First async start expected 201, got {$code1}. Body: {$body1}");
+        $token1 = self::extractOperationToken($body1);
+
+        [$code2, $body2, ] = $http->post(
+            $endpoint,
+            'IdempotentWorkflowService',
+            'longRun',
+            'payload-2',
+            $extraHeaders,
+        );
+        self::assertSame(201, $code2, "Second async start expected 201, got {$code2}. Body: {$body2}");
+        $token2 = self::extractOperationToken($body2);
+
+        self::assertSame(
+            $token1,
+            $token2,
+            "Same Nexus-Request-Id must yield identical operation tokens. token1={$token1} token2={$token2}",
+        );
+    }
+
+    #[Test]
+    public function differentNexusRequestIdsYieldDifferentOperationTokens(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Idempotency_Bootstrap')]
+        WorkflowStubInterface $bootstrapStub,
+    ): void {
+        $bootstrapStub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-idempotent-distinct');
+
+        $requestIdA = 'idempotency-test-A-' . \bin2hex(\random_bytes(4));
+        $requestIdB = 'idempotency-test-B-' . \bin2hex(\random_bytes(4));
+
+        [$code1, $body1, ] = $http->post(
+            $endpoint,
+            'IdempotentWorkflowService',
+            'longRun',
+            'payload-1',
+            [
+                'Nexus-Callback-Url' => 'http://callback.example.local/done',
+                'Nexus-Request-Id' => $requestIdA,
+            ],
+        );
+        self::assertSame(201, $code1);
+        $tokenA = self::extractOperationToken($body1);
+
+        [$code2, $body2, ] = $http->post(
+            $endpoint,
+            'IdempotentWorkflowService',
+            'longRun',
+            'payload-1',
+            [
+                'Nexus-Callback-Url' => 'http://callback.example.local/done',
+                'Nexus-Request-Id' => $requestIdB,
+            ],
+        );
+        self::assertSame(201, $code2);
+        $tokenB = self::extractOperationToken($body2);
+
+        self::assertNotSame(
+            $tokenA,
+            $tokenB,
+            'Different Nexus-Request-Ids must yield distinct operation tokens (no accidental cross-request dedup).',
+        );
+    }
+
+    private static function extractOperationToken(string $responseBody): string
+    {
+        $decoded = \json_decode($responseBody, true);
+        self::assertIsArray($decoded, "Async start body must be JSON OperationInfo. Body: {$responseBody}");
+        $token = $decoded['token'] ?? $decoded['operationToken'] ?? null;
+        self::assertIsString($token, "Async start body must carry a token field. Body: {$responseBody}");
+        self::assertNotSame('', $token, 'Operation token must be non-empty.');
+        return $token;
+    }
+}
+
+#[Service(name: 'IdempotentWorkflowService')]
+class IdempotentWorkflowService
+{
+    #[AsyncOperation(output: 'string')]
+    public function longRun(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            IdempotentHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(Nexus::getStartDetails()->requestId),
+            $input,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class IdempotentHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Idempotency_Handler')]
+    public function handle(string $input)
+    {
+        yield Workflow::timer(CarbonInterval::seconds(3));
+        return 'done:' . $input;
+    }
+}
+
+#[WorkflowInterface]
+class IdempotencyBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Idempotency_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/InputTypes/InputTypesTest.php b/tests/Acceptance/Extra/Nexus/InputTypes/InputTypesTest.php
new file mode 100644
index 000000000..b24d64b7d
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/InputTypes/InputTypesTest.php
@@ -0,0 +1,168 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\InputTypes;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHttpClient;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Acceptance test: Nexus operations with varying input/output shapes
+ * (void, scalar, int, DTO). Validates that the reflection-based OperationDefinition
+ * correctly registers the types and the data converter round-trips each one.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class InputTypesTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function voidInputReturnsString(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_InputTypes_Bootstrap')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        [$code, $resp] = $this->invoke($state, $endpoints, $http, 'pingNoInput', null);
+        self::assertSame(200, $code, "Body: {$resp}");
+        self::assertStringContainsString('pong', $resp);
+    }
+
+    #[Test]
+    public function scalarIntRoundtrip(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_InputTypes_Bootstrap2')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        [$code, $resp] = $this->invoke($state, $endpoints, $http, 'doubleInt', 21);
+        self::assertSame(200, $code, "Body: {$resp}");
+        self::assertStringContainsString('42', $resp);
+    }
+
+    #[Test]
+    public function dtoInputDtoOutput(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_InputTypes_Bootstrap3')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        [$code, $resp] = $this->invoke($state, $endpoints, $http, 'echoDto', [
+            'name' => 'Ada',
+            'value' => 99,
+        ]);
+
+        self::assertSame(200, $code, "Body: {$resp}");
+        self::assertStringContainsString('Ada', $resp);
+        self::assertStringContainsString('99', $resp);
+    }
+
+    /**
+     * @return array{int, string}
+     */
+    private function invoke(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        string $operation,
+        mixed $input,
+    ): array {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-input-types');
+
+        [$code, $body, ] = $http->post($endpoint, 'ShapeService', $operation, $input);
+        return [$code, $body];
+    }
+}
+
+// ── DTOs ─────────────────────────────────────────────────────────────
+
+final class Item
+{
+    public function __construct(
+        public string $name = '',
+        public int $value = 0,
+    ) {}
+}
+
+// ── Nexus service ────────────────────────────────────────────────────
+
+#[Service(name: 'ShapeService')]
+class ShapeService
+{
+    /** Operation with no input parameter — handler receives `null`. */
+    #[Operation]
+    public function pingNoInput(): string
+    {
+        return 'pong';
+    }
+
+    #[Operation]
+    public function doubleInt(int $x): int
+    {
+        return $x * 2;
+    }
+
+    #[Operation]
+    public function echoDto(Item $item): Item
+    {
+        // Echo with a trivial transform to prove deserialization actually happened.
+        return new Item($item->name, $item->value);
+    }
+}
+
+// ── Bootstrap workflows ──────────────────────────────────────────────
+
+#[WorkflowInterface]
+class InputTypesBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_InputTypes_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class InputTypesBootstrapWorkflow2
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_InputTypes_Bootstrap2')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class InputTypesBootstrapWorkflow3
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_InputTypes_Bootstrap3')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/Interceptor/InterceptorTest.php b/tests/Acceptance/Extra/Nexus/Interceptor/InterceptorTest.php
new file mode 100644
index 000000000..9a9dbe471
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/Interceptor/InterceptorTest.php
@@ -0,0 +1,324 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\Interceptor;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Exception\Failure\CanceledFailure;
+use Temporal\Exception\Failure\NexusOperationFailure;
+use Temporal\Interceptor\NexusOperationInbound\CancelOperationInput;
+use Temporal\Interceptor\NexusOperationInbound\StartOperationInput;
+use Temporal\Interceptor\NexusOperationInboundCallsInterceptor;
+use Temporal\Interceptor\PipelineProvider;
+use Temporal\Interceptor\SimplePipelineProvider;
+use Temporal\Interceptor\Trait\NexusOperationInboundCallsInterceptorTrait;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHttpClient;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationCancellationType;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * {@see NexusOperationInboundCallsInterceptor} registered via {@see PipelineProvider};
+ * interceptors record markers in {@see WorkerLocalMarker} that handlers/tests read back.
+ */
+#[Worker(
+    pipelineProvider: [InterceptorTestServices::class, 'interceptors'],
+    options: [InterceptorTest::class, 'workerOptions'],
+)]
+class InterceptorTest extends TestCase
+{
+    public const AUTH_TOKEN = 'super-secret-token';
+
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function startInvokesInterceptorWithValidToken(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Interceptor_Bootstrap')] WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'test-nexus-interceptor');
+
+        [$code, $body, ] = $http->post(
+            $endpoint,
+            'GreetingService',
+            'sayHello',
+            'World',
+            [AuthInterceptor::AUTH_HEADER => self::AUTH_TOKEN],
+        );
+
+        self::assertSame(200, $code, "Expected 200, got {$code}. Response: {$body}");
+        // Greeting proves the pipeline reached the handler.
+        self::assertStringContainsString('Hello, World!', $body);
+        // Marker proves the LoggingInterceptor ran before the handler.
+        self::assertStringContainsString('seen-by-interceptor', $body);
+    }
+
+    #[Test]
+    public function startIsRejectedWithoutAuthToken(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Interceptor_Bootstrap')] WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'test-nexus-interceptor');
+
+        [$code, $body, ] = $http->post(
+            $endpoint,
+            'GreetingService',
+            'sayHello',
+            'World',
+        );
+
+        // Nexus maps `ErrorType::Unauthorized` to HTTP 403.
+        self::assertSame(403, $code, "Expected 403, got {$code}. Response: {$body}");
+        // Auth interceptor short-circuited the pipeline — no handler greeting in the body.
+        self::assertStringNotContainsString('Hello, World!', $body);
+    }
+
+    /** Caller cancels an async op mid-flight; the cancel-side interceptor must leave its marker. */
+    #[Test]
+    public function cancelInvokesInterceptorAndHandlerSeesMarker(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        WorkerLocalMarker::clearCancel();
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'test-nexus-interceptor-cancel');
+
+        // Deterministic handler workflow id — we want to fetch its result later.
+        $handlerWorkflowId = 'cancel-marker-handler-' . \bin2hex(\random_bytes(4));
+
+        $callerStub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_Interceptor_CancelCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(15)),
+        );
+
+        $client->start($callerStub, $endpoint->name, $handlerWorkflowId);
+        self::assertSame('cancelled', $callerStub->getResult('string'));
+
+        // Handler workflow caught CanceledFailure and returned 'cancelled:...'.
+        $handlerStub = $client->newUntypedRunningWorkflowStub($handlerWorkflowId);
+        $handlerResult = $handlerStub->getResult('string', timeout: 10);
+        self::assertStringStartsWith('cancelled:', $handlerResult);
+
+        // File-backed marker survives cross-process dispatch between RR workers.
+        $marker = WorkerLocalMarker::readCancel();
+        self::assertNotNull($marker, 'Cancel interceptor never wrote its marker.');
+        self::assertStringContainsString('cancel-seen-by-interceptor', $marker);
+        WorkerLocalMarker::clearCancel();
+    }
+}
+
+/**
+ * Markers shared between interceptors (writers) and downstream readers:
+ * $lastSeen is process-local (sync case); the cancel marker is file-backed (cross-process).
+ */
+final class WorkerLocalMarker
+{
+    public const CANCEL_MARKER_FILE = '/tmp/nexus-interceptor-cancel-marker-test-nexus-interceptor-cancel';
+
+    public static ?string $lastSeen = null;
+
+    public static function recordCancel(string $value): void
+    {
+        \file_put_contents(self::CANCEL_MARKER_FILE, $value);
+    }
+
+    public static function readCancel(): ?string
+    {
+        return \is_file(self::CANCEL_MARKER_FILE)
+            ? \file_get_contents(self::CANCEL_MARKER_FILE)
+            : null;
+    }
+
+    public static function clearCancel(): void
+    {
+        if (\is_file(self::CANCEL_MARKER_FILE)) {
+            \unlink(self::CANCEL_MARKER_FILE);
+        }
+    }
+}
+
+final class AuthInterceptor implements NexusOperationInboundCallsInterceptor
+{
+    public const AUTH_HEADER = 'authorization';
+
+    public function __construct(private readonly string $authToken) {}
+
+    public function startOperation(StartOperationInput $input, callable $next): OperationStartResult
+    {
+        // Auth is scoped to GreetingService; workflow-to-workflow stubs carry no auth header.
+        if ($input->operationContext->service === 'GreetingService') {
+            $this->assertAuthorized($input->operationContext->headers->get(self::AUTH_HEADER));
+        }
+        return $next($input);
+    }
+
+    public function cancelOperation(CancelOperationInput $input, callable $next): void
+    {
+        if ($input->operationContext->service === 'GreetingService') {
+            $this->assertAuthorized($input->operationContext->headers->get(self::AUTH_HEADER));
+        }
+        $next($input);
+    }
+
+    private function assertAuthorized(?string $token): void
+    {
+        if ($token !== $this->authToken) {
+            throw HandlerException::create(ErrorType::Unauthorized, 'Unauthorized');
+        }
+    }
+}
+
+final class LoggingInterceptor implements NexusOperationInboundCallsInterceptor
+{
+    use NexusOperationInboundCallsInterceptorTrait;
+
+    public function startOperation(StartOperationInput $input, callable $next): OperationStartResult
+    {
+        WorkerLocalMarker::$lastSeen = "seen-by-interceptor:{$input->operationContext->operation}";
+        return $next($input);
+    }
+
+    public function cancelOperation(CancelOperationInput $input, callable $next): void
+    {
+        WorkerLocalMarker::recordCancel("cancel-seen-by-interceptor:{$input->operationContext->operation}");
+        $next($input);
+    }
+}
+
+class InterceptorTestServices
+{
+    public static function interceptors(): PipelineProvider
+    {
+        return new SimplePipelineProvider([
+            new AuthInterceptor(InterceptorTest::AUTH_TOKEN),
+            new LoggingInterceptor(),
+        ]);
+    }
+}
+
+// ── Sync greeting service (used by the first two tests) ────────────────
+
+#[Service(name: 'GreetingService')]
+class GreetingService
+{
+    #[Operation]
+    public function sayHello(string $name): string
+    {
+        $marker = WorkerLocalMarker::$lastSeen ?? 'no-marker';
+        return "Hello, {$name}! [{$marker}]";
+    }
+}
+
+// ── Async cancel service (used by the cancel-marker test) ──────────────
+
+#[Service(name: 'InterceptorCancelService')]
+class InterceptorCancelService
+{
+    #[AsyncOperation(output: 'string')]
+    public function longRunning(string $handlerWorkflowId): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            CancelHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId($handlerWorkflowId),
+            $handlerWorkflowId,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class CancelHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Interceptor_CancelHandler')]
+    public function handle(string $input)
+    {
+        try {
+            // Long enough that the caller can request cancel before we finish.
+            yield Workflow::timer(CarbonInterval::seconds(30));
+            return "completed:{$input}";
+        } catch (CanceledFailure) {
+            // Marker isn't read here: handler may run in a different RR worker process.
+            return "cancelled:{$input}";
+        }
+    }
+}
+
+#[WorkflowInterface]
+class CancelCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Interceptor_CancelCaller')]
+    public function run(string $endpoint, string $handlerWorkflowId)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            InterceptorCancelService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(60))
+                ->withCancellationType(NexusOperationCancellationType::WaitRequested),
+        );
+
+        $promise = null;
+        $scope = Workflow::async(static function () use ($stub, $handlerWorkflowId, &$promise): void {
+            $promise = $stub->longRunning($handlerWorkflowId);
+        });
+
+        // Give the handler workflow a chance to actually start before cancelling.
+        yield Workflow::timer(CarbonInterval::seconds(NexusWorkerOptions::PRE_CANCEL_TIMER_SECONDS));
+        $scope->cancel();
+
+        try {
+            yield $promise;
+        } catch (NexusOperationFailure $e) {
+            if ($e->getPrevious() instanceof CanceledFailure) {
+                return 'cancelled';
+            }
+            throw $e;
+        }
+
+        return 'unexpected-completion';
+    }
+}
+
+#[WorkflowInterface]
+class InterceptorBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Interceptor_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/Links/LinksTest.php b/tests/Acceptance/Extra/Nexus/Links/LinksTest.php
new file mode 100644
index 000000000..7d1f77226
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/Links/LinksTest.php
@@ -0,0 +1,279 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\Links;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Link;
+use Temporal\Nexus\Nexus;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHttpClient;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Acceptance test: Links attached to OperationContext by the handler are
+ * propagated back to the Nexus caller in the response.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class LinksTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function handlerCanAttachSingleLinkAndSeeItBack(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Links_Bootstrap')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        [$code, $resp] = $this->invoke($state, $endpoints, $http, 'attachAndReportSingle', 'session-7');
+
+        self::assertSame(200, $code, "Expected 200, got {$code}. Body: {$resp}");
+        self::assertStringContainsString('count=1', $resp);
+        self::assertStringContainsString('session-7', $resp);
+        self::assertStringContainsString('example.session', $resp);
+    }
+
+    #[Test]
+    public function handlerCanAttachMultipleLinksAndSeeThemBack(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Links_Bootstrap2')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        [$code, $resp] = $this->invoke($state, $endpoints, $http, 'attachAndReportMany', 'job-99');
+
+        self::assertSame(200, $code, "Expected 200, got {$code}. Body: {$resp}");
+        self::assertStringContainsString('count=2', $resp);
+        self::assertStringContainsString('primary-job-99', $resp);
+        self::assertStringContainsString('audit-job-99', $resp);
+    }
+
+    #[Test]
+    public function handlerStartsWithNoLinks(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Links_Bootstrap3')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        [$code, $resp] = $this->invoke($state, $endpoints, $http, 'reportNoLinks', 'x');
+
+        self::assertSame(200, $code, "Body: {$resp}");
+        self::assertStringContainsString('count=0', $resp);
+    }
+
+    /**
+     * End-to-end verification of the handler-response-Link wire:
+     * handler calls $context->links->add(), sdk-php packs them into
+     * `_rr_nexus_links` payload metadata, RoadRunner extracts them and
+     * calls nexus.AddHandlerLinks which puts them into the handler ctx;
+     * Temporal Go SDK reads them via nexus.HandlerLinks(ctx) and emits
+     * `Nexus-Link` response headers back to the caller.
+     */
+    #[Test]
+    public function handlerLinksAppearInNexusLinkResponseHeader(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Links_Bootstrap4')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-links-hdr');
+
+        [$code, $body, $headers] = $http->post(
+            $endpoint,
+            'LinkService',
+            'attachAndReportMany',
+            'order-42',
+        );
+
+        self::assertSame(200, $code, "Body: {$body}");
+        self::assertArrayHasKey('nexus-link', $headers, \sprintf(
+            'Nexus-Link response header missing; got: [%s]',
+            \implode(', ', \array_keys($headers)),
+        ));
+
+        // RFC 5988 Link headers — value format `<url>; type="T"`. The two
+        // links set by attachAndReportMany must both be present (some
+        // clients concatenate with comma, some emit separate values).
+        $linkValues = \implode("\n", (array) $headers['nexus-link']);
+        self::assertStringContainsString('primary-order-42', $linkValues);
+        self::assertStringContainsString('audit-order-42', $linkValues);
+        self::assertStringContainsString('example.primary', $linkValues);
+        self::assertStringContainsString('example.audit', $linkValues);
+    }
+
+    /**
+     * Strict parsing (LinkParser): a caller-supplied `Nexus-Link` with a
+     * missing required field must be rejected with HTTP 400, matching the
+     * Java reference SDK. Previously the sdk-php route silently dropped
+     * malformed entries.
+     */
+    #[Test]
+    public function malformedCallerNexusLinkReturns400(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_Links_Bootstrap5')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-links-bad');
+
+        // A Link header value without the mandatory `type` parameter.
+        // RoadRunner parses the raw `Nexus-Link` header, builds options.links,
+        // sdk-php's LinkParser then rejects with HandlerException(BadRequest).
+        [$code, $body, ] = $http->post(
+            $endpoint,
+            'LinkService',
+            'reportNoLinks',
+            'x',
+            ['Nexus-Link' => '<https://caller.test/orphan>'],
+        );
+
+        self::assertSame(400, $code, "Expected 400 BadRequest, got {$code}. Body: {$body}");
+    }
+
+    /**
+     * @return array{int, string}
+     */
+    private function invoke(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        string $op,
+        string $body,
+    ): array {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-links');
+
+        [$code, $resp, ] = $http->post($endpoint, 'LinkService', $op, $body);
+        return [$code, $resp];
+    }
+}
+
+// ── Nexus service ────────────────────────────────────────────────────
+
+#[Service(name: 'LinkService')]
+class LinkService
+{
+    #[Operation]
+    public function attachAndReportSingle(string $suffix): string
+    {
+        $context = Nexus::getCurrentOperationContext();
+        $context->links->add(new Link(
+            "https://example.test/session/{$suffix}",
+            'example.session',
+        ));
+        return self::reportLinks($context);
+    }
+
+    #[Operation]
+    public function attachAndReportMany(string $suffix): string
+    {
+        $context = Nexus::getCurrentOperationContext();
+        $context->links->add(
+            new Link("https://example.test/primary/primary-{$suffix}", 'example.primary'),
+            new Link("https://example.test/audit/audit-{$suffix}", 'example.audit'),
+        );
+        return self::reportLinks($context);
+    }
+
+    #[Operation]
+    public function reportNoLinks(string $_ignored): string
+    {
+        return self::reportLinks(Nexus::getCurrentOperationContext());
+    }
+
+    /**
+     * Serializes the links currently attached to the given OperationContext into
+     * a compact string the test can assert on.
+     */
+    private static function reportLinks(OperationContext $context): string
+    {
+        $links = $context->links->all();
+        $parts = [];
+        foreach ($links as $link) {
+            $parts[] = "{$link->uri}|{$link->type}";
+        }
+        return \sprintf('count=%d;links=[%s]', \count($links), \implode(';', $parts));
+    }
+}
+
+// ── Bootstrap workflows ──────────────────────────────────────────────
+
+#[WorkflowInterface]
+class LinksBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Links_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class LinksBootstrapWorkflow2
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Links_Bootstrap2')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class LinksBootstrapWorkflow3
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Links_Bootstrap3')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class LinksBootstrapWorkflow4
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Links_Bootstrap4')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
+
+#[WorkflowInterface]
+class LinksBootstrapWorkflow5
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Links_Bootstrap5')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/ManualToken/ManualTokenTest.php b/tests/Acceptance/Extra/Nexus/ManualToken/ManualTokenTest.php
new file mode 100644
index 000000000..b7eb75006
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/ManualToken/ManualTokenTest.php
@@ -0,0 +1,249 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\ManualToken;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHistoryAssertions;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationCancellationType;
+use Temporal\Workflow\NexusOperationHandle;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\SignalMethod;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Manual-token async operations: the factory method returns an
+ * {@see OperationHandlerInterface} implementation owning start and cancel;
+ * cancel routes to the handler's cancel() or fails with NOT_IMPLEMENTED
+ * when the handler refuses cancellation.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class ManualTokenTest extends TestCase
+{
+    use NexusHistoryAssertions;
+
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function manualTokenReachesCallerUntouched(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-manual-token');
+
+        $caller = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_ManualToken_TokenCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(30)),
+        );
+
+        $client->start($caller, $endpoint->name, 'job-1');
+
+        self::assertSame('external-job-1', $caller->getResult('string', timeout: 30));
+    }
+
+    #[Test]
+    public function cancelRoutesToOperationCancelRoutine(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-manual-cancel-ok');
+
+        $caller = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_ManualToken_CancelCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(30)),
+        );
+
+        $client->start($caller, $endpoint->name, 'startCancellable', 'job-2');
+
+        self::assertTrue(
+            self::historyContains($client, $caller, EventType::EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED),
+            'Expected NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED in caller history. Seen events: '
+            . \implode(', ', self::historyEventNames($client, $caller)),
+        );
+
+        $caller->signal('finish');
+        self::assertSame('done', $caller->getResult('string', timeout: 40));
+    }
+
+    #[Test]
+    public function cancelWithoutRoutineFailsWithNotImplemented(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-manual-cancel-ni');
+
+        $caller = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_ManualToken_CancelCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(30)),
+        );
+
+        $client->start($caller, $endpoint->name, 'startUncancellable', 'job-3');
+
+        self::assertTrue(
+            self::historyContains($client, $caller, EventType::EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED),
+            'Expected NEXUS_OPERATION_CANCEL_REQUEST_FAILED in caller history. Seen events: '
+            . \implode(', ', self::historyEventNames($client, $caller)),
+        );
+
+        $caller->signal('finish');
+        self::assertSame('done', $caller->getResult('string', timeout: 40));
+    }
+}
+
+// ── Nexus service: manual tokens, no backing workflow ───────────────────
+
+#[Service(name: 'ManualTokenAcceptanceService')]
+class ManualTokenAcceptanceService
+{
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function startCancellable(): CancellableExternalHandler
+    {
+        return new CancellableExternalHandler();
+    }
+
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function startUncancellable(): UncancellableExternalHandler
+    {
+        return new UncancellableExternalHandler();
+    }
+}
+
+final class CancellableExternalHandler implements OperationHandlerInterface
+{
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        return OperationStartResult::async(new OperationInfo("external-{$param}", OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {}
+}
+
+final class UncancellableExternalHandler implements OperationHandlerInterface
+{
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        return OperationStartResult::async(new OperationInfo("external-{$param}", OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {
+        throw HandlerException::create(ErrorType::NotImplemented, 'manual operation does not support cancellation');
+    }
+}
+
+// ── Caller: starts the op, returns the operation token, abandons the op ──
+
+#[WorkflowInterface]
+class TokenCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_ManualToken_TokenCaller')]
+    public function run(string $endpoint, string $input)
+    {
+        $stub = Workflow::newUntypedNexusOperationStub(
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withService('ManualTokenAcceptanceService')
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(20))
+                ->withCancellationType(NexusOperationCancellationType::Abandon),
+        );
+
+        /** @var NexusOperationHandle<string> $handle */
+        $handle = yield $stub->start('startCancellable', [$input], 'string');
+
+        return $handle->getOperationToken();
+    }
+}
+
+// ── Caller: starts the named op, cancels it, then waits for the `finish` signal ──
+
+#[WorkflowInterface]
+class CancelCallerWorkflow
+{
+    private bool $finished = false;
+
+    #[WorkflowMethod(name: 'Extra_Nexus_ManualToken_CancelCaller')]
+    public function run(string $endpoint, string $operation, string $input)
+    {
+        $stub = Workflow::newUntypedNexusOperationStub(
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withService('ManualTokenAcceptanceService')
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(20))
+                ->withCancellationType(NexusOperationCancellationType::TryCancel),
+        );
+
+        $handle = null;
+        $scope = Workflow::async(static function () use ($stub, $operation, $input, &$handle) {
+            $handle = yield $stub->start($operation, [$input], 'string');
+            yield $handle->getResult();
+        });
+
+        yield Workflow::await(static function () use (&$handle): bool {
+            return $handle !== null;
+        });
+        yield Workflow::timer(CarbonInterval::seconds(NexusWorkerOptions::PRE_CANCEL_TIMER_SECONDS));
+        $scope->cancel();
+
+        try {
+            yield $scope;
+        } catch (\Throwable) {
+        }
+
+        yield Workflow::await(fn(): bool => $this->finished);
+
+        return 'done';
+    }
+
+    #[SignalMethod]
+    public function finish(): void
+    {
+        $this->finished = true;
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/MultiOperation/MultiOperationTest.php b/tests/Acceptance/Extra/Nexus/MultiOperation/MultiOperationTest.php
new file mode 100644
index 000000000..afeef3518
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/MultiOperation/MultiOperationTest.php
@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\MultiOperation;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHttpClient;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Acceptance test: a single Nexus service with multiple operations.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class MultiOperationTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function multipleOperationsAreInvokable(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_MultiOp_Bootstrap')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__);
+
+        $cases = [
+            ['add', [3, 5], '8'],
+            ['multiply', [4, 7], '28'],
+            ['echo', ['hello'], '"hello"'],
+            ['constant', [null], '42'],
+        ];
+
+        foreach ($cases as [$op, $body, $expectedFragment]) {
+            $payload = \count($body) === 1 ? $body[0] : $body;
+            [$code, $resp, ] = $http->post($endpoint, 'MathService', $op, $payload);
+            self::assertSame(200, $code, "Operation {$op}: expected 200, got {$code}. Response: {$resp}");
+            self::assertStringContainsString($expectedFragment, $resp, "Operation {$op}: missing expected fragment");
+        }
+    }
+}
+
+#[Service(name: 'MathService')]
+class MathService
+{
+    #[Operation]
+    public function add(array $args): int
+    {
+        return (int) ($args[0] ?? 0) + (int) ($args[1] ?? 0);
+    }
+
+    #[Operation]
+    public function multiply(array $args): int
+    {
+        return (int) ($args[0] ?? 1) * (int) ($args[1] ?? 1);
+    }
+
+    #[Operation]
+    public function echo(string $value): string
+    {
+        return $value;
+    }
+
+    #[Operation]
+    public function constant(): int
+    {
+        return 42;
+    }
+}
+
+#[WorkflowInterface]
+class MultiOpBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_MultiOp_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/MultiService/MultiServiceTest.php b/tests/Acceptance/Extra/Nexus/MultiService/MultiServiceTest.php
new file mode 100644
index 000000000..e5a11e7c3
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/MultiService/MultiServiceTest.php
@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\MultiService;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHttpClient;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Acceptance test: a single worker hosts multiple Nexus services.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class MultiServiceTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function bothServicesAreInvokable(
+        State $state,
+        NexusEndpoints $endpoints,
+        NexusHttpClient $http,
+        #[Stub('Extra_Nexus_MultiService_Bootstrap')]
+        WorkflowStubInterface $stub,
+    ): void {
+        $stub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'test-nexus-multi');
+
+        [$codeA, $respA, ] = $http->post($endpoint, 'ServiceA', 'opA', 'foo');
+        self::assertSame(200, $codeA, "ServiceA: expected 200, got {$codeA}. Response: {$respA}");
+        self::assertStringContainsString('A:foo', $respA);
+
+        [$codeB, $respB, ] = $http->post($endpoint, 'ServiceB', 'opB', 'bar');
+        self::assertSame(200, $codeB, "ServiceB: expected 200, got {$codeB}. Response: {$respB}");
+        self::assertStringContainsString('B:bar', $respB);
+    }
+}
+
+#[Service(name: 'ServiceA')]
+class ServiceA
+{
+    #[Operation]
+    public function opA(string $input): string
+    {
+        return "A:{$input}";
+    }
+}
+
+#[Service(name: 'ServiceB')]
+class ServiceB
+{
+    #[Operation]
+    public function opB(string $input): string
+    {
+        return "B:{$input}";
+    }
+}
+
+#[WorkflowInterface]
+class MultiServiceBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_MultiService_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/MultipleCallers/MultipleCallersTest.php b/tests/Acceptance/Extra/Nexus/MultipleCallers/MultipleCallersTest.php
new file mode 100644
index 000000000..b82eeeded
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/MultipleCallers/MultipleCallersTest.php
@@ -0,0 +1,135 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\MultipleCallers;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Common\WorkflowIdConflictPolicy;
+use Temporal\Exception\Client\WorkflowNotFoundException;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\SignalMethod;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+#[Worker(options: [self::class, 'workerOptions'])]
+class MultipleCallersTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function twoCallersShareOneAsyncHandlerWorkflow(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-shared-async');
+
+        $handlerWorkflowId = 'shared-handler-' . \bin2hex(\random_bytes(8));
+
+        $callerA = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_MultipleCallers_Caller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(20)),
+        );
+
+        $callerB = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_MultipleCallers_Caller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(20)),
+        );
+
+        $client->start($callerA, $endpoint->name, $handlerWorkflowId);
+        $client->start($callerB, $endpoint->name, $handlerWorkflowId);
+
+        $handlerStub = $client->newUntypedRunningWorkflowStub($handlerWorkflowId);
+        $signaled = false;
+        $deadline = \microtime(true) + 5.0;
+        do {
+            try {
+                $handlerStub->signal('unblock');
+                $signaled = true;
+                break;
+            } catch (WorkflowNotFoundException) {
+                \usleep(50_000);
+            }
+        } while (\microtime(true) < $deadline);
+
+        if (!$signaled) {
+            self::fail('handler never became signalable within 5s');
+        }
+
+        self::assertSame('shared-handler-result', $callerA->getResult('string'));
+        self::assertSame('shared-handler-result', $callerB->getResult('string'));
+    }
+}
+
+#[Service(name: 'SharedAsyncService')]
+class SharedAsyncService
+{
+    #[AsyncOperation(output: 'string')]
+    public function run(string $handlerWorkflowId): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            SharedHandlerWorkflow::class,
+            WorkflowOptions::new()
+                ->withWorkflowId($handlerWorkflowId)
+                ->withWorkflowIdConflictPolicy(WorkflowIdConflictPolicy::UseExisting),
+            $handlerWorkflowId,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class SharedHandlerWorkflow
+{
+    private bool $unblocked = false;
+
+    #[WorkflowMethod(name: 'Extra_Nexus_MultipleCallers_SharedHandler')]
+    public function handle(string $input)
+    {
+        yield Workflow::await(fn() => $this->unblocked);
+        return 'shared-handler-result';
+    }
+
+    #[SignalMethod(name: 'unblock')]
+    public function unblock(): void
+    {
+        $this->unblocked = true;
+    }
+}
+
+#[WorkflowInterface]
+class MultipleCallersCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_MultipleCallers_Caller')]
+    public function run(string $endpoint, string $handlerWorkflowId)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            SharedAsyncService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(15)),
+        );
+
+        return yield $stub->run($handlerWorkflowId);
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/NexusEndpoint.php b/tests/Acceptance/Extra/Nexus/NexusEndpoint.php
new file mode 100644
index 000000000..8659c8820
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/NexusEndpoint.php
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus;
+
+final readonly class NexusEndpoint
+{
+    public function __construct(
+        public string $id,
+        public string $name,
+    ) {}
+}
diff --git a/tests/Acceptance/Extra/Nexus/NexusEndpoints.php b/tests/Acceptance/Extra/Nexus/NexusEndpoints.php
new file mode 100644
index 000000000..13869e0ec
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/NexusEndpoints.php
@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus;
+
+use Temporal\Api\Nexus\V1\EndpointSpec;
+use Temporal\Api\Nexus\V1\EndpointTarget;
+use Temporal\Api\Nexus\V1\EndpointTarget\Worker as WorkerTarget;
+use Temporal\Api\Operatorservice\V1\CreateNexusEndpointRequest;
+use Temporal\Api\Operatorservice\V1\OperatorServiceClient;
+
+final class NexusEndpoints
+{
+    public function __construct(
+        private readonly OperatorServiceClient $operator,
+    ) {}
+
+    public function register(
+        string $namespace,
+        string $taskQueue,
+        string $prefix = 'test-nexus',
+    ): NexusEndpoint {
+        $name = $prefix . '-' . \bin2hex(\random_bytes(4));
+
+        $request = (new CreateNexusEndpointRequest())
+            ->setSpec(
+                (new EndpointSpec())
+                    ->setName($name)
+                    ->setTarget(
+                        (new EndpointTarget())->setWorker(
+                            (new WorkerTarget())
+                                ->setNamespace($namespace)
+                                ->setTaskQueue($taskQueue),
+                        ),
+                    ),
+            );
+
+        [$response, $status] = $this->operator->CreateNexusEndpoint($request)->wait();
+
+        if ($status->code !== \Grpc\STATUS_OK) {
+            throw new \RuntimeException(
+                "CreateNexusEndpoint failed (gRPC code {$status->code}): {$status->details}",
+            );
+        }
+
+        return new NexusEndpoint(id: $response->getEndpoint()->getId(), name: $name);
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/NexusHistoryAssertions.php b/tests/Acceptance/Extra/Nexus/NexusHistoryAssertions.php
new file mode 100644
index 000000000..5e73dc9b1
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/NexusHistoryAssertions.php
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus;
+
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Api\History\V1\History;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowStubInterface;
+
+trait NexusHistoryAssertions
+{
+    protected static function countEvents(History $history, int $type): int
+    {
+        $count = 0;
+        foreach ($history->getEvents() as $event) {
+            if ($event->getEventType() === $type) {
+                $count++;
+            }
+        }
+        return $count;
+    }
+
+    /**
+     * @param list<int> $expectedTypes
+     */
+    protected static function assertContainsEvents(History $history, array $expectedTypes, string $message): void
+    {
+        $present = [];
+        foreach ($history->getEvents() as $event) {
+            $present[$event->getEventType()] = true;
+        }
+        foreach ($expectedTypes as $type) {
+            self::assertArrayHasKey(
+                $type,
+                $present,
+                $message . ' — missing event type ' . EventType::name($type),
+            );
+        }
+    }
+
+    protected static function historyContains(
+        WorkflowClientInterface $client,
+        WorkflowStubInterface $stub,
+        int $eventType,
+        float $timeout = 15.0,
+    ): bool {
+        $deadline = \microtime(true) + $timeout;
+        do {
+            foreach ($client->getWorkflowHistory($stub->getExecution()) as $event) {
+                if ($event->getEventType() === $eventType) {
+                    return true;
+                }
+            }
+            \usleep(500_000);
+        } while (\microtime(true) < $deadline);
+
+        return false;
+    }
+
+    /**
+     * @return list<string>
+     */
+    protected static function historyEventNames(
+        WorkflowClientInterface $client,
+        WorkflowStubInterface $stub,
+    ): array {
+        $names = [];
+        foreach ($client->getWorkflowHistory($stub->getExecution()) as $event) {
+            $names[] = EventType::name($event->getEventType());
+        }
+        return $names;
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/NexusHttpClient.php b/tests/Acceptance/Extra/Nexus/NexusHttpClient.php
new file mode 100644
index 000000000..3451e9b43
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/NexusHttpClient.php
@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus;
+
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+final class NexusHttpClient
+{
+    public function __construct(
+        private readonly HttpClientInterface $http,
+    ) {}
+
+    /**
+     * POST a Nexus operation. Returns [http_code, body, headers-lowercased-keys].
+     *
+     * The Temporal frontend's HTTP endpoint cache is lazy: a freshly-created
+     * endpoint can return 404 for a few ms after CreateNexusEndpoint succeeds.
+     * Mirrors Go SDK's nexus_test helper (10 attempts × 100ms).
+     *
+     * @param mixed $body
+     * @param array<string, string> $headers
+     * @return array{int, string, array<string, list<string>>}
+     */
+    public function post(
+        NexusEndpoint $endpoint,
+        string $service,
+        string $operation,
+        mixed $body,
+        array $headers = [],
+    ): array {
+        $attempts = 10;
+        for ($attempt = 1; $attempt <= $attempts; $attempt++) {
+            $response = $this->http->request(
+                'POST',
+                "/nexus/endpoints/{$endpoint->id}/services/{$service}/{$operation}",
+                [
+                    'headers' => $headers,
+                    'json' => $body,
+                    'max_duration' => 30,
+                ],
+            );
+            $code = $response->getStatusCode();
+            if ($code !== 404 || $attempt === $attempts) {
+                return [$code, $response->getContent(false), $response->getHeaders(false)];
+            }
+            \usleep(100_000);
+        }
+        throw new \LogicException('Unreachable');
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/NexusWorkerOptions.php b/tests/Acceptance/Extra/Nexus/NexusWorkerOptions.php
new file mode 100644
index 000000000..2a2ae0831
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/NexusWorkerOptions.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus;
+
+use Temporal\Worker\WorkerOptions;
+
+final class NexusWorkerOptions
+{
+    public const PRE_CANCEL_TIMER_SECONDS = 1;
+
+    public static function default(): WorkerOptions
+    {
+        return WorkerOptions::new()
+            ->withMaxConcurrentActivityExecutionSize(10)
+            ->withMaxConcurrentNexusTaskExecutionSize(10)
+            ->withMaxConcurrentNexusTaskPollers(2);
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/Parallel/ParallelTest.php b/tests/Acceptance/Extra/Nexus/Parallel/ParallelTest.php
new file mode 100644
index 000000000..5b48c6e3d
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/Parallel/ParallelTest.php
@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\Parallel;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Promise;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * P4 #17 — workflow fans out N Nexus sync operations via {@see Promise::all()}
+ * and waits for all of them to complete.
+ *
+ * Distinct from {@see \Temporal\Tests\Acceptance\Extra\Nexus\MultiOperation\MultiOperationTest}
+ * which exercises multiple operations *sequentially over HTTP*. Here all the
+ * operations are scheduled concurrently and awaited together — same code path
+ * Java's `ParallelWorkflowOperationTest` covers.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class ParallelTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function workflowAwaitsMultipleParallelNexusOperations(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-parallel');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_Parallel_Caller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(20)),
+        );
+
+        $client->start($stub, $endpoint->name);
+
+        // double(1..5) → 2+4+6+8+10 = 30.
+        self::assertSame('sum=30', $stub->getResult('string'));
+    }
+}
+
+#[Service(name: 'ParallelService')]
+class ParallelService
+{
+    #[Operation]
+    public function double(int $input): int
+    {
+        return $input * 2;
+    }
+}
+
+#[WorkflowInterface]
+class ParallelCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Parallel_Caller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            ParallelService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(15)),
+        );
+
+        $promises = [];
+        for ($i = 1; $i <= 5; $i++) {
+            $promises[] = $stub->double($i);
+        }
+
+        $results = yield Promise::all($promises);
+
+        return 'sum=' . \array_sum($results);
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/ParallelCancel/CancelPropagationTest.php b/tests/Acceptance/Extra/Nexus/ParallelCancel/CancelPropagationTest.php
new file mode 100644
index 000000000..ec370ae69
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/ParallelCancel/CancelPropagationTest.php
@@ -0,0 +1,186 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\ParallelCancel;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Exception\Failure\CanceledFailure;
+use Temporal\Exception\Failure\NexusOperationFailure;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Promise;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHistoryAssertions;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationCancellationType;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Scope cancel over Promise::all of N async Nexus ops fans out per-sibling.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class CancelPropagationTest extends TestCase
+{
+    use NexusHistoryAssertions;
+
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function cancellingScopeWithPromiseAllCancelsAllSiblings(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+        #[Stub('Extra_Nexus_ParallelCancel_Bootstrap')]
+        WorkflowStubInterface $bootstrapStub,
+    ): void {
+        $bootstrapStub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-cancel-prop');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_ParallelCancel_Caller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(60)),
+        );
+
+        $client->start($stub, $endpoint->name);
+
+        self::assertSame('cancelled', $stub->getResult('string'));
+
+        $history = $client->getWorkflowHistory($stub->getExecution())->getHistory();
+        $scheduled = self::countEvents($history, EventType::EVENT_TYPE_NEXUS_OPERATION_SCHEDULED);
+        $cancelRequested = self::countEvents($history, EventType::EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUESTED);
+
+        self::assertSame(
+            3,
+            $scheduled,
+            'All three siblings must reach the schedule event before cancel.',
+        );
+        self::assertSame(
+            3,
+            $cancelRequested,
+            'Cancel must fan out to every sibling — proves Scope::onRequest registers per-promise onCancel.',
+        );
+
+        $canceled = self::countEvents($history, EventType::EVENT_TYPE_NEXUS_OPERATION_CANCELED);
+        self::assertSame(
+            3,
+            $canceled,
+            'Every sibling must reach the terminal CANCELED event — the handler re-raises the '
+            . 'CanceledFailure so the operation closes as CANCELED rather than COMPLETED.',
+        );
+
+        $completed = self::countEvents($history, EventType::EVENT_TYPE_NEXUS_OPERATION_COMPLETED);
+        self::assertSame(
+            0,
+            $completed,
+            'No sibling may close as COMPLETED once cancellation propagated.',
+        );
+    }
+}
+
+#[Service(name: 'CancelPropagationService')]
+class CancelPropagationService
+{
+    #[AsyncOperation(output: 'string')]
+    public function longRunning(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            CancelPropagationHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(Nexus::getStartDetails()->requestId),
+            $input,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class CancelPropagationHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_ParallelCancel_Handler')]
+    public function handle(string $input)
+    {
+        yield Workflow::timer(CarbonInterval::seconds(45));
+        return "completed:{$input}";
+    }
+}
+
+#[WorkflowInterface]
+class CancelPropagationCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_ParallelCancel_Caller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            CancelPropagationService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(60))
+                ->withCancellationType(NexusOperationCancellationType::WaitCompleted),
+        );
+
+        $promises = [];
+        $combined = null;
+        $scope = Workflow::async(static function () use ($stub, &$combined, &$promises): void {
+            $promises = [
+                $stub->longRunning('a'),
+                $stub->longRunning('b'),
+                $stub->longRunning('c'),
+            ];
+            $combined = Promise::all($promises);
+        });
+
+        yield Workflow::timer(CarbonInterval::seconds(NexusWorkerOptions::PRE_CANCEL_TIMER_SECONDS));
+        $scope->cancel();
+
+        $outcome = 'unexpected-no-failure';
+        try {
+            yield $combined;
+        } catch (NexusOperationFailure $e) {
+            $outcome = $e->getPrevious() instanceof CanceledFailure
+                ? 'cancelled'
+                : 'unexpected-cause:' . ($e->getPrevious()?->getMessage() ?? 'null');
+        } catch (CanceledFailure) {
+            $outcome = 'cancelled';
+        }
+
+        // Drain every sibling so all terminal events land before the caller closes.
+        foreach ($promises as $promise) {
+            try {
+                yield $promise;
+            } catch (\Throwable) {
+            }
+        }
+
+        return $outcome;
+    }
+}
+
+#[WorkflowInterface]
+class ParallelCancelBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_ParallelCancel_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/ParallelFailure/PartialFailureTest.php b/tests/Acceptance/Extra/Nexus/ParallelFailure/PartialFailureTest.php
new file mode 100644
index 000000000..c53c6242f
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/ParallelFailure/PartialFailureTest.php
@@ -0,0 +1,144 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\ParallelFailure;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Exception\Client\WorkflowFailedException;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Exception\OperationException;
+use Temporal\Promise;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHistoryAssertions;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Promise::all where one of N Nexus ops fails. Product gap: the sibling's failure
+ * surfaces as TimeoutFailure(SCHEDULE_TO_CLOSE) instead of ApplicationFailure, so the
+ * happy path here IS the timeout — hence the short scheduleToClose in the caller.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class PartialFailureTest extends TestCase
+{
+    use NexusHistoryAssertions;
+
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function failingSiblingPropagatesAndSchedulesAllOps(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+        #[Stub('Extra_Nexus_ParallelFailure_Bootstrap')]
+        WorkflowStubInterface $bootstrapStub,
+    ): void {
+        $bootstrapStub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-partial-fail');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_ParallelFailure_PartialCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(45)),
+        );
+
+        $client->start($stub, $endpoint->name);
+
+        $callerFailed = false;
+        try {
+            $stub->getResult('string');
+        } catch (WorkflowFailedException) {
+            $callerFailed = true;
+        }
+
+        self::assertTrue(
+            $callerFailed,
+            'Caller workflow must fail when a sibling Nexus operation fails inside Promise::all.',
+        );
+
+        $history = $client->getWorkflowHistory($stub->getExecution())->getHistory();
+        $scheduled = self::countEvents($history, EventType::EVENT_TYPE_NEXUS_OPERATION_SCHEDULED);
+        $failed = self::countEvents($history, EventType::EVENT_TYPE_NEXUS_OPERATION_FAILED);
+        $timedOut = self::countEvents($history, EventType::EVENT_TYPE_NEXUS_OPERATION_TIMED_OUT);
+
+        self::assertSame(
+            3,
+            $scheduled,
+            'All three Promise::all siblings must be scheduled before the workflow fails.',
+        );
+        self::assertGreaterThanOrEqual(
+            1,
+            $failed + $timedOut,
+            'At least one Nexus operation must terminate (Failed or TimedOut) so Promise::all can settle.',
+        );
+    }
+}
+
+#[Service(name: 'PartialFailureService')]
+class PartialFailureService
+{
+    #[Operation]
+    public function succeed(string $tag): string
+    {
+        return 'ok-' . $tag;
+    }
+
+    #[Operation]
+    public function fail(string $tag): string
+    {
+        throw OperationException::failed('partial-failure-' . $tag);
+    }
+}
+
+#[WorkflowInterface]
+class PartialFailureCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_ParallelFailure_PartialCaller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            PartialFailureService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(5)),
+        );
+
+        $promises = [
+            $stub->succeed('a'),
+            $stub->succeed('b'),
+            $stub->fail('c'),
+        ];
+
+        return yield Promise::all($promises);
+    }
+}
+
+#[WorkflowInterface]
+class ParallelFailureBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_ParallelFailure_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/ParallelMixed/MixedSyncAsyncTest.php b/tests/Acceptance/Extra/Nexus/ParallelMixed/MixedSyncAsyncTest.php
new file mode 100644
index 000000000..25cda95d9
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/ParallelMixed/MixedSyncAsyncTest.php
@@ -0,0 +1,152 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\ParallelMixed;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Promise;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHistoryAssertions;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/** Mixed sync + async Nexus operations awaited via Promise::all in one workflow tick. */
+#[Worker(options: [self::class, 'workerOptions'])]
+class MixedSyncAsyncTest extends TestCase
+{
+    use NexusHistoryAssertions;
+
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function syncAndAsyncOpsResolveTogetherInPromiseAll(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+        #[Stub('Extra_Nexus_ParallelMixed_Bootstrap')]
+        WorkflowStubInterface $bootstrapStub,
+    ): void {
+        $bootstrapStub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-mixed');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_ParallelMixed_Caller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(45)),
+        );
+
+        $client->start($stub, $endpoint->name);
+
+        self::assertSame('sync=ok-x|async=done-y', $stub->getResult('string'));
+
+        $history = $client->getWorkflowHistory($stub->getExecution())->getHistory();
+        $scheduled = self::countEvents($history, EventType::EVENT_TYPE_NEXUS_OPERATION_SCHEDULED);
+        $started = self::countEvents($history, EventType::EVENT_TYPE_NEXUS_OPERATION_STARTED);
+        $completed = self::countEvents($history, EventType::EVENT_TYPE_NEXUS_OPERATION_COMPLETED);
+
+        self::assertSame(
+            2,
+            $scheduled,
+            'Both sync and async siblings must emit NEXUS_OPERATION_SCHEDULED.',
+        );
+        self::assertSame(
+            1,
+            $started,
+            'Only the async sibling emits NEXUS_OPERATION_STARTED — discriminator vs sync path.',
+        );
+        self::assertSame(
+            2,
+            $completed,
+            'Both siblings must terminate via NEXUS_OPERATION_COMPLETED.',
+        );
+    }
+}
+
+#[Service(name: 'MixedSyncAsyncService')]
+class MixedSyncAsyncService
+{
+    #[Operation]
+    public function syncOp(string $tag): string
+    {
+        return 'ok-' . $tag;
+    }
+
+    #[AsyncOperation(output: 'string')]
+    public function asyncOp(string $tag): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            MixedAsyncHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(Nexus::getStartDetails()->requestId),
+            $tag,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class MixedAsyncHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_ParallelMixed_AsyncHandler')]
+    public function handle(string $tag)
+    {
+        // Force a workflow-task transition so the operation actually goes async
+        // (without a yield it collapses to the sync-async path, skipping NEXUS_OPERATION_STARTED).
+        yield Workflow::timer(CarbonInterval::milliseconds(100));
+        return 'done-' . $tag;
+    }
+}
+
+#[WorkflowInterface]
+class MixedSyncAsyncCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_ParallelMixed_Caller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            MixedSyncAsyncService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(30)),
+        );
+
+        [$syncResult, $asyncResult] = yield Promise::all([
+            $stub->syncOp('x'),
+            $stub->asyncOp('y'),
+        ]);
+
+        return "sync={$syncResult}|async={$asyncResult}";
+    }
+}
+
+#[WorkflowInterface]
+class ParallelMixedBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_ParallelMixed_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/Replay/ReplayTest.php b/tests/Acceptance/Extra/Nexus/Replay/ReplayTest.php
new file mode 100644
index 000000000..113ed81e7
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/Replay/ReplayTest.php
@@ -0,0 +1,400 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\Replay;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Exception\Failure\CanceledFailure;
+use Temporal\Exception\Failure\NexusOperationFailure;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Testing\Replay\Exception\ReplayerException;
+use Temporal\Testing\Replay\WorkflowReplayer;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusHistoryAssertions;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationCancellationType;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/** Replay coverage for caller-side Nexus operations: a clean replay proves determinism. */
+#[Worker(options: [self::class, 'workerOptions'])]
+class ReplayTest extends TestCase
+{
+    use NexusHistoryAssertions;
+
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function asyncWorkflowRunOperationReplaysCleanly(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-replay-async');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_Replay_AsyncCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(30)),
+        );
+
+        $client->start($stub, $endpoint->name, 'world');
+        self::assertSame('HELLO, WORLD!', $stub->getResult('string'));
+
+        $history = $client->getWorkflowHistory($stub->getExecution())->getHistory();
+
+        // Started discriminates async from sync; without it the test name lies.
+        self::assertContainsEvents(
+            $history,
+            [
+                EventType::EVENT_TYPE_NEXUS_OPERATION_SCHEDULED,
+                EventType::EVENT_TYPE_NEXUS_OPERATION_STARTED,
+                EventType::EVENT_TYPE_NEXUS_OPERATION_COMPLETED,
+            ],
+            'async caller history must include Scheduled+Started+Completed Nexus events',
+        );
+
+        (new WorkflowReplayer())->replayHistory($history);
+    }
+
+    #[Test]
+    public function timerBeforeNexusOperationReplaysCleanly(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-replay-timer');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_Replay_TimerThenSyncCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(30)),
+        );
+
+        $client->start($stub, $endpoint->name, 'world');
+        self::assertSame('Hello, world!', $stub->getResult('string'));
+
+        $history = $client->getWorkflowHistory($stub->getExecution())->getHistory();
+
+        // Timer + Nexus exercises Request::$lastID ordering across both command kinds.
+        self::assertContainsEvents(
+            $history,
+            [
+                EventType::EVENT_TYPE_TIMER_STARTED,
+                EventType::EVENT_TYPE_TIMER_FIRED,
+                EventType::EVENT_TYPE_NEXUS_OPERATION_SCHEDULED,
+                EventType::EVENT_TYPE_NEXUS_OPERATION_COMPLETED,
+            ],
+            'timer-then-nexus history must include both timer and Nexus events',
+        );
+
+        (new WorkflowReplayer())->replayHistory($history);
+    }
+
+    #[Test]
+    public function syncNexusOperationReplaysFromDumpedJsonFile(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-replay-dump');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_Replay_SyncCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(30)),
+        );
+
+        $client->start($stub, $endpoint->name, 'world');
+        self::assertSame('Hello, world!', $stub->getResult('string'));
+
+        $file = \dirname(__DIR__, 4) . '/runtime/tests/nexus-sync-history.json';
+        \is_dir(\dirname($file)) or \mkdir(\dirname($file), recursive: true);
+        \is_file($file) and \unlink($file);
+
+        try {
+            $replayer = new WorkflowReplayer();
+            $replayer->downloadHistory(
+                'Extra_Nexus_Replay_SyncCaller',
+                $stub->getExecution(),
+                $file,
+            );
+            self::assertFileExists($file);
+            // The file must really contain Nexus events before the JSON-replay step gets credit.
+            $contents = (string) \file_get_contents($file);
+            self::assertStringContainsString(
+                'EVENT_TYPE_NEXUS_OPERATION_SCHEDULED',
+                $contents,
+                'Dumped history JSON must contain a Nexus scheduled event.',
+            );
+            self::assertStringContainsString(
+                'EVENT_TYPE_NEXUS_OPERATION_COMPLETED',
+                $contents,
+                'Dumped history JSON must contain a Nexus completed event.',
+            );
+
+            // Round-trip exercises the JSON deserialiser path independent of proto-from-server.
+            $replayer->replayFromJSON('Extra_Nexus_Replay_SyncCaller', $file);
+        } finally {
+            \is_file($file) and \unlink($file);
+        }
+    }
+
+    #[Test]
+    public function mutatedNexusScheduledEventIsRejectedByReplayer(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-replay-mutate');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_Replay_SyncCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(30)),
+        );
+
+        $client->start($stub, $endpoint->name, 'world');
+        self::assertSame('Hello, world!', $stub->getResult('string'));
+
+        $history = $client->getWorkflowHistory($stub->getExecution())->getHistory();
+
+        // Clean replay first — otherwise the negative assertion below is vacuous.
+        (new WorkflowReplayer())->replayHistory($history);
+
+        // Mutate the recorded operation name; replay must detect the command mismatch.
+        $mutated = false;
+        foreach ($history->getEvents() as $event) {
+            if ($event->getEventType() !== EventType::EVENT_TYPE_NEXUS_OPERATION_SCHEDULED) {
+                continue;
+            }
+            $attrs = $event->getNexusOperationScheduledEventAttributes();
+            self::assertNotNull($attrs);
+            self::assertSame('greet', $attrs->getOperation());
+            $attrs->setOperation('mutatedOperationName');
+            $mutated = true;
+            break;
+        }
+        self::assertTrue(
+            $mutated,
+            'Test setup expected at least one NEXUS_OPERATION_SCHEDULED in history.',
+        );
+
+        $this->expectException(ReplayerException::class);
+        (new WorkflowReplayer())->replayHistory($history);
+    }
+
+    #[Test]
+    public function cancelledNexusOperationReplaysCleanly(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-replay-cancel');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_Replay_CancelCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(30)),
+        );
+
+        $client->start($stub, $endpoint->name, 'world');
+        self::assertSame('cancelled', $stub->getResult('string'));
+
+        $history = $client->getWorkflowHistory($stub->getExecution())->getHistory();
+
+        // Cancel must leave both the request marker and the terminal CANCELED event.
+        self::assertContainsEvents(
+            $history,
+            [
+                EventType::EVENT_TYPE_NEXUS_OPERATION_SCHEDULED,
+                EventType::EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUESTED,
+                EventType::EVENT_TYPE_NEXUS_OPERATION_CANCELED,
+            ],
+            'cancelled caller history must include Scheduled+CancelRequested+Canceled Nexus events',
+        );
+
+        (new WorkflowReplayer())->replayHistory($history);
+    }
+}
+
+// ── Sync Nexus service ─────────────────────────────────────────────────
+
+#[Service(name: 'ReplaySyncService')]
+class ReplaySyncService
+{
+    #[Operation]
+    public function greet(string $name): string
+    {
+        return "Hello, {$name}!";
+    }
+}
+
+// ── Async Nexus service (WorkflowRunOperation) ─────────────────────────
+
+#[Service(name: 'ReplayAsyncService')]
+class ReplayAsyncService
+{
+    #[AsyncOperation(output: 'string')]
+    public function shout(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            ReplayAsyncHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(Nexus::getStartDetails()->requestId),
+            $input,
+        );
+    }
+}
+
+// ── Async handler workflow ─────────────────────────────────────────────
+
+#[WorkflowInterface]
+class ReplayAsyncHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Replay_AsyncHandler')]
+    public function handle(string $input)
+    {
+        // One task transition so the operation goes async (Started event).
+        yield Workflow::timer(CarbonInterval::milliseconds(50));
+        return 'HELLO, ' . \strtoupper($input) . '!';
+    }
+}
+
+// ── Caller workflows ───────────────────────────────────────────────────
+
+#[WorkflowInterface]
+class ReplaySyncCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Replay_SyncCaller')]
+    public function run(string $endpoint, string $name)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            ReplaySyncService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(20)),
+        );
+        return yield $stub->greet($name);
+    }
+}
+
+#[WorkflowInterface]
+class ReplayAsyncCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Replay_AsyncCaller')]
+    public function run(string $endpoint, string $input)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            ReplayAsyncService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(20)),
+        );
+        return yield $stub->shout($input);
+    }
+}
+
+#[WorkflowInterface]
+class ReplayTimerThenSyncCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Replay_TimerThenSyncCaller')]
+    public function run(string $endpoint, string $name)
+    {
+        // Timer first: minimal interleaving that catches per-task command-id drift.
+        yield Workflow::timer(CarbonInterval::milliseconds(50));
+
+        $stub = Workflow::newNexusServiceStub(
+            ReplaySyncService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(20)),
+        );
+        return yield $stub->greet($name);
+    }
+}
+
+// ── Cancel-path Nexus service (long handler that does not recover) ──────
+
+#[Service(name: 'ReplayCancelService')]
+class ReplayCancelService
+{
+    #[AsyncOperation(output: 'string')]
+    public function longRunning(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            ReplayCancelHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(Nexus::getStartDetails()->requestId),
+            $input,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class ReplayCancelHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Replay_CancelHandler')]
+    public function handle(string $input)
+    {
+        yield Workflow::timer(CarbonInterval::seconds(30));
+        return "completed:{$input}";
+    }
+}
+
+#[WorkflowInterface]
+class ReplayCancelCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Replay_CancelCaller')]
+    public function run(string $endpoint, string $input)
+    {
+        // WaitCompleted: with WaitRequested the caller closes before the terminal CANCELED lands.
+        $stub = Workflow::newNexusServiceStub(
+            ReplayCancelService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(60))
+                ->withCancellationType(NexusOperationCancellationType::WaitCompleted),
+        );
+
+        $promise = null;
+        $scope = Workflow::async(static function () use ($stub, $input, &$promise): void {
+            $promise = $stub->longRunning($input);
+        });
+
+        yield Workflow::timer(CarbonInterval::seconds(NexusWorkerOptions::PRE_CANCEL_TIMER_SECONDS));
+        $scope->cancel();
+
+        try {
+            yield $promise;
+        } catch (NexusOperationFailure $e) {
+            if ($e->getPrevious() instanceof CanceledFailure) {
+                return 'cancelled';
+            }
+            throw $e;
+        }
+
+        return 'unexpected-completion';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/ReverseLinks/ReverseLinkTest.php b/tests/Acceptance/Extra/Nexus/ReverseLinks/ReverseLinkTest.php
new file mode 100644
index 000000000..42cd05208
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/ReverseLinks/ReverseLinkTest.php
@@ -0,0 +1,184 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\ReverseLinks;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Tests\Acceptance\App\Attribute\Stub;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowExecution;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Handler's WorkflowExecutionStarted event carries a CompletionCallback link
+ * back to the caller. Server-set; requires Temporal 1.27+ to populate the slot.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class ReverseLinkTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function handlerWorkflowExecutionStartedCarriesCallbackLinkBackToCaller(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+        #[Stub('Extra_Nexus_ReverseLinks_Bootstrap')]
+        WorkflowStubInterface $bootstrapStub,
+    ): void {
+        $bootstrapStub->getResult('string');
+
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-reverse-link');
+
+        $callerStub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_ReverseLinks_Caller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(30)),
+        );
+
+        $client->start($callerStub, $endpoint->name);
+
+        self::assertSame('done-reverse-link', $callerStub->getResult('string'));
+
+        $callerExecution = $callerStub->getExecution();
+        $handlerExecution = self::lookupHandlerExecution($client, $callerExecution);
+
+        $handlerHistory = $client->getWorkflowHistory($handlerExecution)->getHistory();
+        $startedAttributes = null;
+        foreach ($handlerHistory->getEvents() as $event) {
+            if ($event->getEventType() === EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED) {
+                $startedAttributes = $event->getWorkflowExecutionStartedEventAttributes();
+                break;
+            }
+        }
+        self::assertNotNull($startedAttributes, 'Handler workflow must have a WORKFLOW_EXECUTION_STARTED event.');
+
+        $callbacks = $startedAttributes->getCompletionCallbacks();
+        self::assertGreaterThan(
+            0,
+            $callbacks->count(),
+            'Handler workflow must have at least one completion callback on its started event.',
+        );
+
+        $matched = false;
+        foreach ($callbacks as $callback) {
+            foreach ($callback->getLinks() as $link) {
+                $workflowEvent = $link->getWorkflowEvent();
+                if ($workflowEvent === null) {
+                    continue;
+                }
+                if (
+                    $workflowEvent->getNamespace() === $state->namespace
+                    && $workflowEvent->getWorkflowId() === $callerExecution->getID()
+                ) {
+                    $matched = true;
+                    break 2;
+                }
+            }
+        }
+        self::assertTrue(
+            $matched,
+            'Handler started event must carry a CompletionCallback link with a workflow_event '
+            . 'pointing to the caller workflow ' . $callerExecution->getID() . '.',
+        );
+    }
+
+    private static function lookupHandlerExecution(
+        WorkflowClientInterface $client,
+        WorkflowExecution $callerExecution,
+    ): WorkflowExecution {
+        $callerHistory = $client->getWorkflowHistory($callerExecution)->getHistory();
+        foreach ($callerHistory->getEvents() as $event) {
+            if ($event->getEventType() !== EventType::EVENT_TYPE_NEXUS_OPERATION_STARTED) {
+                continue;
+            }
+            $startedEventAttributes = $event->getNexusOperationStartedEventAttributes();
+            $token = $startedEventAttributes?->getOperationToken() ?? '';
+            self::assertNotSame('', $token, 'Caller history must carry a non-empty operation token.');
+            $decoded = \json_decode(\base64_decode(\strtr($token, '-_', '+/')), true);
+            self::assertIsArray($decoded, "Operation token did not decode as JSON: {$token}");
+            $workflowId = $decoded['wid'] ?? null;
+            self::assertIsString($workflowId, "Operation token JSON missing 'wid': " . \var_export($decoded, true));
+
+            // The token only carries the workflow id; describe the workflow to learn its run id,
+            // which getWorkflowHistory requires (see WorkflowClient::getWorkflowHistory).
+            $handlerStub = $client->newUntypedRunningWorkflowStub($workflowId);
+            return $handlerStub->describe()->info->execution;
+        }
+        self::fail('Caller history did not contain a NEXUS_OPERATION_STARTED event; cannot derive handler workflow id.');
+    }
+}
+
+#[Service(name: 'ReverseLinkService')]
+class ReverseLinkService
+{
+    #[AsyncOperation(output: 'string')]
+    public function backedByWorkflow(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            ReverseLinkHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(Nexus::getStartDetails()->requestId),
+            $input,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class ReverseLinkHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_ReverseLinks_Handler')]
+    public function handle(string $input)
+    {
+        yield Workflow::timer(CarbonInterval::milliseconds(50));
+        return 'done-' . $input;
+    }
+}
+
+#[WorkflowInterface]
+class ReverseLinkCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_ReverseLinks_Caller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            ReverseLinkService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(20)),
+        );
+
+        return yield $stub->backedByWorkflow('reverse-link');
+    }
+}
+
+#[WorkflowInterface]
+class ReverseLinksBootstrapWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_ReverseLinks_Bootstrap')]
+    public function run(): string
+    {
+        return 'ready';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/SyncFailure/SyncFailureTest.php b/tests/Acceptance/Extra/Nexus/SyncFailure/SyncFailureTest.php
new file mode 100644
index 000000000..9784328ea
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/SyncFailure/SyncFailureTest.php
@@ -0,0 +1,468 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\SyncFailure;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\DataConverter\EncodedValues;
+use Temporal\Exception\Failure\ApplicationFailure;
+use Temporal\Exception\Failure\CanceledFailure;
+use Temporal\Exception\Failure\NexusHandlerFailure;
+use Temporal\Exception\Failure\NexusOperationFailure;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\OperationException;
+use Temporal\Nexus\Exception\RetryBehavior;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/** Caller-workflow failure mapping for SYNC Nexus operations. */
+#[Worker(options: [self::class, 'workerOptions'])]
+class SyncFailureTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function callerCatchesNexusOperationFailureWithApplicationFailureCause(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-sync-fail-app');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_SyncFailure_AppFailureCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(15)),
+        );
+
+        $client->start($stub, $endpoint->name);
+
+        self::assertSame('ok', $stub->getResult('string'));
+    }
+
+    #[Test]
+    public function callerCatchesCanceledFailureWhenHandlerCancelsTheOperation(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-sync-cancel-app');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_SyncFailure_CanceledCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(15)),
+        );
+
+        $client->start($stub, $endpoint->name);
+
+        self::assertSame('ok', $stub->getResult('string'));
+    }
+
+    #[Test]
+    public function handlerErrorBadRequest(State $state, WorkflowClientInterface $client, NexusEndpoints $endpoints): void
+    {
+        self::assertSame('ok', $this->runHandlerErrorScenario($state, $client, $endpoints, 'badRequest', 'BAD_REQUEST'));
+    }
+
+    #[Test]
+    public function handlerErrorInternal(State $state, WorkflowClientInterface $client, NexusEndpoints $endpoints): void
+    {
+        self::assertSame('ok', $this->runHandlerErrorScenario($state, $client, $endpoints, 'internal', 'INTERNAL'));
+    }
+
+    #[Test]
+    public function handlerErrorNotFound(State $state, WorkflowClientInterface $client, NexusEndpoints $endpoints): void
+    {
+        self::assertSame('ok', $this->runHandlerErrorScenario($state, $client, $endpoints, 'notFound', 'NOT_FOUND'));
+    }
+
+    #[Test]
+    public function handlerErrorUnauthorized(State $state, WorkflowClientInterface $client, NexusEndpoints $endpoints): void
+    {
+        self::assertSame('ok', $this->runHandlerErrorScenario($state, $client, $endpoints, 'unauthorized', 'UNAUTHORIZED'));
+    }
+
+    #[Test]
+    public function applicationFailureCausePreservesTypeMessageAndDetails(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-sync-fail-rich-cause');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_SyncFailure_RichCauseCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(15)),
+        );
+
+        $client->start($stub, $endpoint->name);
+
+        self::assertSame('ok', $stub->getResult('string'));
+    }
+
+    #[Test]
+    public function callerReceivesNotFoundForUnknownOperation(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-sync-unknown-op');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_SyncFailure_UnknownOperationCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(15)),
+        );
+
+        $client->start($stub, $endpoint->name);
+
+        self::assertSame('ok', $stub->getResult('string'));
+    }
+
+    private function runHandlerErrorScenario(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+        string $opName,
+        string $expectedType,
+    ): string {
+        $endpoint = $endpoints->register(
+            $state->namespace,
+            __NAMESPACE__,
+            'nexus-sync-handler-err-' . \strtolower($opName),
+        );
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_SyncFailure_HandlerErrorCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(15)),
+        );
+
+        $client->start($stub, $endpoint->name, $opName, $expectedType);
+
+        return $stub->getResult('string');
+    }
+}
+
+// ── Service A: throws OperationException::failed() ─────────────────
+
+#[Service(name: 'SyncFailureAppService')]
+class SyncFailureAppService
+{
+    #[Operation]
+    public function failAlways(string $input): string
+    {
+        throw OperationException::failed('business-error');
+    }
+
+    #[Operation]
+    public function cancelAlways(string $input): string
+    {
+        throw OperationException::canceled('operation canceled by the handler');
+    }
+}
+
+#[WorkflowInterface]
+class AppFailureCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_SyncFailure_AppFailureCaller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            SyncFailureAppService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(10)),
+        );
+
+        try {
+            yield $stub->failAlways('ignored');
+        } catch (NexusOperationFailure $e) {
+            $cause = $e->getPrevious();
+            if (!$cause instanceof ApplicationFailure) {
+                return 'wrong-cause-type:' . \get_debug_type($cause);
+            }
+            if ($cause->getType() !== 'OperationError') {
+                return "wrong-type:{$cause->getType()}";
+            }
+            if (!\str_contains($cause->getOriginalMessage(), 'business-error')) {
+                return "missing-message:{$cause->getOriginalMessage()}";
+            }
+            return 'ok';
+        }
+
+        return 'unexpected:no-exception';
+    }
+}
+
+#[WorkflowInterface]
+class CanceledCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_SyncFailure_CanceledCaller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            SyncFailureAppService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(10)),
+        );
+
+        try {
+            yield $stub->cancelAlways('ignored');
+        } catch (NexusOperationFailure $e) {
+            $cause = $e->getPrevious();
+            if (!$cause instanceof CanceledFailure) {
+                return 'wrong-cause-type:' . \get_debug_type($cause);
+            }
+
+            return 'ok';
+        }
+
+        return 'unexpected:no-exception';
+    }
+}
+
+// ── Service B: throws HandlerException with various ErrorTypes ─────
+
+// Interface + impl shape kept here on purpose: pairs with the untyped-stub
+// caller workflow below to cover the "service contract on an interface, called
+// via newUntypedNexusOperationStub" path end-to-end.
+#[Service(name: 'SyncHandlerErrorService')]
+interface SyncHandlerErrorService
+{
+    #[Operation]
+    public function badRequest(string $input): string;
+
+    #[Operation]
+    public function internal(string $input): string;
+
+    #[Operation]
+    public function notFound(string $input): string;
+
+    #[Operation]
+    public function unauthorized(string $input): string;
+}
+
+final class SyncHandlerErrorServiceImpl implements SyncHandlerErrorService
+{
+    public function badRequest(string $input): string
+    {
+        throw HandlerException::create(ErrorType::BadRequest, 'bad-request-msg');
+    }
+
+    public function internal(string $input): string
+    {
+        // `Internal` is retryable by default — force NonRetryable so the caller
+        // sees the handler error directly instead of a TimeoutFailure after
+        // retries exhaust the schedule-to-close window.
+        throw HandlerException::create(ErrorType::Internal, 'internal-msg', null, RetryBehavior::NonRetryable);
+    }
+
+    public function notFound(string $input): string
+    {
+        throw HandlerException::create(ErrorType::NotFound, 'not-found-msg');
+    }
+
+    public function unauthorized(string $input): string
+    {
+        throw HandlerException::create(ErrorType::Unauthorized, 'unauthorized-msg');
+    }
+}
+
+#[WorkflowInterface]
+class HandlerErrorCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_SyncFailure_HandlerErrorCaller')]
+    public function run(string $endpoint, string $opName, string $expectedErrorType)
+    {
+        $stub = Workflow::newUntypedNexusOperationStub(
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withService('SyncHandlerErrorService')
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(10)),
+        );
+
+        try {
+            yield $stub->execute($opName, ['ignored']);
+        } catch (NexusOperationFailure $e) {
+            $cause = $e->getPrevious();
+            if (!$cause instanceof NexusHandlerFailure) {
+                $causeName = $cause === null ? 'null' : $cause::class;
+                return "wrong-cause-type:{$causeName}";
+            }
+
+            if ($cause->getType() !== $expectedErrorType) {
+                return "wrong-error-type:got={$cause->getType()}:want={$expectedErrorType}";
+            }
+
+            return 'ok';
+        }
+
+        return 'unexpected:no-exception';
+    }
+}
+
+// ── Service D: throws OperationException::failed with a rich ApplicationFailure cause ──
+
+#[Service(name: 'SyncFailureRichCauseService')]
+class SyncFailureRichCauseService
+{
+    #[Operation]
+    public function failWithRichCause(string $input): string
+    {
+        throw OperationException::failed(
+            'outer-business-error',
+            new ApplicationFailure(
+                'inner-business-message',
+                'CustomBusinessType',
+                false,
+                EncodedValues::fromValues(['detail-payload-marker']),
+            ),
+        );
+    }
+}
+
+#[WorkflowInterface]
+class RichCauseCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_SyncFailure_RichCauseCaller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            SyncFailureRichCauseService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(10)),
+        );
+
+        try {
+            yield $stub->failWithRichCause('ignored');
+        } catch (NexusOperationFailure $e) {
+            $innerType = self::findApplicationFailureType($e, 'CustomBusinessType');
+            if ($innerType === null) {
+                return self::dumpChain($e, 'inner-CustomBusinessType-not-found-in-chain');
+            }
+
+            $messageHaystack = $innerType->getOriginalMessage() . '|' . $innerType->getMessage();
+            if (!\str_contains($messageHaystack, 'inner-business-message')) {
+                return "missing-inner-message:haystack={$messageHaystack}";
+            }
+
+            $details = $innerType->getDetails();
+            if ($details->count() === 0) {
+                return 'missing-details:zero-values';
+            }
+
+            $detailValue = $details->getValue(0, 'string');
+            if ($detailValue !== 'detail-payload-marker') {
+                return "wrong-detail-payload:{$detailValue}";
+            }
+
+            return 'ok';
+        }
+
+        return 'unexpected:no-exception';
+    }
+
+    private static function findApplicationFailureType(\Throwable $e, string $type): ?ApplicationFailure
+    {
+        $current = $e;
+        while ($current !== null) {
+            if ($current instanceof ApplicationFailure && $current->getType() === $type) {
+                return $current;
+            }
+            $current = $current->getPrevious();
+        }
+        return null;
+    }
+
+    private static function dumpChain(\Throwable $e, string $reason): string
+    {
+        $entries = [];
+        $current = $e;
+        while ($current !== null) {
+            $entry = $current::class;
+            if ($current instanceof ApplicationFailure) {
+                $entry .= '(type=' . $current->getType()
+                    . ',msg=' . $current->getOriginalMessage()
+                    . ',details=' . $current->getDetails()->count() . ')';
+            } else {
+                $entry .= '(msg=' . $current->getMessage() . ')';
+            }
+            $entries[] = $entry;
+            $current = $current->getPrevious();
+        }
+        return $reason . '|chain=' . \implode('->', $entries);
+    }
+}
+
+// ── Service C: known service for "unknown operation" scenario ──────
+
+#[Service(name: 'KnownService')]
+class KnownService
+{
+    #[Operation]
+    public function knownOp(string $input): string
+    {
+        return "known:{$input}";
+    }
+}
+
+#[WorkflowInterface]
+class UnknownOperationCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_SyncFailure_UnknownOperationCaller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newUntypedNexusOperationStub(
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withService('KnownService')
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(10)),
+        );
+
+        try {
+            yield $stub->execute('definitelyNotRegistered', ['x']);
+        } catch (NexusOperationFailure $e) {
+            $cause = $e->getPrevious();
+            if (!$cause instanceof NexusHandlerFailure) {
+                $causeName = $cause === null ? 'null' : $cause::class;
+                return "wrong-cause-type:{$causeName}";
+            }
+
+            if ($cause->getType() !== 'NOT_FOUND') {
+                return "wrong-error-type:{$cause->getType()}";
+            }
+
+            return 'ok';
+        }
+
+        return 'unexpected:no-exception';
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/SyncFromWorkflow/SyncFromWorkflowTest.php b/tests/Acceptance/Extra/Nexus/SyncFromWorkflow/SyncFromWorkflowTest.php
new file mode 100644
index 000000000..de77be9f7
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/SyncFromWorkflow/SyncFromWorkflowTest.php
@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\SyncFromWorkflow;
+
+use Carbon\CarbonInterval;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * Smoke test for the workflow → Nexus path with a SYNC handler.
+ *
+ * Distinct from the Cancel/Async suite (which only exercises HTTP-side
+ * Nexus invocation): here a workflow yields a Nexus stub call and waits
+ * for the result over the SDK wire.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class SyncFromWorkflowTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function workflowCallsSyncNexusOperationAndGetsResult(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-sync-from-wf');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_SyncFromWorkflow_Caller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(30)),
+        );
+
+        $client->start($stub, $endpoint->name, 'world');
+
+        self::assertSame('Hello, world!', $stub->getResult('string'));
+    }
+}
+
+// This test deliberately keeps the interface + impl shape so we cover the
+// "service contract on an interface, impl on a separate class" path end-to-end
+// — the rest of the Nexus acceptance suite runs the class-only shape.
+#[Service(name: 'SyncFromWorkflowService')]
+interface SyncFromWorkflowService
+{
+    #[Operation]
+    public function greet(string $name): string;
+}
+
+final class SyncFromWorkflowServiceImpl implements SyncFromWorkflowService
+{
+    public function greet(string $name): string
+    {
+        return "Hello, {$name}!";
+    }
+}
+
+#[WorkflowInterface]
+class SyncFromWorkflowCaller
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_SyncFromWorkflow_Caller')]
+    public function run(string $endpoint, string $name)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            SyncFromWorkflowService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(20)),
+        );
+        return yield $stub->greet($name);
+    }
+}
diff --git a/tests/Acceptance/Extra/Nexus/Timeout/TimeoutTest.php b/tests/Acceptance/Extra/Nexus/Timeout/TimeoutTest.php
new file mode 100644
index 000000000..1f6d57975
--- /dev/null
+++ b/tests/Acceptance/Extra/Nexus/Timeout/TimeoutTest.php
@@ -0,0 +1,187 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Acceptance\Extra\Nexus\Timeout;
+
+use Carbon\CarbonInterval;
+use PHPUnit\Framework\Attributes\Test;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Exception\Failure\NexusOperationFailure;
+use Temporal\Exception\Failure\TimeoutFailure;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Tests\Acceptance\App\Attribute\Worker;
+use Temporal\Tests\Acceptance\App\Runtime\State;
+use Temporal\Tests\Acceptance\App\TestCase;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusEndpoints;
+use Temporal\Tests\Acceptance\Extra\Nexus\NexusWorkerOptions;
+use Temporal\Worker\WorkerOptions;
+use Temporal\Workflow;
+use Temporal\Workflow\NexusOperationOptions;
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+/**
+ * P2 #10–11 — `scheduleToCloseTimeout` enforcement on caller side.
+ *
+ * Two scenarios:
+ *   - sync handler runs longer than the timeout → caller catches a
+ *     {@see NexusOperationFailure} whose cause is {@see TimeoutFailure}.
+ *   - async handler workflow runs longer than the timeout → same.
+ *
+ * P2 #12 ("retry within timeout") is deferred — `NexusOperationOptions` does
+ * not currently expose a retry policy, so retry semantics are server-driven
+ * and not under direct caller control. Tracked as a gap in nexus_plan.md.
+ */
+#[Worker(options: [self::class, 'workerOptions'])]
+class TimeoutTest extends TestCase
+{
+    public static function workerOptions(): WorkerOptions
+    {
+        return NexusWorkerOptions::default();
+    }
+
+    #[Test]
+    public function syncOperationTimesOutOnCaller(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-timeout-sync');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_Timeout_SyncCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(20)),
+        );
+
+        $client->start($stub, $endpoint->name);
+
+        self::assertSame('ok', $stub->getResult('string'));
+    }
+
+    #[Test]
+    public function asyncOperationTimesOutOnCaller(
+        State $state,
+        WorkflowClientInterface $client,
+        NexusEndpoints $endpoints,
+    ): void {
+        $endpoint = $endpoints->register($state->namespace, __NAMESPACE__, 'nexus-timeout-async');
+
+        $stub = $client->newUntypedWorkflowStub(
+            'Extra_Nexus_Timeout_AsyncCaller',
+            WorkflowOptions::new()
+                ->withTaskQueue(__NAMESPACE__)
+                ->withWorkflowExecutionTimeout(CarbonInterval::seconds(20)),
+        );
+
+        $client->start($stub, $endpoint->name);
+
+        self::assertSame('ok', $stub->getResult('string'));
+    }
+}
+
+// ── Sync service: handler sleeps past the caller's timeout ─────────
+
+#[Service(name: 'TimeoutSyncService')]
+class TimeoutSyncService
+{
+    #[Operation]
+    public function slowSync(string $input): string
+    {
+        // PHP-side handler blocks the worker thread; sleep just past the
+        // caller's 2s scheduleToCloseTimeout.
+        \sleep(5);
+        return "should-not-reach:{$input}";
+    }
+}
+
+#[WorkflowInterface]
+class TimeoutSyncCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Timeout_SyncCaller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            TimeoutSyncService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(2)),
+        );
+
+        try {
+            yield $stub->slowSync('payload');
+        } catch (NexusOperationFailure $e) {
+            $cause = $e->getPrevious();
+            if (!$cause instanceof TimeoutFailure) {
+                $causeName = $cause === null ? 'null' : $cause::class;
+                return "wrong-cause:{$causeName}";
+            }
+            return 'ok';
+        }
+
+        return 'unexpected:no-exception';
+    }
+}
+
+// ── Async service: handler workflow sleeps past the caller's timeout ─
+
+#[Service(name: 'TimeoutAsyncService')]
+class TimeoutAsyncService
+{
+    #[AsyncOperation(output: 'string')]
+    public function slowAsync(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            SlowHandlerWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(Nexus::getStartDetails()->requestId),
+            $input,
+        );
+    }
+}
+
+#[WorkflowInterface]
+class SlowHandlerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Timeout_SlowHandler')]
+    public function handle(string $input)
+    {
+        // Sleep well past the caller's 3s timeout.
+        yield Workflow::timer(CarbonInterval::seconds(15));
+        return "should-not-reach:{$input}";
+    }
+}
+
+#[WorkflowInterface]
+class TimeoutAsyncCallerWorkflow
+{
+    #[WorkflowMethod(name: 'Extra_Nexus_Timeout_AsyncCaller')]
+    public function run(string $endpoint)
+    {
+        $stub = Workflow::newNexusServiceStub(
+            TimeoutAsyncService::class,
+            NexusOperationOptions::new()
+                ->withEndpoint($endpoint)
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(3)),
+        );
+
+        try {
+            yield $stub->slowAsync('payload');
+        } catch (NexusOperationFailure $e) {
+            $cause = $e->getPrevious();
+            if (!$cause instanceof TimeoutFailure) {
+                $causeName = $cause === null ? 'null' : $cause::class;
+                return "wrong-cause:{$causeName}";
+            }
+            return 'ok';
+        }
+
+        return 'unexpected:no-exception';
+    }
+}
diff --git a/tests/Acceptance/Extra/Workflow/MutexRunLockedTest.php b/tests/Acceptance/Extra/Workflow/MutexRunLockedTest.php
index 62a92eced..9223ca106 100644
--- a/tests/Acceptance/Extra/Workflow/MutexRunLockedTest.php
+++ b/tests/Acceptance/Extra/Workflow/MutexRunLockedTest.php
@@ -69,6 +69,7 @@ public function __construct()
     #[Workflow\ReturnType(Type::TYPE_ARRAY)]
     public function handle(): \Generator
     {
+        $result = null;
         $exception = null;
         try {
             $result = yield $this->promise = Workflow::runLocked($this->mutex, $this->runLocked(...));
@@ -79,7 +80,7 @@ public function handle(): \Generator
         $trailed = false;
         yield Workflow::await(
             fn() => $this->exit,
-            Workflow::runLocked($this->mutex, static function () use (&$trailed) {
+            Workflow::runLocked($this->mutex, static function () use (&$trailed): void {
                 $trailed = true;
             }),
         );
@@ -110,7 +111,7 @@ private function runLocked(): \Generator
         // Permanently lock mutex
         Workflow::runLocked($this->mutex, function () {
             $this->unlocked = true;
-            yield Workflow::await(fn() => false);
+            yield Workflow::await(static fn() => false);
         });
 
         yield Workflow::await(fn() => $this->unblock);
diff --git a/tests/Acceptance/worker.php b/tests/Acceptance/worker.php
index 08da5fa6d..486962652 100644
--- a/tests/Acceptance/worker.php
+++ b/tests/Acceptance/worker.php
@@ -97,20 +97,6 @@
     $converter = new DataConverter(...$converters);
     $container->bindSingleton(DataConverter::class, $converter);
 
-    $plugins = [new TranscriptPlugin($workerTranscript)];
-    $container->bindSingleton(
-        WorkerFactoryInterface::class,
-        WorkerFactory::create(
-            converter: $converter,
-            pluginRegistry: new PluginRegistry($plugins),
-        )
-    );
-
-    $workerFactory = $container->get(\Temporal\Tests\Acceptance\App\Feature\WorkerFactory::class);
-    $getWorker = static function (Feature $feature) use (&$workers, $workerFactory): WorkerInterface {
-        return $workers[$feature->taskQueue] ??= $workerFactory->createWorker($feature);
-    };
-
     $serviceClient = $runtime->command->tlsKey === null && $runtime->command->tlsCert === null
         ? ServiceClient::create($runtime->address)
         : ServiceClient::createSSL(
@@ -122,6 +108,21 @@
     $workflowClient = WorkflowClient::create(serviceClient: $serviceClient, options: $options, converter: $converter);
     $scheduleClient = ScheduleClient::create(serviceClient: $serviceClient, options: $options, converter: $converter);
 
+    $container->bindSingleton(
+        WorkerFactoryInterface::class,
+        WorkerFactory::create(
+            converter: $converter,
+            pluginRegistry: new PluginRegistry([new TranscriptPlugin($workerTranscript)]),
+            client: $workflowClient,
+        ),
+    );
+
+    $workerFactory =  $container->get(\Temporal\Tests\Acceptance\App\Feature\WorkerFactory::class);
+    $getWorker = static function (Feature $feature) use (&$workers, $workerFactory): WorkerInterface {
+        return $workers[$feature->taskQueue] ??= $workerFactory->createWorker($feature);
+    };
+
+    // Bind services
     $container->bindSingleton(State::class, $runtime);
     $container->bindSingleton(LoggerInterface::class, $logger);
     $container->bindSingleton(ServiceClientInterface::class, $serviceClient);
@@ -141,6 +142,11 @@
         $getWorker($feature)->registerActivityImplementations($container->make($activity));
     }
 
+    // Register Nexus Services
+    foreach ($runtime->nexusServices() as $feature => $nexusService) {
+        $getWorker($feature)->registerNexusServiceImplementation($container->make($nexusService));
+    }
+
     $host = new RecordingHost(RoadRunner::create(), $workerTranscript);
     $container->get(WorkerFactoryInterface::class)->run($host);
 } catch (\Throwable $e) {
diff --git a/tests/Arch/NexusDependencyTest.php b/tests/Arch/NexusDependencyTest.php
new file mode 100644
index 000000000..e149823fb
--- /dev/null
+++ b/tests/Arch/NexusDependencyTest.php
@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Arch;
+
+use PHPUnit\Architecture\ArchitectureAsserts;
+use PHPUnit\Framework\TestCase;
+use Temporal\Nexus\Handler\Internal\HandlerInterface;
+use Temporal\Nexus\Handler\Internal\MethodOperationHandler;
+use Temporal\Nexus\Handler\Internal\ServiceHandler;
+use Temporal\Nexus\Handler\Internal\WorkflowRunStarter;
+use Temporal\Nexus\Header;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\NexusOperationContext;
+use Temporal\Nexus\WorkflowHandle;
+
+final class NexusDependencyTest extends TestCase
+{
+    protected array $excludedPaths = [
+        'vendor',
+        'tests',
+    ];
+
+    use ArchitectureAsserts;
+
+    /**
+     * Public `Temporal\Nexus\*` types that are allowed to reach into
+     * `Temporal\Internal\*` / `Temporal\Client\*`: the `Handler\Internal` dispatch
+     * subtree plus the facade/DTO types that bridge to the worker runtime.
+     *
+     * @var list<class-string>
+     */
+    private const EXEMPT = [
+        HandlerInterface::class,
+        MethodOperationHandler::class,
+        ServiceHandler::class,
+        WorkflowRunStarter::class,
+        Nexus::class,
+        Header::class,
+        NexusOperationContext::class,
+        WorkflowHandle::class,
+    ];
+
+    public function testPublicNexusNamespaceDoesNotDependOnInternalOrClient(): void
+    {
+        $violations = [];
+
+        foreach ($this->layer() as $object) {
+            if (!\str_starts_with($object->name, 'Temporal\\Nexus\\')) {
+                continue;
+            }
+            if (\in_array($object->name, self::EXEMPT, true)) {
+                continue;
+            }
+
+            foreach ($object->uses as $use) {
+                if (\str_starts_with($use, 'Temporal\\Internal\\') || \str_starts_with($use, 'Temporal\\Client\\')) {
+                    $violations[] = "{$object->name} -> {$use}";
+                }
+            }
+        }
+
+        self::assertSame(
+            [],
+            $violations,
+            'Public Temporal\Nexus\* classes must depend only on Common/Exception/Workflow (plus the '
+            . 'documented exemptions in self::EXEMPT); they must not reach into Temporal\Internal\* or Temporal\Client\*.',
+        );
+    }
+}
diff --git a/tests/Fixtures/src/Workflow/ZeroTimerWorkflow.php b/tests/Fixtures/src/Workflow/ZeroTimerWorkflow.php
new file mode 100644
index 000000000..eccbc34d5
--- /dev/null
+++ b/tests/Fixtures/src/Workflow/ZeroTimerWorkflow.php
@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Workflow;
+
+use Temporal\Workflow;
+use Temporal\Workflow\WorkflowMethod;
+
+#[Workflow\WorkflowInterface]
+class ZeroTimerWorkflow
+{
+    #[WorkflowMethod(name: 'ZeroTimerWorkflow')]
+    public function handler(int $seconds): \Generator
+    {
+        $delay = yield Workflow::sideEffect(static fn(): int => $seconds);
+
+        yield Workflow::timer($delay);
+
+        return 'done';
+    }
+}
diff --git a/tests/Functional/ReplayerTestCase.php b/tests/Functional/ReplayerTestCase.php
index 2ab06c1e3..fc3d51908 100644
--- a/tests/Functional/ReplayerTestCase.php
+++ b/tests/Functional/ReplayerTestCase.php
@@ -25,20 +25,6 @@ final class ReplayerTestCase extends TestCase
 {
     private WorkflowClient $workflowClient;
 
-    protected function setUp(): void
-    {
-        $this->workflowClient = new WorkflowClient(
-            ServiceClient::create(TemporalServer::address())
-        );
-
-        parent::setUp();
-    }
-
-    protected function tearDown(): void
-    {
-        parent::tearDown();
-    }
-
     public function testReplayWorkflowFromServer(): void
     {
         $workflow = $this->workflowClient->newWorkflowStub(WorkflowWithSequence::class);
@@ -254,7 +240,7 @@ public function testFilterHistory(): void
         $history = $this->workflowClient->getWorkflowHistory(
             execution: $run->getExecution(),
             historyEventFilterType: HistoryEventFilterType::HISTORY_EVENT_FILTER_TYPE_CLOSE_EVENT,
-            skipArchival: true
+            skipArchival: true,
         )->getHistory();
 
         $this->assertCount(1, \iterator_to_array($history->getEvents(), false));
@@ -328,10 +314,21 @@ public function testReplayNotExistingWorkflowHistory(): void
         (new WorkflowReplayer())->replayHistory($history);
     }
 
+    protected function setUp(): void
+    {
+        $this->workflowClient = new WorkflowClient(
+            ServiceClient::create(TemporalServer::address()),
+        );
+
+        parent::setUp();
+    }
+
     private function createAwaitsUpdateUntypedStub(WorkflowClient $client): WorkflowStubInterface
     {
-        return $client->newWorkflowStub(AwaitsUpdateWorkflow::class, WorkflowOptions::new()
-            ->withWorkflowRunTimeout('10 seconds')
+        return $client->newWorkflowStub(
+            AwaitsUpdateWorkflow::class,
+            WorkflowOptions::new()
+                ->withWorkflowRunTimeout('10 seconds'),
         )->__getUntypedStub();
     }
 }
diff --git a/tests/Functional/ZeroTimerTestCase.php b/tests/Functional/ZeroTimerTestCase.php
new file mode 100644
index 000000000..50767e6d4
--- /dev/null
+++ b/tests/Functional/ZeroTimerTestCase.php
@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Functional;
+
+use Temporal\Client\GRPC\ServiceClient;
+use Temporal\Client\WorkflowClient;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Testing\TemporalServer;
+use Temporal\Tests\TestCase;
+use Temporal\Tests\Workflow\ZeroTimerWorkflow;
+
+final class ZeroTimerTestCase extends TestCase
+{
+    private WorkflowClient $workflowClient;
+
+    public function testZeroIntervalTimerFires(): void
+    {
+        self::assertSame('done', $this->runWith(0));
+    }
+
+    public function testNonZeroIntervalTimerFires(): void
+    {
+        self::assertSame('done', $this->runWith(1));
+    }
+
+    protected function setUp(): void
+    {
+        $this->workflowClient = new WorkflowClient(
+            ServiceClient::create(TemporalServer::address()),
+        );
+
+        parent::setUp();
+    }
+
+    private function runWith(int $seconds): mixed
+    {
+        $workflow = $this->workflowClient->newWorkflowStub(
+            ZeroTimerWorkflow::class,
+            WorkflowOptions::new()->withTaskQueue('default'),
+        );
+
+        return $this->workflowClient->start($workflow, $seconds)->getResult('string', 10);
+    }
+}
diff --git a/tests/Nexus/Fixtures/Service/FakeGreetingWorkflow.php b/tests/Nexus/Fixtures/Service/FakeGreetingWorkflow.php
new file mode 100644
index 000000000..cd57a8ad5
--- /dev/null
+++ b/tests/Nexus/Fixtures/Service/FakeGreetingWorkflow.php
@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\Service;
+
+final class FakeGreetingWorkflow {}
diff --git a/tests/Nexus/Fixtures/Service/GenericServiceInterface.php b/tests/Nexus/Fixtures/Service/GenericServiceInterface.php
new file mode 100644
index 000000000..b3e10204b
--- /dev/null
+++ b/tests/Nexus/Fixtures/Service/GenericServiceInterface.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\Service;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface GenericServiceInterface
+{
+    #[Operation]
+    public function operation(string $name): string;
+}
diff --git a/tests/Nexus/Fixtures/Service/GreetingService.php b/tests/Nexus/Fixtures/Service/GreetingService.php
new file mode 100644
index 000000000..c85c72788
--- /dev/null
+++ b/tests/Nexus/Fixtures/Service/GreetingService.php
@@ -0,0 +1,57 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\Service;
+
+use Temporal\Client\WorkflowOptions;
+use Temporal\Nexus\Link;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\WorkflowHandle;
+
+final class GreetingService implements GreetingServiceInterface
+{
+    public const WORKFLOW_ID = 'greeting-workflow';
+
+    /** @var callable(string): string */
+    private $apiClient;
+
+    public function __construct(callable $apiClient)
+    {
+        $this->apiClient = $apiClient;
+    }
+
+    public function sayHello1(string $name): string
+    {
+        return "Hello, {$name}!";
+    }
+
+    public function sayHello2(string $name): WorkflowHandle
+    {
+        $details = Nexus::getStartDetails();
+        if ($details->callbackUrl !== null) {
+            throw new \InvalidArgumentException('This service does not support callbacks');
+        }
+
+        ($this->apiClient)($name);
+
+        if (\str_ends_with($name, 'link')) {
+            Nexus::getCurrentOperationContext()->links->add(
+                new Link('http://somepath?k=v', 'com.example.MyResource'),
+            );
+        }
+
+        return WorkflowHandle::fromWorkflowMethod(
+            FakeGreetingWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(self::WORKFLOW_ID),
+        );
+    }
+
+}
diff --git a/tests/Nexus/Fixtures/Service/GreetingServiceInterface.php b/tests/Nexus/Fixtures/Service/GreetingServiceInterface.php
new file mode 100644
index 000000000..800db54d2
--- /dev/null
+++ b/tests/Nexus/Fixtures/Service/GreetingServiceInterface.php
@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\Service;
+
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\WorkflowHandle;
+
+#[Service]
+interface GreetingServiceInterface
+{
+    #[Operation]
+    public function sayHello1(string $name): string;
+
+    #[AsyncOperation(output: 'string')]
+    public function sayHello2(string $name): WorkflowHandle;
+}
diff --git a/tests/Nexus/Fixtures/Service/IntersectionInputServiceInterface.php b/tests/Nexus/Fixtures/Service/IntersectionInputServiceInterface.php
new file mode 100644
index 000000000..54ba9cf8a
--- /dev/null
+++ b/tests/Nexus/Fixtures/Service/IntersectionInputServiceInterface.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\Service;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface IntersectionInputServiceInterface
+{
+    #[Operation]
+    public function operation(\Countable&\ArrayAccess $input): string;
+}
diff --git a/tests/Nexus/Fixtures/Service/NullableInputServiceInterface.php b/tests/Nexus/Fixtures/Service/NullableInputServiceInterface.php
new file mode 100644
index 000000000..4e7353503
--- /dev/null
+++ b/tests/Nexus/Fixtures/Service/NullableInputServiceInterface.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\Service;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface NullableInputServiceInterface
+{
+    #[Operation]
+    public function operation(?string $input): ?string;
+}
diff --git a/tests/Nexus/Fixtures/Service/ThrowingGreetingService.php b/tests/Nexus/Fixtures/Service/ThrowingGreetingService.php
new file mode 100644
index 000000000..c92fd0fc9
--- /dev/null
+++ b/tests/Nexus/Fixtures/Service/ThrowingGreetingService.php
@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\Service;
+
+use Temporal\Client\WorkflowOptions;
+use Temporal\Nexus\WorkflowHandle;
+
+/**
+ * Greeting-service implementation whose operations either trigger a configured throwable
+ * (for testing exception paths) or return a benign workflow-backed stub.
+ */
+final class ThrowingGreetingService implements GreetingServiceInterface
+{
+    public function __construct(
+        private readonly ?\Throwable $hello1Throw = null,
+        private readonly ?\Throwable $hello2Throw = null,
+    ) {}
+
+    public function sayHello1(string $name): string
+    {
+        if ($this->hello1Throw !== null) {
+            throw $this->hello1Throw;
+        }
+        return 'ok';
+    }
+
+    public function sayHello2(string $name): WorkflowHandle
+    {
+        if ($this->hello2Throw !== null) {
+            throw $this->hello2Throw;
+        }
+        return WorkflowHandle::fromWorkflowMethod(
+            FakeGreetingWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId('throwing-workflow'),
+        );
+    }
+
+}
diff --git a/tests/Nexus/Fixtures/Service/UnionInputServiceInterface.php b/tests/Nexus/Fixtures/Service/UnionInputServiceInterface.php
new file mode 100644
index 000000000..6c137755d
--- /dev/null
+++ b/tests/Nexus/Fixtures/Service/UnionInputServiceInterface.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\Service;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface UnionInputServiceInterface
+{
+    #[Operation]
+    public function operation(string|int $input): string;
+}
diff --git a/tests/Nexus/Fixtures/Service/UnionOutputServiceInterface.php b/tests/Nexus/Fixtures/Service/UnionOutputServiceInterface.php
new file mode 100644
index 000000000..6fdfe688b
--- /dev/null
+++ b/tests/Nexus/Fixtures/Service/UnionOutputServiceInterface.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\Service;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface UnionOutputServiceInterface
+{
+    #[Operation]
+    public function operation(string $input): string|int;
+}
diff --git a/tests/Nexus/Fixtures/Service/UntypedInputServiceInterface.php b/tests/Nexus/Fixtures/Service/UntypedInputServiceInterface.php
new file mode 100644
index 000000000..fd50ffc07
--- /dev/null
+++ b/tests/Nexus/Fixtures/Service/UntypedInputServiceInterface.php
@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\Service;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface UntypedInputServiceInterface
+{
+    /** @param mixed $input */
+    #[Operation]
+    public function operation($input): string;
+}
diff --git a/tests/Nexus/Fixtures/Service/VoidServiceInterface.php b/tests/Nexus/Fixtures/Service/VoidServiceInterface.php
new file mode 100644
index 000000000..772f0c79e
--- /dev/null
+++ b/tests/Nexus/Fixtures/Service/VoidServiceInterface.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\Service;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface VoidServiceInterface
+{
+    #[Operation]
+    public function operation(): void;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/AmbiguousServiceAlpha.php b/tests/Nexus/Fixtures/ServiceDefinition/AmbiguousServiceAlpha.php
new file mode 100644
index 000000000..58388d19d
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/AmbiguousServiceAlpha.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service(name: 'AmbiguousAlpha')]
+interface AmbiguousServiceAlpha
+{
+    #[Operation]
+    public function alpha(): void;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/AmbiguousServiceBeta.php b/tests/Nexus/Fixtures/ServiceDefinition/AmbiguousServiceBeta.php
new file mode 100644
index 000000000..19afbcdc0
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/AmbiguousServiceBeta.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service(name: 'AmbiguousBeta')]
+interface AmbiguousServiceBeta
+{
+    #[Operation]
+    public function beta(): void;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/AmbiguousServiceImpl.php b/tests/Nexus/Fixtures/ServiceDefinition/AmbiguousServiceImpl.php
new file mode 100644
index 000000000..1b5bfb199
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/AmbiguousServiceImpl.php
@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+final class AmbiguousServiceImpl implements AmbiguousServiceAlpha, AmbiguousServiceBeta
+{
+    public function alpha(): void {}
+
+    public function beta(): void {}
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/DiamondCommonInterface.php b/tests/Nexus/Fixtures/ServiceDefinition/DiamondCommonInterface.php
new file mode 100644
index 000000000..209197c27
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/DiamondCommonInterface.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service(name: 'Diamond')]
+interface DiamondCommonInterface
+{
+    #[Operation]
+    public function commonOp(): void;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/DiamondFinalInterface.php b/tests/Nexus/Fixtures/ServiceDefinition/DiamondFinalInterface.php
new file mode 100644
index 000000000..4d0f009e5
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/DiamondFinalInterface.php
@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Service;
+
+#[Service(name: 'Diamond')]
+interface DiamondFinalInterface extends DiamondLeftInterface, DiamondRightInterface
+{
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/DiamondLeftInterface.php b/tests/Nexus/Fixtures/ServiceDefinition/DiamondLeftInterface.php
new file mode 100644
index 000000000..ec2a5fbc5
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/DiamondLeftInterface.php
@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Service;
+
+#[Service(name: 'Diamond')]
+interface DiamondLeftInterface extends DiamondCommonInterface
+{
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/DiamondRightInterface.php b/tests/Nexus/Fixtures/ServiceDefinition/DiamondRightInterface.php
new file mode 100644
index 000000000..a65383a12
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/DiamondRightInterface.php
@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Service;
+
+#[Service(name: 'Diamond')]
+interface DiamondRightInterface extends DiamondCommonInterface
+{
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/EmptyService.php b/tests/Nexus/Fixtures/ServiceDefinition/EmptyService.php
new file mode 100644
index 000000000..80bdfabd0
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/EmptyService.php
@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface EmptyService
+{
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/FactoryWithParametersService.php b/tests/Nexus/Fixtures/ServiceDefinition/FactoryWithParametersService.php
new file mode 100644
index 000000000..78ab3091d
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/FactoryWithParametersService.php
@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+
+#[Service(name: 'factory-with-parameters-service')]
+interface FactoryWithParametersService
+{
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function badFactory(string $input): OperationHandlerInterface;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/InvalidAsyncReturnTypeService.php b/tests/Nexus/Fixtures/ServiceDefinition/InvalidAsyncReturnTypeService.php
new file mode 100644
index 000000000..a46dc586c
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/InvalidAsyncReturnTypeService.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service(name: 'invalid-async-return-type-service')]
+interface InvalidAsyncReturnTypeService
+{
+    #[AsyncOperation]
+    public function badReturn(string $input): string;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/InvalidServiceDuplicateOperation.php b/tests/Nexus/Fixtures/ServiceDefinition/InvalidServiceDuplicateOperation.php
new file mode 100644
index 000000000..a00227cc3
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/InvalidServiceDuplicateOperation.php
@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface InvalidServiceDuplicateOperation
+{
+    #[Operation]
+    public function duplicateWhenNameOverridden1(): void;
+
+    #[Operation(name: 'duplicateWhenNameOverridden1')]
+    public function duplicateWhenNameOverridden2(): void;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/InvalidServiceNoAnnotation.php b/tests/Nexus/Fixtures/ServiceDefinition/InvalidServiceNoAnnotation.php
new file mode 100644
index 000000000..22824e373
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/InvalidServiceNoAnnotation.php
@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+interface InvalidServiceNoAnnotation {}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/InvalidServiceWithOperations.php b/tests/Nexus/Fixtures/ServiceDefinition/InvalidServiceWithOperations.php
new file mode 100644
index 000000000..ddef03c31
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/InvalidServiceWithOperations.php
@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service(name: 'invalid-service-with-operations')]
+interface InvalidServiceWithOperations
+{
+    public function methodWithNoAnnotation(): void;
+
+    #[Operation]
+    public function twoParameterOperation(string $one, string $two): void;
+
+    #[Operation]
+    public static function staticOperation(): void;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/InvalidSubService.php b/tests/Nexus/Fixtures/ServiceDefinition/InvalidSubService.php
new file mode 100644
index 000000000..d40ffdd74
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/InvalidSubService.php
@@ -0,0 +1,17 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface InvalidSubService extends InvalidSuperService {}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/InvalidSuperService.php b/tests/Nexus/Fixtures/ServiceDefinition/InvalidSuperService.php
new file mode 100644
index 000000000..6f73fbd4c
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/InvalidSuperService.php
@@ -0,0 +1,17 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface InvalidSuperService {}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/NonPublicOperationService.php b/tests/Nexus/Fixtures/ServiceDefinition/NonPublicOperationService.php
new file mode 100644
index 000000000..db45aa866
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/NonPublicOperationService.php
@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+class NonPublicOperationService
+{
+    #[Operation]
+    protected function hiddenOperation(string $input): string
+    {
+        return $input;
+    }
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/NullableAsyncReturnTypeService.php b/tests/Nexus/Fixtures/ServiceDefinition/NullableAsyncReturnTypeService.php
new file mode 100644
index 000000000..66761f837
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/NullableAsyncReturnTypeService.php
@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\WorkflowHandle;
+
+#[Service(name: 'nullable-async-return-type-service')]
+interface NullableAsyncReturnTypeService
+{
+    #[AsyncOperation]
+    public function badNullableReturn(string $input): ?WorkflowHandle;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/OperationOverrideMismatchService.php b/tests/Nexus/Fixtures/ServiceDefinition/OperationOverrideMismatchService.php
new file mode 100644
index 000000000..556718a52
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/OperationOverrideMismatchService.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service(name: 'OperationOverrideMismatch')]
+interface OperationOverrideMismatchService extends ParentWithDifferentOperationName
+{
+    #[Operation(name: 'child-name')]
+    public function sharedMethod(): void;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/ParentWithDifferentOperationName.php b/tests/Nexus/Fixtures/ServiceDefinition/ParentWithDifferentOperationName.php
new file mode 100644
index 000000000..91ea1194f
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/ParentWithDifferentOperationName.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service(name: 'OperationOverrideMismatch')]
+interface ParentWithDifferentOperationName
+{
+    #[Operation(name: 'parent-name')]
+    public function sharedMethod(): void;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/PlainParentInterface.php b/tests/Nexus/Fixtures/ServiceDefinition/PlainParentInterface.php
new file mode 100644
index 000000000..f318c1f77
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/PlainParentInterface.php
@@ -0,0 +1,20 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Operation;
+
+interface PlainParentInterface
+{
+    #[Operation]
+    public function inheritedOperation(): void;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/ServiceWithPlainParentInterface.php b/tests/Nexus/Fixtures/ServiceDefinition/ServiceWithPlainParentInterface.php
new file mode 100644
index 000000000..c96fa2aea
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/ServiceWithPlainParentInterface.php
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface ServiceWithPlainParentInterface extends PlainParentInterface
+{
+    #[Operation]
+    public function ownOperation(): void;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/ValidServiceWithOperations.php b/tests/Nexus/Fixtures/ServiceDefinition/ValidServiceWithOperations.php
new file mode 100644
index 000000000..d359e519f
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/ValidServiceWithOperations.php
@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service]
+interface ValidServiceWithOperations extends ValidSuperServiceWithOperations
+{
+    #[Operation]
+    public function superMethod(): void;
+
+    #[Operation]
+    public function noParamNoReturn(): void;
+
+    #[Operation]
+    public function noParamSingleReturn(): string;
+
+    #[Operation]
+    public function singleParamNoReturn(string $param): void;
+
+    #[Operation]
+    public function singleParamSingleReturn(string $param): string;
+
+    #[Operation(name: 'custom-name')]
+    public function customName(): void;
+}
diff --git a/tests/Nexus/Fixtures/ServiceDefinition/ValidSuperServiceWithOperations.php b/tests/Nexus/Fixtures/ServiceDefinition/ValidSuperServiceWithOperations.php
new file mode 100644
index 000000000..22b36f461
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceDefinition/ValidSuperServiceWithOperations.php
@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceDefinition;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service(name: 'ValidServiceWithOperations')]
+interface ValidSuperServiceWithOperations
+{
+    #[Operation]
+    public function superMethod(): void;
+
+    #[Operation]
+    public function superInterfaceOnly(): void;
+}
diff --git a/tests/Nexus/Fixtures/ServiceHandler/AuthInterceptor.php b/tests/Nexus/Fixtures/ServiceHandler/AuthInterceptor.php
new file mode 100644
index 000000000..81f6b6f44
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceHandler/AuthInterceptor.php
@@ -0,0 +1,51 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceHandler;
+
+use Temporal\Interceptor\NexusOperationInbound\CancelOperationInput;
+use Temporal\Interceptor\NexusOperationInbound\StartOperationInput;
+use Temporal\Interceptor\NexusOperationInboundCallsInterceptor;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Handler\OperationStartResult;
+
+/**
+ * Rejects operations missing the expected auth token. Short-circuits before
+ * the underlying handler is invoked.
+ */
+final class AuthInterceptor implements NexusOperationInboundCallsInterceptor
+{
+    public const AUTH_HEADER = 'authorization';
+
+    public function __construct(
+        private readonly string $authToken,
+    ) {}
+
+    public function startOperation(StartOperationInput $input, callable $next): OperationStartResult
+    {
+        $this->assertAuthorized($input->operationContext->headers->get(self::AUTH_HEADER));
+        return $next($input);
+    }
+
+    public function cancelOperation(CancelOperationInput $input, callable $next): void
+    {
+        $this->assertAuthorized($input->operationContext->headers->get(self::AUTH_HEADER));
+        $next($input);
+    }
+
+    private function assertAuthorized(?string $token): void
+    {
+        if ($token !== $this->authToken) {
+            throw HandlerException::create(ErrorType::Unauthorized, 'Unauthorized');
+        }
+    }
+}
diff --git a/tests/Nexus/Fixtures/ServiceHandler/ExternalJobHandler.php b/tests/Nexus/Fixtures/ServiceHandler/ExternalJobHandler.php
new file mode 100644
index 000000000..ae256d38a
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceHandler/ExternalJobHandler.php
@@ -0,0 +1,40 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceHandler;
+
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+
+final class ExternalJobHandler implements OperationHandlerInterface
+{
+    public ?string $cancelledToken = null;
+
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        return OperationStartResult::async(new OperationInfo('ext-' . $param, OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {
+        $this->cancelledToken = $details->operationToken;
+    }
+}
diff --git a/tests/Nexus/Fixtures/ServiceHandler/FinishedJobHandler.php b/tests/Nexus/Fixtures/ServiceHandler/FinishedJobHandler.php
new file mode 100644
index 000000000..5d915f3f7
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceHandler/FinishedJobHandler.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceHandler;
+
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+
+final class FinishedJobHandler implements OperationHandlerInterface
+{
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        return OperationStartResult::async(new OperationInfo('ext-done-' . $param, OperationState::Succeeded));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {}
+}
diff --git a/tests/Nexus/Fixtures/ServiceHandler/LoggingInterceptor.php b/tests/Nexus/Fixtures/ServiceHandler/LoggingInterceptor.php
new file mode 100644
index 000000000..81b163ea0
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceHandler/LoggingInterceptor.php
@@ -0,0 +1,46 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceHandler;
+
+use Temporal\Interceptor\NexusOperationInbound\CancelOperationInput;
+use Temporal\Interceptor\NexusOperationInbound\StartOperationInput;
+use Temporal\Interceptor\NexusOperationInboundCallsInterceptor;
+use Temporal\Nexus\Handler\OperationStartResult;
+
+/**
+ * Test interceptor that records each operation it sees.
+ */
+final class LoggingInterceptor implements NexusOperationInboundCallsInterceptor
+{
+    /** @var list<string> */
+    private array $operations = [];
+
+    /**
+     * @return list<string>
+     */
+    public function getOperations(): array
+    {
+        return $this->operations;
+    }
+
+    public function startOperation(StartOperationInput $input, callable $next): OperationStartResult
+    {
+        $this->operations[] = $input->operationContext->operation;
+        return $next($input);
+    }
+
+    public function cancelOperation(CancelOperationInput $input, callable $next): void
+    {
+        $this->operations[] = $input->operationContext->operation;
+        $next($input);
+    }
+}
diff --git a/tests/Nexus/Fixtures/ServiceHandler/ManualTokenService.php b/tests/Nexus/Fixtures/ServiceHandler/ManualTokenService.php
new file mode 100644
index 000000000..bcf3aa0ce
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceHandler/ManualTokenService.php
@@ -0,0 +1,44 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceHandler;
+
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+
+#[Service(name: 'ManualTokenService')]
+final class ManualTokenService
+{
+    public readonly ExternalJobHandler $externalJobHandler;
+
+    public function __construct()
+    {
+        $this->externalJobHandler = new ExternalJobHandler();
+    }
+
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function startExternal(): ExternalJobHandler
+    {
+        return $this->externalJobHandler;
+    }
+
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function startUncancellable(): UncancellableJobHandler
+    {
+        return new UncancellableJobHandler();
+    }
+
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function startAlreadyFinished(): FinishedJobHandler
+    {
+        return new FinishedJobHandler();
+    }
+}
diff --git a/tests/Nexus/Fixtures/ServiceHandler/UncancellableJobHandler.php b/tests/Nexus/Fixtures/ServiceHandler/UncancellableJobHandler.php
new file mode 100644
index 000000000..87955696a
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceHandler/UncancellableJobHandler.php
@@ -0,0 +1,40 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceHandler;
+
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+
+final class UncancellableJobHandler implements OperationHandlerInterface
+{
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        return OperationStartResult::async(new OperationInfo('ext-fixed-' . $param, OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {
+        throw HandlerException::create(ErrorType::NotImplemented, 'manual operation does not support cancellation');
+    }
+}
diff --git a/tests/Nexus/Fixtures/ServiceHandler/VoidService.php b/tests/Nexus/Fixtures/ServiceHandler/VoidService.php
new file mode 100644
index 000000000..81c589a3d
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceHandler/VoidService.php
@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceHandler;
+
+use Temporal\Tests\Nexus\Fixtures\Service\VoidServiceInterface;
+
+final class VoidService implements VoidServiceInterface
+{
+    public function operation(): void {}
+}
diff --git a/tests/Nexus/Fixtures/ServiceImplInstance/ChildInheritingHandler.php b/tests/Nexus/Fixtures/ServiceImplInstance/ChildInheritingHandler.php
new file mode 100644
index 000000000..0fd743737
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceImplInstance/ChildInheritingHandler.php
@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceImplInstance;
+
+final class ChildInheritingHandler extends ParentWithHandler {}
diff --git a/tests/Nexus/Fixtures/ServiceImplInstance/NoServiceAnnotation.php b/tests/Nexus/Fixtures/ServiceImplInstance/NoServiceAnnotation.php
new file mode 100644
index 000000000..ddbd1e9a9
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceImplInstance/NoServiceAnnotation.php
@@ -0,0 +1,24 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceImplInstance;
+
+/**
+ * Class that does not implement any #[Service]-annotated interface, so the
+ * factory cannot derive a contract.
+ */
+final class NoServiceAnnotation
+{
+    public function operation(): string
+    {
+        return '';
+    }
+}
diff --git a/tests/Nexus/Fixtures/ServiceImplInstance/ParentWithHandler.php b/tests/Nexus/Fixtures/ServiceImplInstance/ParentWithHandler.php
new file mode 100644
index 000000000..2fd842efb
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceImplInstance/ParentWithHandler.php
@@ -0,0 +1,26 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceImplInstance;
+
+use Temporal\Tests\Nexus\Fixtures\Service\GenericServiceInterface;
+
+/**
+ * Parent declares the operation method; subclass inherits without redeclaring it.
+ * Exercises the inheritance traversal in {@see \Temporal\Internal\Declaration\Instantiator\NexusServiceInstantiator}.
+ */
+class ParentWithHandler implements GenericServiceInterface
+{
+    public function operation(string $name): string
+    {
+        return 'parent';
+    }
+}
diff --git a/tests/Nexus/Fixtures/ServiceImplInstance/ServiceAsClass.php b/tests/Nexus/Fixtures/ServiceImplInstance/ServiceAsClass.php
new file mode 100644
index 000000000..01b260f85
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceImplInstance/ServiceAsClass.php
@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceImplInstance;
+
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+
+/**
+ * Service implementation that carries `#[Service]` directly on the class — no separate
+ * contract interface is required.
+ */
+#[Service]
+final class ServiceAsClass
+{
+    #[Operation]
+    public function classOperation(string $input): string
+    {
+        return $input;
+    }
+}
diff --git a/tests/Nexus/Fixtures/ServiceImplInstance/ServiceWithExtraNonOperationMethod.php b/tests/Nexus/Fixtures/ServiceImplInstance/ServiceWithExtraNonOperationMethod.php
new file mode 100644
index 000000000..7cd6a2cd9
--- /dev/null
+++ b/tests/Nexus/Fixtures/ServiceImplInstance/ServiceWithExtraNonOperationMethod.php
@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Fixtures\ServiceImplInstance;
+
+use Temporal\Tests\Nexus\Fixtures\Service\VoidServiceInterface;
+
+/**
+ * Implementation with a non-operation helper method — the factory should ignore it.
+ */
+final class ServiceWithExtraNonOperationMethod implements VoidServiceInterface
+{
+    public function operation(): void {}
+
+    public function plainHelper(): int
+    {
+        return 42;
+    }
+}
diff --git a/tests/Nexus/Support/BindNexusService.php b/tests/Nexus/Support/BindNexusService.php
new file mode 100644
index 000000000..88d73d37e
--- /dev/null
+++ b/tests/Nexus/Support/BindNexusService.php
@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Support;
+
+use Spiral\Attributes\AttributeReader;
+use Temporal\Internal\Declaration\Instantiator\NexusServiceInstantiator;
+use Temporal\Internal\Declaration\NexusServiceInstance;
+use Temporal\Internal\Declaration\Reader\NexusServiceReader;
+
+/**
+ * Test helper: wires Reader + Instantiator the same way Worker does, returning
+ * a {@see NexusServiceInstance} bound to the given impl object.
+ */
+trait BindNexusService
+{
+    protected static function bindNexusService(object $instance): NexusServiceInstance
+    {
+        $reader = new NexusServiceReader(new AttributeReader());
+        $prototype = $reader->fromClass(\get_class($instance))->withInstance($instance);
+        return (new NexusServiceInstantiator())->instantiate($prototype);
+    }
+}
diff --git a/tests/Nexus/Support/EncodesValues.php b/tests/Nexus/Support/EncodesValues.php
new file mode 100644
index 000000000..e1c67f62b
--- /dev/null
+++ b/tests/Nexus/Support/EncodesValues.php
@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Support;
+
+use Temporal\DataConverter\DataConverter;
+use Temporal\DataConverter\DataConverterInterface;
+use Temporal\DataConverter\EncodedValues;
+
+trait EncodesValues
+{
+    protected static function dataConverter(): DataConverterInterface
+    {
+        return DataConverter::createDefault();
+    }
+
+    protected static function encode(mixed $value): EncodedValues
+    {
+        return EncodedValues::fromValues([$value], self::dataConverter());
+    }
+}
diff --git a/tests/Nexus/Support/ExceptionAssertions.php b/tests/Nexus/Support/ExceptionAssertions.php
new file mode 100644
index 000000000..7771823d3
--- /dev/null
+++ b/tests/Nexus/Support/ExceptionAssertions.php
@@ -0,0 +1,41 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Support;
+
+use PHPUnit\Framework\Assert;
+
+/**
+ * Captures an exception thrown by the given callable and returns it for
+ * further assertions. Use in tests that need to interrogate fields on the
+ * thrown exception; for pure type/message checks prefer `expectException*`.
+ *
+ * Supersedes the `try { ...; self::fail(); } catch (...) { ... }` pattern.
+ */
+trait ExceptionAssertions
+{
+    /**
+     * @template T of \Throwable
+     * @param class-string<T> $expected
+     * @return T
+     */
+    protected static function assertThrown(string $expected, callable $action): \Throwable
+    {
+        try {
+            $action();
+        } catch (\Throwable $e) {
+            Assert::assertInstanceOf($expected, $e);
+            return $e;
+        }
+
+        Assert::fail("Expected {$expected} but nothing was thrown");
+    }
+}
diff --git a/tests/Nexus/Support/MocksAsyncWorkflowClient.php b/tests/Nexus/Support/MocksAsyncWorkflowClient.php
new file mode 100644
index 000000000..7bb80ec18
--- /dev/null
+++ b/tests/Nexus/Support/MocksAsyncWorkflowClient.php
@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Support;
+
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Tests\Nexus\Fixtures\Service\GreetingService;
+use Temporal\Workflow\WorkflowExecution;
+use Temporal\Workflow\WorkflowRunInterface;
+
+trait MocksAsyncWorkflowClient
+{
+    protected function asyncClient(): WorkflowClientInterface
+    {
+        $client = $this->createMock(WorkflowClientInterface::class);
+        $client->method('newWorkflowStub')->willReturn($this->createMock(WorkflowStubInterface::class));
+        $client->method('newUntypedRunningWorkflowStub')->willReturn($this->createMock(WorkflowStubInterface::class));
+
+        $run = $this->createMock(WorkflowRunInterface::class);
+        $run->method('getExecution')->willReturn(new WorkflowExecution(GreetingService::WORKFLOW_ID, 'run-1'));
+        $client->method('start')->willReturn($run);
+
+        return $client;
+    }
+}
diff --git a/tests/Nexus/Unit/Exception/ErrorTypeTest.php b/tests/Nexus/Unit/Exception/ErrorTypeTest.php
new file mode 100644
index 000000000..c97fd1e63
--- /dev/null
+++ b/tests/Nexus/Unit/Exception/ErrorTypeTest.php
@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Exception;
+
+use Temporal\Nexus\Exception\ErrorType;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ErrorType::class)]
+final class ErrorTypeTest extends TestCase
+{
+    /**
+     * Spec-mandated wire values per SPEC.md "Predefined Handler Errors".
+     */
+    public function testWireValuesMatchSpec(): void
+    {
+        self::assertSame('BAD_REQUEST',        ErrorType::BadRequest->value);
+        self::assertSame('UNAUTHENTICATED',    ErrorType::Unauthenticated->value);
+        self::assertSame('UNAUTHORIZED',       ErrorType::Unauthorized->value);
+        self::assertSame('NOT_FOUND',          ErrorType::NotFound->value);
+        self::assertSame('REQUEST_TIMEOUT',    ErrorType::RequestTimeout->value);
+        self::assertSame('CONFLICT',           ErrorType::Conflict->value);
+        self::assertSame('RESOURCE_EXHAUSTED', ErrorType::ResourceExhausted->value);
+        self::assertSame('INTERNAL',           ErrorType::Internal->value);
+        self::assertSame('NOT_IMPLEMENTED',    ErrorType::NotImplemented->value);
+        self::assertSame('UNAVAILABLE',        ErrorType::Unavailable->value);
+        self::assertSame('UPSTREAM_TIMEOUT',   ErrorType::UpstreamTimeout->value);
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/CancelOperationTest.php b/tests/Nexus/Unit/Handler/CancelOperationTest.php
new file mode 100644
index 000000000..825ab9457
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/CancelOperationTest.php
@@ -0,0 +1,143 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\NexusOperationContext;
+
+use Temporal\DataConverter\EncodedValues;
+use Temporal\Interceptor\SimplePipelineProvider;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\Internal\ServiceHandler;
+use Temporal\Tests\Nexus\Fixtures\Service\GreetingService;
+use Temporal\Tests\Nexus\Fixtures\ServiceHandler\AuthInterceptor;
+use Temporal\Tests\Nexus\Fixtures\ServiceHandler\LoggingInterceptor;
+use Temporal\Tests\Nexus\Fixtures\ServiceHandler\VoidService;
+use Temporal\Tests\Nexus\Support\BindNexusService;
+use Temporal\Tests\Nexus\Support\EncodesValues;
+use Temporal\Tests\Nexus\Support\ExceptionAssertions;
+use Temporal\Tests\Nexus\Support\MocksAsyncWorkflowClient;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ServiceHandler::class)]
+final class CancelOperationTest extends TestCase
+{
+    use BindNexusService;
+    use EncodesValues;
+    use ExceptionAssertions;
+    use MocksAsyncWorkflowClient;
+
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    public function testCancelUnrecognizedService(): void
+    {
+        $handler = ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [
+                self::bindNexusService(new VoidService()),
+            ],
+        );
+
+        $e = self::assertThrown(HandlerException::class, fn() => $handler->cancelOperation(
+            new OperationContext(service: 'NonExistent', operation: 'op', env: $this->env),
+            new OperationCancelDetails(operationToken: 'token'),
+            null,
+            new NexusOperationContext(),
+        ));
+
+        self::assertSame(ErrorType::NotFound, $e->errorType);
+        self::assertStringContainsString("Unrecognized service 'NonExistent'", $e->getMessage());
+    }
+
+    public function testCancelUnrecognizedOperation(): void
+    {
+        $handler = ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [
+                self::bindNexusService(new VoidService()),
+            ],
+        );
+
+        $e = self::assertThrown(HandlerException::class, fn() => $handler->cancelOperation(
+            new OperationContext(service: 'VoidServiceInterface', operation: 'nonExistent', env: $this->env),
+            new OperationCancelDetails(operationToken: 'token'),
+            null,
+            new NexusOperationContext(),
+        ));
+
+        self::assertSame(ErrorType::NotFound, $e->errorType);
+        self::assertStringContainsString("has no operation 'nonExistent'", $e->getMessage());
+    }
+
+    public function testCancelWithInterceptor(): void
+    {
+        $apiClient = static fn(string $name): string => "greeting-{$name}";
+        $authToken = 'auth-token';
+        $loggingInterceptor = new LoggingInterceptor();
+
+        $handler = ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [
+                self::bindNexusService(new GreetingService($apiClient)),
+            ],
+            interceptorProvider: new SimplePipelineProvider([
+                new AuthInterceptor($authToken),
+                $loggingInterceptor,
+            ]),
+        );
+
+        // Start an async operation first.
+        $result = $handler->startOperation(
+            new OperationContext(
+                service: 'GreetingServiceInterface',
+                operation: 'sayHello2',
+                env: $this->env,
+                headers: [AuthInterceptor::AUTH_HEADER => $authToken],
+            ),
+            new OperationStartDetails(requestId: 'r1'),
+            EncodedValues::fromValues(['SomeUser'], self::dataConverter()),
+            $this->asyncClient(),
+            new NexusOperationContext('test-ns', 'test-tq'),
+        );
+
+        $token = $result->info->token;
+        self::assertNotNull($token);
+
+        // Cancel it.
+        $handler->cancelOperation(
+            new OperationContext(
+                service: 'GreetingServiceInterface',
+                operation: 'sayHello2',
+                env: $this->env,
+                headers: [AuthInterceptor::AUTH_HEADER => $authToken],
+            ),
+            new OperationCancelDetails(operationToken: $token),
+            $this->asyncClient(),
+            new NexusOperationContext('test-ns', 'test-tq'),
+        );
+
+        // Logging interceptor saw both start and cancel.
+        self::assertSame(['sayHello2', 'sayHello2'], $loggingInterceptor->getOperations());
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/ClosureMethodCancellationListenerTest.php b/tests/Nexus/Unit/Handler/ClosureMethodCancellationListenerTest.php
new file mode 100644
index 000000000..0e68de97f
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/ClosureMethodCancellationListenerTest.php
@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\Handler\ClosureMethodCancellationListener;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ClosureMethodCancellationListener::class)]
+final class ClosureMethodCancellationListenerTest extends TestCase
+{
+    public function testCancelledInvokesWrappedCallable(): void
+    {
+        $calls = 0;
+        $listener = ClosureMethodCancellationListener::fromCallable(static function () use (&$calls): void {
+            $calls++;
+        });
+
+        $listener->cancelled();
+        $listener->cancelled();
+
+        self::assertSame(2, $calls);
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/HandlerExceptionTest.php b/tests/Nexus/Unit/Handler/HandlerExceptionTest.php
new file mode 100644
index 000000000..2c8870f94
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/HandlerExceptionTest.php
@@ -0,0 +1,149 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\NexusException;
+use Temporal\Nexus\Exception\RetryBehavior;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(HandlerException::class)]
+final class HandlerExceptionTest extends TestCase
+{
+    public function testCreateWithMessage(): void
+    {
+        $ex = HandlerException::create(ErrorType::BadRequest, 'Invalid input');
+
+        self::assertSame('Invalid input', $ex->getMessage());
+        self::assertSame(ErrorType::BadRequest, $ex->errorType);
+        self::assertSame('BAD_REQUEST', $ex->errorType->value);
+        self::assertNull($ex->getPrevious());
+        self::assertSame(RetryBehavior::Unspecified, $ex->retryBehavior);
+    }
+
+    public function testCreateWithCause(): void
+    {
+        $cause = new \RuntimeException('Root cause');
+        $ex = HandlerException::create(ErrorType::Internal, 'Handler error', $cause);
+
+        self::assertSame('Handler error', $ex->getMessage());
+        self::assertSame($cause, $ex->getPrevious());
+        self::assertSame(ErrorType::Internal, $ex->errorType);
+    }
+
+    public function testCreateWithRetryBehavior(): void
+    {
+        $ex = HandlerException::create(
+            ErrorType::Internal,
+            'Server error',
+            retryBehavior: RetryBehavior::NonRetryable,
+        );
+
+        self::assertSame(RetryBehavior::NonRetryable, $ex->retryBehavior);
+        self::assertFalse($ex->isRetryable());
+    }
+
+    public function testFromCauseBuildsMessage(): void
+    {
+        $ex = HandlerException::fromCause(ErrorType::Internal, new \RuntimeException('boom'));
+
+        self::assertSame('handler error: boom', $ex->getMessage());
+        self::assertSame(ErrorType::Internal, $ex->errorType);
+        self::assertInstanceOf(\RuntimeException::class, $ex->getPrevious());
+        self::assertSame('boom', $ex->getPrevious()->getMessage());
+    }
+
+    public function testFromCauseWithEmptyMessageDefaultsToHandlerError(): void
+    {
+        $ex = HandlerException::fromCause(ErrorType::Internal, new \RuntimeException(''));
+
+        self::assertSame('handler error', $ex->getMessage());
+    }
+
+    public function testFromCauseWithRetryBehavior(): void
+    {
+        $cause = new \RuntimeException('Cause');
+        $ex = HandlerException::fromCause(
+            ErrorType::BadRequest,
+            $cause,
+            RetryBehavior::Retryable,
+        );
+
+        self::assertSame($cause, $ex->getPrevious());
+        self::assertSame(RetryBehavior::Retryable, $ex->retryBehavior);
+        self::assertTrue($ex->isRetryable());
+    }
+
+    public function testIsRetryableFromErrorType(): void
+    {
+        $retryable = [
+            ErrorType::RequestTimeout,
+            ErrorType::ResourceExhausted,
+            ErrorType::Internal,
+            ErrorType::Unavailable,
+            ErrorType::UpstreamTimeout,
+            ErrorType::Unknown,
+        ];
+        foreach ($retryable as $type) {
+            $ex = HandlerException::create($type, 'x');
+            self::assertTrue($ex->isRetryable(), "{$type->value} should be retryable");
+        }
+
+        $nonRetryable = [
+            ErrorType::BadRequest,
+            ErrorType::Unauthenticated,
+            ErrorType::Unauthorized,
+            ErrorType::NotFound,
+            ErrorType::Conflict,
+            ErrorType::NotImplemented,
+        ];
+        foreach ($nonRetryable as $type) {
+            $ex = HandlerException::create($type, 'x');
+            self::assertFalse($ex->isRetryable(), "{$type->value} should be non-retryable");
+        }
+
+        // Completeness guard — new ErrorType cases must be classified above.
+        $covered = \count($retryable) + \count($nonRetryable);
+        self::assertSame(\count(ErrorType::cases()), $covered);
+    }
+
+    public function testIsRetryableOverriddenByRetryable(): void
+    {
+        // BAD_REQUEST is non-retryable by default, but explicit Retryable flips it.
+        $ex = HandlerException::create(
+            ErrorType::BadRequest,
+            'x',
+            retryBehavior: RetryBehavior::Retryable,
+        );
+        self::assertTrue($ex->isRetryable());
+    }
+
+    public function testIsRetryableOverriddenByNonRetryable(): void
+    {
+        // INTERNAL is retryable by default, but explicit NonRetryable flips it.
+        $ex = HandlerException::create(
+            ErrorType::Internal,
+            'x',
+            retryBehavior: RetryBehavior::NonRetryable,
+        );
+        self::assertFalse($ex->isRetryable());
+    }
+
+    public function testIsInstanceOfNexusException(): void
+    {
+        $ex = HandlerException::create(ErrorType::Internal, 'x');
+        self::assertInstanceOf(NexusException::class, $ex);
+        self::assertInstanceOf(\RuntimeException::class, $ex);
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/HeaderCollectionTest.php b/tests/Nexus/Unit/Handler/HeaderCollectionTest.php
new file mode 100644
index 000000000..cc829d0ad
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/HeaderCollectionTest.php
@@ -0,0 +1,62 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\Handler\HeaderCollection;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(HeaderCollection::class)]
+final class HeaderCollectionTest extends TestCase
+{
+    public function testGetIsCaseInsensitive(): void
+    {
+        $headers = new HeaderCollection(['Content-Type' => 'text/plain']);
+
+        self::assertSame('text/plain', $headers->get('content-type'));
+        self::assertSame('text/plain', $headers->get('Content-Type'));
+        self::assertSame('text/plain', $headers->get('CONTENT-TYPE'));
+    }
+
+    public function testGetReturnsNullForUnknownHeader(): void
+    {
+        $headers = new HeaderCollection(['x-known' => 'v']);
+
+        self::assertNull($headers->get('x-unknown'));
+    }
+
+    public function testHasIsCaseInsensitive(): void
+    {
+        $headers = new HeaderCollection(['X-Trace-Id' => 'abc']);
+
+        self::assertTrue($headers->has('x-trace-id'));
+        self::assertTrue($headers->has('X-Trace-Id'));
+        self::assertTrue($headers->has('X-TRACE-ID'));
+        self::assertFalse($headers->has('x-other'));
+    }
+
+    public function testAllReturnsNormalizedMap(): void
+    {
+        $headers = new HeaderCollection(['UPPER' => 'A', 'lower' => 'b']);
+
+        self::assertSame(['upper' => 'A', 'lower' => 'b'], $headers->all());
+    }
+
+    public function testEmptyCollection(): void
+    {
+        $headers = new HeaderCollection();
+
+        self::assertSame([], $headers->all());
+        self::assertFalse($headers->has('anything'));
+        self::assertNull($headers->get('anything'));
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/LinkCollectionTest.php b/tests/Nexus/Unit/Handler/LinkCollectionTest.php
new file mode 100644
index 000000000..1bbcadaae
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/LinkCollectionTest.php
@@ -0,0 +1,66 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Handler\LinkCollection;
+use Temporal\Nexus\Link;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(LinkCollection::class)]
+final class LinkCollectionTest extends TestCase
+{
+    public function testRejectsNonLinkInInitial(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('initial[1] must be');
+        /** @phpstan-ignore-next-line — intentionally wrong type */
+        new LinkCollection([new Link('a', 't'), 'not-a-link']);
+    }
+
+    public function testRejectsNonLinkInInitialWithStringKey(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("initial['k']");
+        /** @phpstan-ignore-next-line — intentionally wrong type */
+        new LinkCollection(['k' => 'nope']);
+    }
+
+
+    public function testEmptyByDefault(): void
+    {
+        $c = new LinkCollection();
+
+        self::assertSame([], $c->all());
+    }
+
+    public function testSeedListIsCopied(): void
+    {
+        $seed = [new Link('u', 't')];
+        $c = new LinkCollection($seed);
+
+        $seed[] = new Link('u2', 't2');
+
+        self::assertCount(1, $c->all());
+    }
+
+    public function testAddAppendsInOrder(): void
+    {
+        $c = new LinkCollection();
+        $c->add(new Link('a', 'x'));
+        $c->add(new Link('b', 'y'), new Link('c', 'z'));
+
+        $uris = \array_map(static fn(Link $l) => $l->uri, $c->all());
+        self::assertSame(['a', 'b', 'c'], $uris);
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/ManualTokenOperationTest.php b/tests/Nexus/Unit/Handler/ManualTokenOperationTest.php
new file mode 100644
index 000000000..42c699dab
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/ManualTokenOperationTest.php
@@ -0,0 +1,112 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Handler\Internal\ServiceHandler;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\NexusOperationContext;
+use Temporal\Tests\Nexus\Fixtures\ServiceHandler\ManualTokenService;
+use Temporal\Tests\Nexus\Support\BindNexusService;
+use Temporal\Tests\Nexus\Support\EncodesValues;
+use Temporal\Tests\Nexus\Support\ExceptionAssertions;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+
+#[CoversClass(ServiceHandler::class)]
+final class ManualTokenOperationTest extends TestCase
+{
+    use BindNexusService;
+    use EncodesValues;
+    use ExceptionAssertions;
+
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    public function testStartReturnsManualTokenWithoutWorkflowClient(): void
+    {
+        $result = $this->handler()->startOperation(
+            $this->context('startExternal'),
+            new OperationStartDetails(requestId: 'r1'),
+            self::encode('job-42'),
+            null,
+            new NexusOperationContext(),
+        );
+
+        self::assertSame('ext-job-42', $result->info->token);
+    }
+
+    public function testCancelRoutesToHandlerCancelMethod(): void
+    {
+        $service = new ManualTokenService();
+        $handler = $this->handler($service);
+
+        $handler->cancelOperation(
+            $this->context('startExternal'),
+            new OperationCancelDetails(operationToken: 'ext-job-42'),
+            null,
+            new NexusOperationContext(),
+        );
+
+        self::assertSame('ext-job-42', $service->externalJobHandler->cancelledToken);
+    }
+
+    public function testCancelThrowingNotImplementedSurfacesErrorType(): void
+    {
+        $e = self::assertThrown(HandlerException::class, fn() => $this->handler()->cancelOperation(
+            $this->context('startUncancellable'),
+            new OperationCancelDetails(operationToken: 'ext-fixed-1'),
+            null,
+            new NexusOperationContext(),
+        ));
+
+        self::assertSame(ErrorType::NotImplemented, $e->errorType);
+    }
+
+    public function testStartRejectsNonRunningOperationInfo(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('must report a running operation');
+
+        $this->handler()->startOperation(
+            $this->context('startAlreadyFinished'),
+            new OperationStartDetails(requestId: 'r2'),
+            self::encode('job-43'),
+            null,
+            new NexusOperationContext(),
+        );
+    }
+
+    private function handler(?ManualTokenService $service = null): ServiceHandler
+    {
+        return ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [self::bindNexusService($service ?? new ManualTokenService())],
+        );
+    }
+
+    private function context(string $operation): OperationContext
+    {
+        return new OperationContext(service: 'ManualTokenService', operation: $operation, env: $this->env);
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/MethodCancellerTest.php b/tests/Nexus/Unit/Handler/MethodCancellerTest.php
new file mode 100644
index 000000000..59f11c376
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/MethodCancellerTest.php
@@ -0,0 +1,228 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\Handler\ClosureMethodCancellationListener;
+use Temporal\Nexus\Handler\MethodCanceller;
+use Temporal\Nexus\Handler\MethodCancellationListenerInterface;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+use Temporal\Worker\Transport\Command\Server\TickInfo;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(MethodCanceller::class)]
+final class MethodCancellerTest extends TestCase
+{
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    public function testNotCancelledByDefault(): void
+    {
+        $canceller = new MethodCanceller($this->env);
+
+        self::assertFalse($canceller->isCancelled());
+        self::assertNull($canceller->getReason());
+    }
+
+    public function testCancelSetsReason(): void
+    {
+        $canceller = new MethodCanceller($this->env);
+        $canceller->cancel('deadline exceeded');
+
+        self::assertTrue($canceller->isCancelled());
+        self::assertSame('deadline exceeded', $canceller->getReason());
+    }
+
+    public function testCancelIsIdempotent(): void
+    {
+        $canceller = new MethodCanceller($this->env);
+        $canceller->cancel('first');
+        $canceller->cancel('second');
+
+        self::assertSame('first', $canceller->getReason(), 'second cancel must be a no-op');
+    }
+
+    public function testListenerInvokedOnCancel(): void
+    {
+        $canceller = new MethodCanceller($this->env);
+        $hits = 0;
+        $canceller->addListener(ClosureMethodCancellationListener::fromCallable(
+            static function () use (&$hits): void {
+                $hits++;
+            },
+        ));
+
+        $canceller->cancel('shutdown');
+
+        self::assertSame(1, $hits);
+        // Listeners must read the reason from the canceller if they need it.
+        self::assertSame('shutdown', $canceller->getReason());
+    }
+
+    public function testListenerInvokedOnlyOnceAcrossDuplicateCancels(): void
+    {
+        $canceller = new MethodCanceller($this->env);
+        $count = 0;
+        $canceller->addListener(ClosureMethodCancellationListener::fromCallable(
+            static function () use (&$count): void {
+                $count++;
+            },
+        ));
+
+        $canceller->cancel('first');
+        $canceller->cancel('second');
+
+        self::assertSame(1, $count);
+    }
+
+    public function testListenerAddedAfterCancelInvokedImmediately(): void
+    {
+        $canceller = new MethodCanceller($this->env);
+        $canceller->cancel('gone');
+
+        $fired = false;
+        $canceller->addListener(ClosureMethodCancellationListener::fromCallable(
+            static function () use (&$fired): void {
+                $fired = true;
+            },
+        ));
+
+        self::assertTrue($fired);
+    }
+
+    public function testRemovedListenerNotInvoked(): void
+    {
+        $canceller = new MethodCanceller($this->env);
+        $invoked = false;
+
+        $listener = new class($invoked) implements MethodCancellationListenerInterface {
+            public function __construct(private bool &$invoked) {}
+
+            public function cancelled(): void
+            {
+                $this->invoked = true;
+            }
+        };
+
+        $canceller->addListener($listener);
+        $canceller->removeListener($listener);
+        $canceller->cancel('irrelevant');
+
+        self::assertFalse($invoked);
+    }
+
+    public function testDeadlineNotExpiredYet(): void
+    {
+        $canceller = new MethodCanceller($this->env, new \DateTimeImmutable('+1 hour'));
+
+        self::assertFalse($canceller->isCancelled());
+        self::assertNull($canceller->getReason());
+    }
+
+    public function testExpiredDeadlineAutoCancelsOnIsCancelled(): void
+    {
+        $canceller = new MethodCanceller($this->env, new \DateTimeImmutable('-1 second'));
+
+        self::assertTrue($canceller->isCancelled());
+        self::assertStringContainsString('deadline exceeded', (string) $canceller->getReason());
+    }
+
+    public function testExpiredDeadlineAutoCancelsOnGetReason(): void
+    {
+        $canceller = new MethodCanceller($this->env, new \DateTimeImmutable('-1 second'));
+
+        // getReason() must trip the cancellation even if isCancelled() wasn't called first.
+        self::assertNotNull($canceller->getReason());
+        self::assertTrue($canceller->isCancelled());
+    }
+
+    public function testListenerFiresOnDeadlineTrip(): void
+    {
+        $this->env->update(new TickInfo(time: new \DateTimeImmutable('2026-01-01T00:00:00Z')));
+        $deadline = new \DateTimeImmutable('2026-01-01T00:00:00.100Z');
+        $canceller = new MethodCanceller($this->env, $deadline);
+
+        $fired = false;
+        $canceller->addListener(ClosureMethodCancellationListener::fromCallable(
+            static function () use (&$fired): void {
+                $fired = true;
+            },
+        ));
+        self::assertFalse($canceller->isCancelled());
+        self::assertFalse($fired);
+
+        $this->env->update(new TickInfo(time: new \DateTimeImmutable('2026-01-01T00:00:01Z')));
+        self::assertTrue($canceller->isCancelled());
+
+        self::assertTrue($fired);
+        self::assertStringContainsString('deadline exceeded', (string) $canceller->getReason());
+    }
+
+    public function testExplicitCancelWinsOverDeadline(): void
+    {
+        $canceller = new MethodCanceller($this->env, new \DateTimeImmutable('-1 second'));
+
+        $canceller->cancel('shutdown');
+
+        // Explicit cancel() before any deadline inspection wins; lazy deadline check is a no-op afterwards.
+        self::assertSame('shutdown', $canceller->getReason());
+    }
+
+    public function testAddListenerOnAlreadyExpiredDeadlineInvokesImmediately(): void
+    {
+        $canceller = new MethodCanceller($this->env, new \DateTimeImmutable('-1 second'));
+
+        $fired = false;
+        $canceller->addListener(ClosureMethodCancellationListener::fromCallable(
+            static function () use (&$fired): void {
+                $fired = true;
+            },
+        ));
+
+        self::assertTrue($fired, 'listener must fire synchronously when deadline already passed');
+        self::assertStringContainsString('deadline exceeded', (string) $canceller->getReason());
+    }
+
+    public function testNoDeadlineNeverAutoCancels(): void
+    {
+        $canceller = new MethodCanceller($this->env);
+
+        self::assertFalse($canceller->isCancelled());
+    }
+
+    public function testListenersInvokedInRegistrationOrder(): void
+    {
+        $canceller = new MethodCanceller($this->env);
+        $order = [];
+        $canceller->addListener(ClosureMethodCancellationListener::fromCallable(
+            static function () use (&$order): void {
+                $order[] = 'a';
+            },
+        ));
+        $canceller->addListener(ClosureMethodCancellationListener::fromCallable(
+            static function () use (&$order): void {
+                $order[] = 'b';
+            },
+        ));
+
+        $canceller->cancel('x');
+
+        self::assertSame(['a', 'b'], $order);
+    }
+
+}
diff --git a/tests/Nexus/Unit/Handler/NexusServiceInstantiatorTest.php b/tests/Nexus/Unit/Handler/NexusServiceInstantiatorTest.php
new file mode 100644
index 000000000..2f1e5e9b7
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/NexusServiceInstantiatorTest.php
@@ -0,0 +1,81 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Spiral\Attributes\AttributeReader;
+use Temporal\Internal\Declaration\Instantiator\NexusServiceInstantiator;
+use Temporal\Internal\Declaration\NexusServiceInstance;
+use Temporal\Internal\Declaration\Prototype\NexusServicePrototype;
+use Temporal\Internal\Declaration\Reader\NexusServiceReader;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Exception\NexusException;
+use Temporal\Nexus\Handler\Internal\MethodOperationHandler;
+use Temporal\Tests\Nexus\Fixtures\Service\GreetingServiceInterface;
+use Temporal\Tests\Nexus\Fixtures\ServiceImplInstance\ChildInheritingHandler;
+use Temporal\Tests\Nexus\Fixtures\ServiceImplInstance\NoServiceAnnotation;
+use Temporal\Tests\Nexus\Fixtures\ServiceImplInstance\ServiceAsClass;
+use Temporal\Tests\Nexus\Fixtures\ServiceImplInstance\ServiceWithExtraNonOperationMethod;
+use Temporal\Tests\Nexus\Support\ExceptionAssertions;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(NexusServiceInstantiator::class)]
+#[CoversClass(NexusServiceInstance::class)]
+#[CoversClass(MethodOperationHandler::class)]
+#[UsesClass(NexusServiceReader::class)]
+#[UsesClass(NexusServicePrototype::class)]
+final class NexusServiceInstantiatorTest extends TestCase
+{
+    use ExceptionAssertions;
+
+    public function testMissingContractInterfaceRejected(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Missing #[Service] attribute on ');
+        self::bind(new NoServiceAnnotation());
+    }
+
+    public function testServiceAttributeOnClassIsAccepted(): void
+    {
+        $instance = self::bind(new ServiceAsClass());
+
+        self::assertSame('ServiceAsClass', $instance->prototype->getID());
+        self::assertCount(1, $instance->operationHandlers);
+        self::assertArrayHasKey('classOperation', $instance->operationHandlers);
+    }
+
+    public function testInheritedHandlerIsDiscovered(): void
+    {
+        $instance = self::bind(new ChildInheritingHandler());
+        self::assertArrayHasKey('operation', $instance->operationHandlers);
+    }
+
+    public function testServiceWithExtraNonOperationMethodIsAccepted(): void
+    {
+        $instance = self::bind(new ServiceWithExtraNonOperationMethod());
+
+        self::assertCount(1, $instance->operationHandlers);
+        self::assertArrayHasKey('operation', $instance->operationHandlers);
+    }
+
+    /**
+     * Helper that wires Reader+Instantiator together — the same flow the
+     * Worker uses at registration time.
+     */
+    private static function bind(object $instance): NexusServiceInstance
+    {
+        $reader = new NexusServiceReader(new AttributeReader());
+        $prototype = $reader->fromClass(\get_class($instance))->withInstance($instance);
+        return (new NexusServiceInstantiator())->instantiate($prototype);
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/OperationCancelDetailsTest.php b/tests/Nexus/Unit/Handler/OperationCancelDetailsTest.php
new file mode 100644
index 000000000..4ebd368e0
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/OperationCancelDetailsTest.php
@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(OperationCancelDetails::class)]
+final class OperationCancelDetailsTest extends TestCase
+{
+    public function testHoldsOperationToken(): void
+    {
+        $d = new OperationCancelDetails('tok-1');
+        self::assertSame('tok-1', $d->operationToken);
+    }
+
+    public function testRejectsEmptyToken(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        new OperationCancelDetails('');
+    }
+
+    public function testRejectsTokenWithWhitespace(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        new OperationCancelDetails("bad tok");
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/OperationContextTest.php b/tests/Nexus/Unit/Handler/OperationContextTest.php
new file mode 100644
index 000000000..a9872f5fd
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/OperationContextTest.php
@@ -0,0 +1,168 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\Handler\ClosureMethodCancellationListener;
+use Temporal\Nexus\Handler\LinkCollection;
+use Temporal\Nexus\Handler\MethodCanceller;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Link;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(OperationContext::class)]
+final class OperationContextTest extends TestCase
+{
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    public function testLinksAddAndSet(): void
+    {
+        $ctx = new OperationContext(service: 'service', operation: 'operation', env: $this->env);
+        $ctx->links->add(new Link('http://somepath?k=v', 'com.example.MyResource'));
+
+        self::assertEquals(
+            [new Link('http://somepath?k=v', 'com.example.MyResource')],
+            $ctx->links->all(),
+        );
+    }
+
+    public function testDeadline(): void
+    {
+        $deadline = new \DateTimeImmutable('+1 second');
+        $ctx = new OperationContext(
+            service: 'service',
+            operation: 'operation',
+            env: $this->env,
+            deadline: $deadline,
+        );
+
+        self::assertSame($deadline, $ctx->deadline);
+    }
+
+    public function testConstructorNormalizesHeaders(): void
+    {
+        $ctx = new OperationContext(
+            service: 's',
+            operation: 'o',
+            env: $this->env,
+            headers: [
+                'Content-Type' => 'text/plain',
+                'UPPER-CASE-HEADER' => 'UPPER-VALUE',
+                'lower-case-header' => 'lower-value',
+            ],
+        );
+
+        self::assertSame(
+            [
+                'content-type' => 'text/plain',
+                'upper-case-header' => 'UPPER-VALUE',
+                'lower-case-header' => 'lower-value',
+            ],
+            $ctx->headers->all(),
+        );
+    }
+
+    public function testLinksPassedAsExistingCollectionAreUsedAsIs(): void
+    {
+        $collection = new LinkCollection([new Link('shared', 't')]);
+        $ctx = new OperationContext(service: 's', operation: 'o', env: $this->env, links: $collection);
+
+        $collection->add(new Link('added-outside', 't'));
+        // The same collection was injected, so external additions are visible.
+        self::assertSame($collection, $ctx->links);
+        self::assertCount(2, $ctx->links->all());
+    }
+
+    public function testMethodCancellationDegradesWithoutCanceller(): void
+    {
+        $ctx = new OperationContext(service: 's', operation: 'o', env: $this->env);
+
+        self::assertFalse($ctx->isMethodCancelled());
+        self::assertNull($ctx->getMethodCancellationReason());
+
+        // Listener registration without a canceller is a silent no-op.
+        $called = false;
+        $listener = ClosureMethodCancellationListener::fromCallable(
+            static function () use (&$called): void {
+                $called = true;
+            },
+        );
+        $ctx->addMethodCancellationListener($listener);
+        $ctx->removeMethodCancellationListener($listener);
+        self::assertFalse($called);
+    }
+
+    public function testMethodCancellationPropagatesFromCanceller(): void
+    {
+        $canceller = new MethodCanceller($this->env);
+        $ctx = new OperationContext(
+            service: 's',
+            operation: 'o',
+            env: $this->env,
+            methodCanceller: $canceller,
+        );
+
+        self::assertFalse($ctx->isMethodCancelled());
+
+        $fired = false;
+        $ctx->addMethodCancellationListener(ClosureMethodCancellationListener::fromCallable(
+            static function () use (&$fired): void {
+                $fired = true;
+            },
+        ));
+
+        $canceller->cancel('shutdown');
+
+        self::assertTrue($ctx->isMethodCancelled());
+        self::assertSame('shutdown', $ctx->getMethodCancellationReason());
+        self::assertTrue($fired);
+    }
+
+    public function testIsMethodCancelledTripsOnDeadlineEvenWithoutCanceller(): void
+    {
+        // No canceller attached — but deadline-based trip must still be observable so
+        // long-running handlers that only poll isMethodCancelled() degrade correctly on
+        // transports without method-cancel support.
+        $ctx = new OperationContext(
+            service: 's',
+            operation: 'o',
+            env: $this->env,
+            deadline: new \DateTimeImmutable('-1 second'),
+        );
+
+        self::assertTrue($ctx->isMethodCancelled());
+        self::assertStringContainsString('deadline exceeded', (string) $ctx->getMethodCancellationReason());
+    }
+
+    public function testExplicitCancellerReasonBeatsDeadline(): void
+    {
+        $canceller = new MethodCanceller($this->env);
+        $canceller->cancel('shutdown');
+        $ctx = new OperationContext(
+            service: 's',
+            operation: 'o',
+            env: $this->env,
+            deadline: new \DateTimeImmutable('-1 second'),
+            methodCanceller: $canceller,
+        );
+
+        self::assertSame('shutdown', $ctx->getMethodCancellationReason());
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/OperationStartDetailsTest.php b/tests/Nexus/Unit/Handler/OperationStartDetailsTest.php
new file mode 100644
index 000000000..f2574d487
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/OperationStartDetailsTest.php
@@ -0,0 +1,61 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Link;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(OperationStartDetails::class)]
+final class OperationStartDetailsTest extends TestCase
+{
+    public function testStoresAllProperties(): void
+    {
+        $links = [new Link('https://x', 'app/x')];
+        $d = new OperationStartDetails(
+            requestId: 'req-1',
+            callbackUrl: 'https://cb',
+            callbackHeaders: ['Token' => 'secret'],
+            links: $links,
+        );
+
+        self::assertSame('req-1', $d->requestId);
+        self::assertSame('https://cb', $d->callbackUrl);
+        self::assertSame(['Token' => 'secret'], $d->callbackHeaders);
+        self::assertSame($links, $d->links);
+    }
+
+    public function testRejectsEmptyRequestId(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('OperationStartDetails requires a non-empty requestId');
+        new OperationStartDetails(requestId: '');
+    }
+
+    public function testRejectsNonLinkInLinksList(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('links[1] must be');
+        /** @phpstan-ignore-next-line — intentionally wrong type */
+        new OperationStartDetails(requestId: 'r', links: [new Link('a', 't'), 'not-a-link']);
+    }
+
+    public function testRejectsNonLinkInLinksMapWithStringKey(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("links['k']");
+        /** @phpstan-ignore-next-line — intentionally wrong type */
+        new OperationStartDetails(requestId: 'r', links: ['k' => 'not-a-link']);
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/OperationStartResultTest.php b/tests/Nexus/Unit/Handler/OperationStartResultTest.php
new file mode 100644
index 000000000..526001877
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/OperationStartResultTest.php
@@ -0,0 +1,69 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\Handler\AsyncOperationStartResult;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\Handler\SyncOperationStartResult;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(OperationStartResult::class)]
+#[CoversClass(SyncOperationStartResult::class)]
+#[CoversClass(AsyncOperationStartResult::class)]
+final class OperationStartResultTest extends TestCase
+{
+    public function testSyncFactoryReturnsSyncSubclass(): void
+    {
+        $result = OperationStartResult::sync(null);
+
+        self::assertInstanceOf(SyncOperationStartResult::class, $result);
+        self::assertNull($result->value);
+    }
+
+    public function testSyncCarriesValue(): void
+    {
+        $result = OperationStartResult::sync('hello');
+
+        self::assertInstanceOf(SyncOperationStartResult::class, $result);
+        self::assertSame('hello', $result->value);
+    }
+
+    public function testAsyncFactoryReturnsAsyncSubclass(): void
+    {
+        $info = new OperationInfo('token-123', OperationState::Running);
+        $result = OperationStartResult::async($info);
+
+        self::assertInstanceOf(AsyncOperationStartResult::class, $result);
+        self::assertSame($info, $result->info);
+    }
+
+    public function testPatternMatchWithInstanceOf(): void
+    {
+        $results = [
+            OperationStartResult::sync('v'),
+            OperationStartResult::async(new OperationInfo('tok', OperationState::Running)),
+        ];
+
+        $summary = \array_map(
+            static fn(OperationStartResult $r): string => match (true) {
+                $r instanceof SyncOperationStartResult  => "sync:{$r->value}",
+                $r instanceof AsyncOperationStartResult => "async:{$r->info->token}",
+            },
+            $results,
+        );
+
+        self::assertSame(['sync:v', 'async:tok'], $summary);
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/ServiceHandlerEdgeCasesTest.php b/tests/Nexus/Unit/Handler/ServiceHandlerEdgeCasesTest.php
new file mode 100644
index 000000000..127c39a3d
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/ServiceHandlerEdgeCasesTest.php
@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\DataConverter\DataConverter;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Handler\Internal\ServiceHandler;
+use Temporal\Tests\Nexus\Fixtures\ServiceHandler\VoidService;
+use Temporal\Tests\Nexus\Support\BindNexusService;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ServiceHandler::class)]
+final class ServiceHandlerEdgeCasesTest extends TestCase
+{
+    use BindNexusService;
+
+    public function testNoInstancesThrows(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('No service instances defined');
+        ServiceHandler::create(
+            dataConverter: DataConverter::createDefault(),
+            instances: [],
+        );
+    }
+
+    public function testDuplicateServiceNames(): void
+    {
+        $instance = self::bindNexusService(new VoidService());
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("Multiple instances registered for service name");
+        ServiceHandler::create(
+            dataConverter: DataConverter::createDefault(),
+            instances: [$instance, $instance],
+        );
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/ServiceHandlerInterceptorTest.php b/tests/Nexus/Unit/Handler/ServiceHandlerInterceptorTest.php
new file mode 100644
index 000000000..861936acc
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/ServiceHandlerInterceptorTest.php
@@ -0,0 +1,244 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\NexusOperationContext;
+
+use Temporal\Interceptor\NexusOperationInbound\CancelOperationInput;
+use Temporal\Interceptor\NexusOperationInbound\StartOperationInput;
+use Temporal\Interceptor\NexusOperationInboundCallsInterceptor;
+use Temporal\Interceptor\SimplePipelineProvider;
+use Temporal\Interceptor\Trait\NexusOperationInboundCallsInterceptorTrait;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Handler\Internal\ServiceHandler;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Tests\Nexus\Fixtures\Service\GreetingService;
+use Temporal\Tests\Nexus\Support\BindNexusService;
+use Temporal\Tests\Nexus\Support\EncodesValues;
+use Temporal\Tests\Nexus\Support\MocksAsyncWorkflowClient;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ServiceHandler::class)]
+final class ServiceHandlerInterceptorTest extends TestCase
+{
+    use BindNexusService;
+    use EncodesValues;
+    use MocksAsyncWorkflowClient;
+
+    private const NS = 'sample-ns';
+    private const TQ = 'sample-tq';
+
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    public function testMultipleInterceptorsAreAppliedInRegistrationOrder(): void
+    {
+        $log = [];
+        $record = static function (string $name) use (&$log): NexusOperationInboundCallsInterceptor {
+            return new class($name, $log) implements NexusOperationInboundCallsInterceptor {
+                use NexusOperationInboundCallsInterceptorTrait;
+
+                /**
+                 * @param list<string> $log
+                 */
+                public function __construct(
+                    private readonly string $name,
+                    private array &$log,
+                ) {}
+
+                public function startOperation(
+                    StartOperationInput $input,
+                    callable $next,
+                ): OperationStartResult {
+                    $this->log[] = "enter:{$this->name}";
+                    $result = $next($input);
+                    $this->log[] = "exit:{$this->name}";
+                    return $result;
+                }
+            };
+        };
+
+        $handler = ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [self::bindNexusService(new GreetingService(static fn($n) => "g-{$n}"))],
+            interceptorProvider: new SimplePipelineProvider([$record('A'), $record('B'), $record('C')]),
+        );
+
+        $handler->startOperation(
+            new OperationContext(service: 'GreetingServiceInterface', operation: 'sayHello1', env: $this->env),
+            new OperationStartDetails(requestId: 'r1'),
+            self::encode('User'),
+            null,
+            new NexusOperationContext(),
+        );
+
+        // First registered interceptor is the outermost.
+        self::assertSame(
+            ['enter:A', 'enter:B', 'enter:C', 'exit:C', 'exit:B', 'exit:A'],
+            $log,
+        );
+    }
+
+    public function testInterceptorCanOverrideHandlerResult(): void
+    {
+        $overriding = new class implements NexusOperationInboundCallsInterceptor {
+            use NexusOperationInboundCallsInterceptorTrait;
+
+            public function startOperation(
+                StartOperationInput $input,
+                callable $next,
+            ): OperationStartResult {
+                \assert($input->input instanceof \Temporal\DataConverter\ValuesInterface);
+                return OperationStartResult::sync('rewritten-' . $input->input->getValue(0, 'string'));
+            }
+        };
+
+        $handler = ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [self::bindNexusService(new GreetingService(static fn($n) => "g-{$n}"))],
+            interceptorProvider: new SimplePipelineProvider([$overriding]),
+        );
+
+        $result = $handler->startOperation(
+            new OperationContext(service: 'GreetingServiceInterface', operation: 'sayHello1', env: $this->env),
+            new OperationStartDetails(requestId: 'r1'),
+            self::encode('Alice'),
+            null,
+            new NexusOperationContext(),
+        );
+
+        self::assertSame('rewritten-Alice', $result->value->getValue(0, 'string'));
+    }
+
+    public function testInterceptorExceptionPropagates(): void
+    {
+        $exploding = new class implements NexusOperationInboundCallsInterceptor {
+            use NexusOperationInboundCallsInterceptorTrait;
+
+            public function startOperation(
+                StartOperationInput $input,
+                callable $next,
+            ): OperationStartResult {
+                throw HandlerException::create(ErrorType::Unauthorized, 'blocked');
+            }
+        };
+
+        $handler = ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [self::bindNexusService(new GreetingService(static fn($n) => "g-{$n}"))],
+            interceptorProvider: new SimplePipelineProvider([$exploding]),
+        );
+
+        $this->expectException(HandlerException::class);
+        $this->expectExceptionMessage('blocked');
+        $handler->startOperation(
+            new OperationContext(service: 'GreetingServiceInterface', operation: 'sayHello1', env: $this->env),
+            new OperationStartDetails(requestId: 'r1'),
+            self::encode('X'),
+            null,
+            new NexusOperationContext(),
+        );
+    }
+
+    public function testInterceptorCanSwallowHandlerException(): void
+    {
+        $swallowing = new class implements NexusOperationInboundCallsInterceptor {
+            use NexusOperationInboundCallsInterceptorTrait;
+
+            public function startOperation(
+                StartOperationInput $input,
+                callable $next,
+            ): OperationStartResult {
+                try {
+                    return $next($input);
+                } catch (HandlerException) {
+                    return OperationStartResult::sync('fallback');
+                }
+            }
+        };
+
+        // The injected apiClient is invoked by the async sayHello2 path; we make it throw.
+        $handler = ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [self::bindNexusService(new GreetingService(
+                static fn(string $n): string => throw HandlerException::create(ErrorType::Internal, 'boom'),
+            ))],
+            interceptorProvider: new SimplePipelineProvider([$swallowing]),
+        );
+
+        $result = $handler->startOperation(
+            new OperationContext(service: 'GreetingServiceInterface', operation: 'sayHello2', env: $this->env),
+            new OperationStartDetails(requestId: 'r1'),
+            self::encode('X'),
+            null,
+            new NexusOperationContext(),
+        );
+
+        self::assertSame('fallback', $result->value->getValue(0, 'string'));
+    }
+
+    public function testCancelInterceptorReceivesContext(): void
+    {
+        $seen = [];
+        $observer = new class($seen) implements NexusOperationInboundCallsInterceptor {
+            use NexusOperationInboundCallsInterceptorTrait;
+
+            /**
+             * @param list<string> $seen
+             */
+            public function __construct(private array &$seen) {}
+
+            public function cancelOperation(CancelOperationInput $input, callable $next): void
+            {
+                $this->seen[] = "{$input->operationContext->operation}:{$input->cancelDetails->operationToken}";
+                $next($input);
+            }
+        };
+
+        $handler = ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [self::bindNexusService(new GreetingService(static fn($n) => "g-{$n}"))],
+            interceptorProvider: new SimplePipelineProvider([$observer]),
+        );
+
+        $started = $handler->startOperation(
+            new OperationContext(service: 'GreetingServiceInterface', operation: 'sayHello2', env: $this->env),
+            new OperationStartDetails(requestId: 'r1'),
+            self::encode('User'),
+            $this->asyncClient(),
+            new NexusOperationContext(self::NS, self::TQ),
+        );
+
+        $token = $started->info->token;
+        self::assertNotNull($token);
+
+        $handler->cancelOperation(
+            new OperationContext(service: 'GreetingServiceInterface', operation: 'sayHello2', env: $this->env),
+            new \Temporal\Nexus\Handler\OperationCancelDetails(operationToken: $token),
+            $this->asyncClient(),
+            new NexusOperationContext('test-ns', 'test-tq'),
+        );
+
+        self::assertSame(["sayHello2:{$token}"], $seen);
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/ServiceHandlerSerdeErrorsTest.php b/tests/Nexus/Unit/Handler/ServiceHandlerSerdeErrorsTest.php
new file mode 100644
index 000000000..62998e6ec
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/ServiceHandlerSerdeErrorsTest.php
@@ -0,0 +1,231 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\NexusOperationContext;
+
+use Temporal\Api\Common\V1\Payload;
+use Temporal\DataConverter\DataConverter;
+use Temporal\DataConverter\DataConverterInterface;
+use Temporal\DataConverter\EncodedValues;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\OperationException;
+use Temporal\Nexus\Exception\RetryBehavior;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\Internal\ServiceHandler;
+use Temporal\Tests\Nexus\Fixtures\Service\ThrowingGreetingService;
+use Temporal\Tests\Nexus\Support\BindNexusService;
+use Temporal\Tests\Nexus\Support\ExceptionAssertions;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ServiceHandler::class)]
+final class ServiceHandlerSerdeErrorsTest extends TestCase
+{
+    use BindNexusService;
+    use ExceptionAssertions;
+
+    private static EnvironmentInterface $env;
+
+    public static function setUpBeforeClass(): void
+    {
+        parent::setUpBeforeClass();
+        self::$env = new Environment();
+    }
+
+    public function testDeserializeFailureWrapsAsBadRequestHandlerException(): void
+    {
+        $converter = self::failingDeserializeConverter();
+        $handler = self::newHandler($converter);
+
+        $e = self::assertThrown(HandlerException::class, static fn() => $handler->startOperation(
+            self::newContext('sayHello1'),
+            new OperationStartDetails(requestId: 'r1'),
+            self::input($converter),
+            null,
+            new NexusOperationContext(),
+        ));
+
+        self::assertStringContainsString(
+            'Failed deserializing input for GreetingServiceInterface/sayHello1 as string: Bad JSON',
+            $e->getMessage(),
+        );
+        self::assertSame(ErrorType::BadRequest, $e->errorType);
+        self::assertInstanceOf(\JsonException::class, $e->getPrevious());
+    }
+
+    public function testSerializeFailureWrapsAsInternalHandlerException(): void
+    {
+        $converter = self::failingSerializeConverter();
+        $handler = self::newHandler($converter);
+
+        $e = self::assertThrown(HandlerException::class, static fn() => $handler->startOperation(
+            self::newContext('sayHello1'),
+            new OperationStartDetails(requestId: 'r1'),
+            self::input($converter),
+            null,
+            new NexusOperationContext(),
+        ));
+
+        self::assertStringContainsString(
+            'Failed serializing result for GreetingServiceInterface/sayHello1 as string: cannot serialize',
+            $e->getMessage(),
+        );
+        self::assertSame(ErrorType::Internal, $e->errorType);
+        self::assertInstanceOf(\RuntimeException::class, $e->getPrevious());
+    }
+
+    public function testOperationExceptionFromHandlerIsNotWrapped(): void
+    {
+        $converter = DataConverter::createDefault();
+        $handler = self::newHandler(
+            $converter,
+            new ThrowingGreetingService(hello1Throw: OperationException::failed('intentional business failure')),
+        );
+
+        $this->expectException(OperationException::class);
+        $this->expectExceptionMessage('intentional business failure');
+        $handler->startOperation(
+            self::newContext('sayHello1'),
+            new OperationStartDetails(requestId: 'r1'),
+            EncodedValues::fromValues(['anything'], $converter),
+            null,
+            new NexusOperationContext(),
+        );
+    }
+
+    public function testHandlerExceptionFromHandlerIsNotDoubleWrapped(): void
+    {
+        $converter = DataConverter::createDefault();
+        $handler = self::newHandler(
+            $converter,
+            new ThrowingGreetingService(hello1Throw: HandlerException::create(
+                ErrorType::Unauthorized,
+                'no auth',
+                retryBehavior: RetryBehavior::NonRetryable,
+            )),
+        );
+
+        $e = self::assertThrown(HandlerException::class, static fn() => $handler->startOperation(
+            self::newContext('sayHello1'),
+            new OperationStartDetails(requestId: 'r1'),
+            EncodedValues::fromValues(['anything'], $converter),
+            null,
+            new NexusOperationContext(),
+        ));
+
+        self::assertSame(ErrorType::Unauthorized, $e->errorType);
+        self::assertSame('no auth', $e->getMessage());
+        self::assertSame(RetryBehavior::NonRetryable, $e->retryBehavior);
+    }
+
+    public function testDeserializeErrorMessageContainsServiceOperationAndType(): void
+    {
+        $converter = self::failingDeserializeConverter();
+        $handler = self::newHandler($converter);
+
+        $e = self::assertThrown(HandlerException::class, static fn() => $handler->startOperation(
+            self::newContext('sayHello2'),
+            new OperationStartDetails(requestId: 'r1'),
+            self::input($converter),
+            null,
+            new NexusOperationContext(),
+        ));
+
+        self::assertStringContainsString('GreetingServiceInterface', $e->getMessage());
+        self::assertStringContainsString('sayHello2', $e->getMessage());
+        self::assertStringContainsString('string', $e->getMessage());
+    }
+
+    public function testSerializeErrorMessageContainsOutputType(): void
+    {
+        $converter = self::failingSerializeConverter();
+        $handler = self::newHandler($converter);
+
+        $e = self::assertThrown(HandlerException::class, static fn() => $handler->startOperation(
+            self::newContext('sayHello1'),
+            new OperationStartDetails(requestId: 'r1'),
+            self::input($converter),
+            null,
+            new NexusOperationContext(),
+        ));
+
+        self::assertStringContainsString('as string', $e->getMessage());
+    }
+
+    private static function newHandler(
+        DataConverterInterface $dataConverter,
+        ?ThrowingGreetingService $instance = null,
+    ): ServiceHandler {
+        return ServiceHandler::create(
+            dataConverter: $dataConverter,
+            instances: [self::bindNexusService($instance ?? new ThrowingGreetingService())],
+        );
+    }
+
+    private static function newContext(string $operation): OperationContext
+    {
+        return new OperationContext(
+            service: 'GreetingServiceInterface',
+            operation: $operation,
+            env: self::$env,
+        );
+    }
+
+    /**
+     * Wrap a single dummy proto Payload so ServiceHandler routes through
+     * `DataConverterInterface::fromPayload()` (the path that may raise).
+     */
+    private static function input(DataConverterInterface $dataConverter): EncodedValues
+    {
+        $payload = new Payload();
+        $payload->setData('garbage');
+        $payloads = new \Temporal\Api\Common\V1\Payloads(['payloads' => [$payload]]);
+        return EncodedValues::fromPayloads($payloads, $dataConverter);
+    }
+
+    private static function failingDeserializeConverter(): DataConverterInterface
+    {
+        return new class implements DataConverterInterface {
+            public function fromPayload(Payload $payload, mixed $type): mixed
+            {
+                throw new \JsonException('Bad JSON');
+            }
+
+            public function toPayload(mixed $value): Payload
+            {
+                $p = new Payload();
+                $p->setData((string) $value);
+                return $p;
+            }
+        };
+    }
+
+    private static function failingSerializeConverter(): DataConverterInterface
+    {
+        return new class implements DataConverterInterface {
+            public function fromPayload(Payload $payload, mixed $type): mixed
+            {
+                return $payload->getData();
+            }
+
+            public function toPayload(mixed $value): Payload
+            {
+                throw new \RuntimeException('cannot serialize');
+            }
+        };
+    }
+}
diff --git a/tests/Nexus/Unit/Handler/ServiceHandlerTest.php b/tests/Nexus/Unit/Handler/ServiceHandlerTest.php
new file mode 100644
index 000000000..b819bf879
--- /dev/null
+++ b/tests/Nexus/Unit/Handler/ServiceHandlerTest.php
@@ -0,0 +1,285 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Handler;
+
+use Temporal\Nexus\NexusOperationContext;
+
+use Temporal\DataConverter\EncodedValues;
+use Temporal\Interceptor\PipelineProvider;
+use Temporal\Interceptor\SimplePipelineProvider;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\Internal\ServiceHandler;
+use Temporal\Nexus\Internal\WorkflowRunOperationToken;
+use Temporal\Tests\Nexus\Fixtures\Service\GreetingService;
+use Temporal\Tests\Nexus\Fixtures\ServiceHandler\AuthInterceptor;
+use Temporal\Tests\Nexus\Fixtures\ServiceHandler\LoggingInterceptor;
+use Temporal\Tests\Nexus\Fixtures\ServiceHandler\VoidService;
+use Temporal\Tests\Nexus\Support\BindNexusService;
+use Temporal\Tests\Nexus\Support\EncodesValues;
+use Temporal\Tests\Nexus\Support\ExceptionAssertions;
+use Temporal\Tests\Nexus\Support\MocksAsyncWorkflowClient;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ServiceHandler::class)]
+final class ServiceHandlerTest extends TestCase
+{
+    use BindNexusService;
+    use EncodesValues;
+    use ExceptionAssertions;
+    use MocksAsyncWorkflowClient;
+
+    private const NS = 'sample-ns';
+    private const TQ = 'sample-tq';
+
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    public function testVoidService(): void
+    {
+        $serviceInstance = self::bindNexusService(new VoidService());
+        self::assertCount(1, $serviceInstance->operationHandlers);
+    }
+
+    public function testSyncHandlerReturnsSyncResult(): void
+    {
+        $handler = self::newGreetingHandler();
+
+        $result = $handler->startOperation(
+            $this->newGreetingContext('sayHello1'),
+            new OperationStartDetails(requestId: 'r1'),
+            self::encode('SomeUser'),
+            null,
+            new NexusOperationContext(),
+        );
+
+        self::assertSame('Hello, SomeUser!', $result->value->getValue(0, 'string'));
+    }
+
+    public function testAsyncHandlerReturnsToken(): void
+    {
+        $handler = self::newGreetingHandler();
+
+        $result = $handler->startOperation(
+            $this->newGreetingContext('sayHello2'),
+            new OperationStartDetails(requestId: 'r3'),
+            self::encode('SomeUser'),
+            $this->asyncClient(),
+            $this->asyncOperationContext(),
+        );
+
+        $expectedToken = WorkflowRunOperationToken::generate(self::NS, GreetingService::WORKFLOW_ID);
+        self::assertSame($expectedToken, $result->info->token);
+    }
+
+    public function testAsyncHandlerWithoutWorkflowClientSurfacesLogicException(): void
+    {
+        $handler = self::newGreetingHandler();
+
+        $e = self::assertThrown(\LogicException::class, fn() => $handler->startOperation(
+            $this->newGreetingContext('sayHello2'),
+            new OperationStartDetails(requestId: 'r3'),
+            self::encode('SomeUser'),
+            null,
+            $this->asyncOperationContext(),
+        ));
+
+        self::assertSame(
+            'Nexus::getWorkflowClient() requires a WorkflowClient. Async Nexus operations (WorkflowRunOperation)'
+            . ' need cluster access; provide a WorkflowClient to the WorkerFactory.',
+            $e->getMessage(),
+        );
+    }
+
+    public function testAsyncHandlerCollectsLinksOnLinkSuffixedInput(): void
+    {
+        $handler = self::newGreetingHandler();
+        $context = $this->newGreetingContext('sayHello2');
+
+        $result = $handler->startOperation(
+            $context,
+            new OperationStartDetails(requestId: 'r4'),
+            self::encode('SomeUser-link'),
+            $this->asyncClient(),
+            $this->asyncOperationContext(),
+        );
+
+        self::assertNotNull($result->info->token);
+        $links = $context->links->all();
+        self::assertCount(2, $links);
+        self::assertSame('http://somepath?k=v', $links[0]->uri);
+        self::assertSame('com.example.MyResource', $links[0]->type);
+        self::assertSame(
+            'temporal:///namespaces/sample-ns/workflows/greeting-workflow/run-1/history'
+            . '?referenceType=EventReference&eventType=WorkflowExecutionStarted',
+            $links[1]->uri,
+        );
+        self::assertSame('temporal.api.common.v1.Link.WorkflowEvent', $links[1]->type);
+    }
+
+    public function testAuthInterceptorAllowsCallWithValidToken(): void
+    {
+        $token = 'auth-token';
+        $handler = self::newGreetingHandler(new SimplePipelineProvider([
+            new AuthInterceptor($token),
+            new LoggingInterceptor(),
+        ]));
+
+        $result = $handler->startOperation(
+            new OperationContext(
+                service: 'GreetingServiceInterface',
+                operation: 'sayHello1',
+                env: $this->env,
+                headers: [AuthInterceptor::AUTH_HEADER => $token],
+            ),
+            new OperationStartDetails(requestId: 'r1'),
+            self::encode('SomeUser'),
+            null,
+            new NexusOperationContext(),
+        );
+
+        self::assertSame('Hello, SomeUser!', $result->value->getValue(0, 'string'));
+    }
+
+    public function testAuthInterceptorRejectsCallWithMissingToken(): void
+    {
+        $handler = self::newGreetingHandler(new SimplePipelineProvider([
+            new AuthInterceptor('auth-token'),
+            new LoggingInterceptor(),
+        ]));
+
+        $this->expectException(HandlerException::class);
+        $handler->startOperation(
+            new OperationContext(
+                service: 'GreetingServiceInterface',
+                operation: 'sayHello1',
+                env: $this->env,
+            ),
+            new OperationStartDetails(requestId: 'r2'),
+            self::encode('SomeUser'),
+            null,
+            new NexusOperationContext(),
+        );
+    }
+
+    public function testLoggingInterceptorRecordsAuthorizedCallsOnly(): void
+    {
+        $token = 'auth-token';
+        $logger = new LoggingInterceptor();
+        $handler = self::newGreetingHandler(new SimplePipelineProvider([
+            new AuthInterceptor($token),
+            $logger,
+        ]));
+
+        $handler->startOperation(
+            new OperationContext(
+                service: 'GreetingServiceInterface',
+                operation: 'sayHello1',
+                env: $this->env,
+                headers: [AuthInterceptor::AUTH_HEADER => $token],
+            ),
+            new OperationStartDetails(requestId: 'r1'),
+            self::encode('SomeUser'),
+            null,
+            new NexusOperationContext(),
+        );
+
+        self::assertSame(['sayHello1'], $logger->getOperations());
+    }
+
+    public function testUnrecognizedService(): void
+    {
+        $handler = ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [self::bindNexusService(new VoidService())],
+        );
+
+        $e = self::assertThrown(HandlerException::class, fn() => $handler->startOperation(
+            new OperationContext(service: 'NonExistent', operation: 'op', env: $this->env),
+            new OperationStartDetails(requestId: 'r1'),
+            EncodedValues::empty(),
+            null,
+            new NexusOperationContext(),
+        ));
+
+        self::assertSame(ErrorType::NotFound, $e->errorType);
+        self::assertStringContainsString("Unrecognized service 'NonExistent'", $e->getMessage());
+    }
+
+    public function testUnrecognizedOperation(): void
+    {
+        $handler = ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [self::bindNexusService(new VoidService())],
+        );
+
+        $e = self::assertThrown(HandlerException::class, fn() => $handler->startOperation(
+            new OperationContext(service: 'VoidServiceInterface', operation: 'nonExistent', env: $this->env),
+            new OperationStartDetails(requestId: 'r1'),
+            EncodedValues::empty(),
+            null,
+            new NexusOperationContext(),
+        ));
+
+        self::assertSame(ErrorType::NotFound, $e->errorType);
+        self::assertStringContainsString("has no operation 'nonExistent'", $e->getMessage());
+    }
+
+    public function testCancelOnSyncHandlerThrowsNotImplemented(): void
+    {
+        $handler = ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [self::bindNexusService(new VoidService())],
+        );
+
+        $this->expectException(HandlerException::class);
+        $this->expectExceptionMessage('synchronous and cannot be cancelled');
+        $handler->cancelOperation(
+            new OperationContext(service: 'VoidServiceInterface', operation: 'operation', env: $this->env),
+            new OperationCancelDetails(operationToken: 'some-token'),
+            null,
+            new NexusOperationContext(),
+        );
+    }
+
+    private static function newGreetingHandler(?PipelineProvider $interceptorProvider = null): ServiceHandler
+    {
+        $apiClient = static fn(string $name): string => "greeting-{$name}";
+
+        return ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [self::bindNexusService(new GreetingService($apiClient))],
+            interceptorProvider: $interceptorProvider ?? new SimplePipelineProvider(),
+        );
+    }
+
+    private function newGreetingContext(string $operation): OperationContext
+    {
+        return new OperationContext(service: 'GreetingServiceInterface', operation: $operation, env: $this->env);
+    }
+
+    private function asyncOperationContext(): NexusOperationContext
+    {
+        return new NexusOperationContext(self::NS, self::TQ);
+    }
+}
diff --git a/tests/Nexus/Unit/HeaderTest.php b/tests/Nexus/Unit/HeaderTest.php
new file mode 100644
index 000000000..27ba1f3df
--- /dev/null
+++ b/tests/Nexus/Unit/HeaderTest.php
@@ -0,0 +1,137 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Header;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(Header::class)]
+final class HeaderTest extends TestCase
+{
+    public function testAllKnownNexusHeaderConstants(): void
+    {
+        // Guard against typos in constant values — these are wire-level and must be stable.
+        self::assertSame('Request-Timeout', Header::REQUEST_TIMEOUT);
+        self::assertSame('Operation-Timeout', Header::OPERATION_TIMEOUT);
+        self::assertSame('Nexus-Operation-Id', Header::OPERATION_ID);
+        self::assertSame('Nexus-Operation-Token', Header::OPERATION_TOKEN);
+        self::assertSame('Nexus-Operation-Start-Time', Header::OPERATION_START_TIME);
+        self::assertSame('Nexus-Operation-Close-Time', Header::OPERATION_CLOSE_TIME);
+        self::assertSame('Nexus-Operation-State', Header::OPERATION_STATE);
+        self::assertSame('Nexus-Request-Id', Header::REQUEST_ID);
+        self::assertSame('Nexus-Link', Header::LINK);
+        self::assertSame('Nexus-Callback-Url', Header::CALLBACK_URL);
+        self::assertSame('Nexus-Callback-Token', Header::CALLBACK_TOKEN);
+        self::assertSame('Nexus-Callback-', Header::CALLBACK_PREFIX);
+        self::assertSame('Content-Type', Header::CONTENT_TYPE);
+        self::assertSame('application/json', Header::CONTENT_TYPE_JSON);
+    }
+
+    // ── get() lookup ────────────────────────────────────────────────
+
+    public function testGetLooksUpByCaseInsensitiveName(): void
+    {
+        $headers = ['nexus-operation-token' => 'abc123']; // already lowercase
+
+        self::assertSame('abc123', Header::get($headers, Header::OPERATION_TOKEN));
+        self::assertSame('abc123', Header::get($headers, 'NEXUS-OPERATION-TOKEN'));
+        self::assertSame('abc123', Header::get($headers, 'nexus-operation-token'));
+        self::assertNull(Header::get($headers, 'x-unknown'));
+    }
+
+    public function testGetReturnsNullOnEmptyBag(): void
+    {
+        self::assertNull(Header::get([], Header::REQUEST_ID));
+    }
+
+    // ── parseTimeout() ──────────────────────────────────────────────
+
+    public function testParseTimeoutMilliseconds(): void
+    {
+        $i = Header::parseTimeout('250ms');
+
+        self::assertNotNull($i);
+        // DateInterval from 'milliseconds' carries the fraction in ->f.
+        self::assertEqualsWithDelta(0.25, $i->s + $i->f, 0.001);
+    }
+
+    public function testParseTimeoutSeconds(): void
+    {
+        $i = Header::parseTimeout('30s');
+
+        self::assertNotNull($i);
+        self::assertSame(30, $i->s);
+    }
+
+    public function testParseTimeoutMinutes(): void
+    {
+        $i = Header::parseTimeout('2m');
+
+        self::assertNotNull($i);
+        self::assertSame(2, $i->i);
+    }
+
+    public function testParseTimeoutReturnsNullForEmpty(): void
+    {
+        self::assertNull(Header::parseTimeout(''));
+        self::assertNull(Header::parseTimeout('   '));
+    }
+
+    /**
+     * @return iterable<string, array{0: string}>
+     */
+    public static function malformedTimeoutProvider(): iterable
+    {
+        yield 'unknown unit us' => ['30us'];
+        yield 'no unit'         => ['30'];
+        yield 'bare number'     => ['5'];
+        yield 'only unit'       => ['ms'];
+        yield 'pure garbage'    => ['abc'];
+        yield 'trailing junk'   => ['12x'];
+    }
+
+    #[DataProvider('malformedTimeoutProvider')]
+    public function testParseTimeoutRejectsMalformed(string $input): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("Invalid Nexus timeout '{$input}'");
+
+        Header::parseTimeout($input);
+    }
+
+    // ── deadlineFromTimeout() ───────────────────────────────────────
+
+    public function testDeadlineFromTimeoutAddsIntervalToNow(): void
+    {
+        $now = new \DateTimeImmutable('2026-01-01T00:00:00Z');
+
+        $deadline = Header::deadlineFromTimeout('30s', $now);
+
+        self::assertNotNull($deadline);
+        self::assertSame('2026-01-01T00:00:30+00:00', $deadline->format('c'));
+    }
+
+    public function testDeadlineFromTimeoutReturnsNullForEmpty(): void
+    {
+        self::assertNull(Header::deadlineFromTimeout(''));
+    }
+
+    public function testDeadlineFromTimeoutThrowsOnMalformed(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        Header::deadlineFromTimeout('garbage');
+    }
+
+}
diff --git a/tests/Nexus/Unit/Interceptor/CancelOperationInputTest.php b/tests/Nexus/Unit/Interceptor/CancelOperationInputTest.php
new file mode 100644
index 000000000..0b3bd9054
--- /dev/null
+++ b/tests/Nexus/Unit/Interceptor/CancelOperationInputTest.php
@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Interceptor;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use Temporal\Interceptor\NexusOperationInbound\CancelOperationInput;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+
+#[CoversClass(CancelOperationInput::class)]
+final class CancelOperationInputTest extends TestCase
+{
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    public function testWithReturnsNewInstanceKeepingValues(): void
+    {
+        $input = $this->makeInput();
+        $copy = $input->with();
+
+        self::assertNotSame($input, $copy);
+        self::assertSame($input->operationContext, $copy->operationContext);
+        self::assertSame($input->cancelDetails, $copy->cancelDetails);
+    }
+
+    public function testWithOverridesOperationContextOnly(): void
+    {
+        $input = $this->makeInput();
+        $newContext = new OperationContext('other-service', 'other-operation', $this->env);
+
+        $copy = $input->with(operationContext: $newContext);
+
+        self::assertSame($newContext, $copy->operationContext);
+        self::assertSame($input->cancelDetails, $copy->cancelDetails);
+    }
+
+    public function testWithOverridesCancelDetailsOnly(): void
+    {
+        $input = $this->makeInput();
+        $newDetails = new OperationCancelDetails('other-token');
+
+        $copy = $input->with(cancelDetails: $newDetails);
+
+        self::assertSame($input->operationContext, $copy->operationContext);
+        self::assertSame($newDetails, $copy->cancelDetails);
+    }
+
+    private function makeInput(): CancelOperationInput
+    {
+        return new CancelOperationInput(
+            new OperationContext('service', 'operation', $this->env),
+            new OperationCancelDetails('operation-token'),
+        );
+    }
+}
diff --git a/tests/Nexus/Unit/Interceptor/StartOperationInputTest.php b/tests/Nexus/Unit/Interceptor/StartOperationInputTest.php
new file mode 100644
index 000000000..311d64d3b
--- /dev/null
+++ b/tests/Nexus/Unit/Interceptor/StartOperationInputTest.php
@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Interceptor;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use Temporal\Interceptor\NexusOperationInbound\StartOperationInput;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+
+#[CoversClass(StartOperationInput::class)]
+final class StartOperationInputTest extends TestCase
+{
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    public function testWithReturnsNewInstanceKeepingValues(): void
+    {
+        $input = $this->makeInput();
+        $copy = $input->with();
+
+        self::assertNotSame($input, $copy);
+        self::assertSame($input->operationContext, $copy->operationContext);
+        self::assertSame($input->startDetails, $copy->startDetails);
+        self::assertSame($input->input, $copy->input);
+    }
+
+    public function testWithOverridesOperationContextOnly(): void
+    {
+        $input = $this->makeInput();
+        $newContext = new OperationContext('other-service', 'other-operation', $this->env);
+
+        $copy = $input->with(operationContext: $newContext);
+
+        self::assertSame($newContext, $copy->operationContext);
+        self::assertSame($input->startDetails, $copy->startDetails);
+        self::assertSame($input->input, $copy->input);
+    }
+
+    public function testWithOverridesStartDetailsOnly(): void
+    {
+        $input = $this->makeInput();
+        $newDetails = new OperationStartDetails('other-request-id');
+
+        $copy = $input->with(startDetails: $newDetails);
+
+        self::assertSame($input->operationContext, $copy->operationContext);
+        self::assertSame($newDetails, $copy->startDetails);
+        self::assertSame($input->input, $copy->input);
+    }
+
+    public function testWithOverridesInputOnly(): void
+    {
+        $input = $this->makeInput();
+
+        $copy = $input->with(input: 'changed');
+
+        self::assertSame($input->operationContext, $copy->operationContext);
+        self::assertSame($input->startDetails, $copy->startDetails);
+        self::assertSame('changed', $copy->input);
+    }
+
+    private function makeInput(): StartOperationInput
+    {
+        return new StartOperationInput(
+            new OperationContext('service', 'operation', $this->env),
+            new OperationStartDetails('request-id'),
+            'original-input',
+        );
+    }
+}
diff --git a/tests/Nexus/Unit/Internal/Failure/NexusFailureConverterTest.php b/tests/Nexus/Unit/Internal/Failure/NexusFailureConverterTest.php
new file mode 100644
index 000000000..a587e0e51
--- /dev/null
+++ b/tests/Nexus/Unit/Internal/Failure/NexusFailureConverterTest.php
@@ -0,0 +1,46 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Internal\Failure;
+
+use Temporal\Api\Enums\V1\NexusHandlerErrorRetryBehavior;
+use Temporal\Nexus\Exception\RetryBehavior;
+use Temporal\Nexus\Internal\Failure\NexusFailureConverter;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(NexusFailureConverter::class)]
+final class NexusFailureConverterTest extends TestCase
+{
+    /** @return iterable<string, array{0: RetryBehavior, 1: int}> */
+    public static function retryBehaviorMatrix(): iterable
+    {
+        yield 'Unspecified' => [
+            RetryBehavior::Unspecified,
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_UNSPECIFIED,
+        ];
+        yield 'Retryable' => [
+            RetryBehavior::Retryable,
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE,
+        ];
+        yield 'NonRetryable' => [
+            RetryBehavior::NonRetryable,
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE,
+        ];
+    }
+
+    #[DataProvider('retryBehaviorMatrix')]
+    public function testMapRetryBehavior(RetryBehavior $behavior, int $expectedProto): void
+    {
+        self::assertSame($expectedProto, NexusFailureConverter::mapRetryBehavior($behavior));
+    }
+}
diff --git a/tests/Nexus/Unit/Internal/HeadersTest.php b/tests/Nexus/Unit/Internal/HeadersTest.php
new file mode 100644
index 000000000..1d0139393
--- /dev/null
+++ b/tests/Nexus/Unit/Internal/HeadersTest.php
@@ -0,0 +1,50 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Internal;
+
+use Temporal\Nexus\Internal\Headers;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(Headers::class)]
+final class HeadersTest extends TestCase
+{
+    public function testNormalizeLowercasesKeys(): void
+    {
+        self::assertSame(
+            ['foo' => 'bar', 'baz' => 'qux'],
+            Headers::normalize(['FOO' => 'bar', 'Baz' => 'qux']),
+        );
+    }
+
+    public function testNormalizePreservesValueCase(): void
+    {
+        self::assertSame(
+            ['content-type' => 'Application/JSON'],
+            Headers::normalize(['Content-Type' => 'Application/JSON']),
+        );
+    }
+
+    public function testNormalizeEmpty(): void
+    {
+        self::assertSame([], Headers::normalize([]));
+    }
+
+    public function testNormalizeLastValueWinsOnCaseCollision(): void
+    {
+        // Same key with different casing — last one wins after normalization.
+        self::assertSame(
+            ['x-custom' => 'second'],
+            Headers::normalize(['X-Custom' => 'first', 'x-custom' => 'second']),
+        );
+    }
+}
diff --git a/tests/Nexus/Unit/LinkParserTest.php b/tests/Nexus/Unit/LinkParserTest.php
new file mode 100644
index 000000000..1987368c3
--- /dev/null
+++ b/tests/Nexus/Unit/LinkParserTest.php
@@ -0,0 +1,160 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit;
+
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\NexusException;
+use Temporal\Nexus\Link;
+use Temporal\Nexus\LinkParser;
+use Temporal\Tests\Nexus\Support\ExceptionAssertions;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(LinkParser::class)]
+#[UsesClass(Link::class)]
+#[UsesClass(HandlerException::class)]
+#[UsesClass(NexusException::class)]
+#[UsesClass(ErrorType::class)]
+final class LinkParserTest extends TestCase
+{
+    use ExceptionAssertions;
+
+    public function testFromRawNullReturnsEmpty(): void
+    {
+        self::assertSame([], LinkParser::fromRaw(null));
+    }
+
+    public function testFromRawEmptyArrayReturnsEmpty(): void
+    {
+        self::assertSame([], LinkParser::fromRaw([]));
+    }
+
+    public function testFromRawHappyPath(): void
+    {
+        $links = LinkParser::fromRaw([
+            ['url' => 'https://a/1', 'type' => 'com.example.A'],
+            ['url' => 'https://a/2', 'type' => 'com.example.B'],
+        ]);
+
+        self::assertCount(2, $links);
+        self::assertContainsOnlyInstancesOf(Link::class, $links);
+        self::assertSame('https://a/1', $links[0]->uri);
+        self::assertSame('com.example.A', $links[0]->type);
+        self::assertSame('https://a/2', $links[1]->uri);
+        self::assertSame('com.example.B', $links[1]->type);
+    }
+
+    public function testFromRawRejectsNonArrayPayload(): void
+    {
+        $e = self::assertThrown(HandlerException::class, static fn() => LinkParser::fromRaw('not-an-array'));
+
+        self::assertSame(ErrorType::BadRequest, $e->errorType);
+        self::assertStringContainsString('must be an array', $e->getMessage());
+    }
+
+    public function testFromRawRejectsNonObjectEntry(): void
+    {
+        $e = self::assertThrown(
+            HandlerException::class,
+            static fn() => LinkParser::fromRaw([['url' => 'https://a', 'type' => 't'], 'bad']),
+        );
+
+        self::assertSame(ErrorType::BadRequest, $e->errorType);
+        self::assertStringContainsString('index 1 is not an object', $e->getMessage());
+    }
+
+    public function testFromRawRejectsMissingUrl(): void
+    {
+        $e = self::assertThrown(HandlerException::class, static fn() => LinkParser::fromRaw([['type' => 't']]));
+
+        self::assertSame(ErrorType::BadRequest, $e->errorType);
+        self::assertStringContainsString('"url"', $e->getMessage());
+    }
+
+    public function testFromRawRejectsMissingType(): void
+    {
+        $e = self::assertThrown(HandlerException::class, static fn() => LinkParser::fromRaw([['url' => 'https://a']]));
+
+        self::assertSame(ErrorType::BadRequest, $e->errorType);
+        self::assertStringContainsString('"type"', $e->getMessage());
+    }
+
+    public function testFromRawRejectsEmptyUrl(): void
+    {
+        $this->expectException(HandlerException::class);
+        $this->expectExceptionMessage('Nexus link at index 0 has missing or empty "url"');
+        LinkParser::fromRaw([['url' => '', 'type' => 't']]);
+    }
+
+    public function testFromRawRejectsNonStringUrl(): void
+    {
+        $this->expectException(HandlerException::class);
+        $this->expectExceptionMessage('Nexus link at index 0 has missing or empty "url"');
+        LinkParser::fromRaw([['url' => 42, 'type' => 't']]);
+    }
+
+    public function testFromRawRejectsEmptyType(): void
+    {
+        $this->expectException(HandlerException::class);
+        $this->expectExceptionMessage('Nexus link at index 0 has missing or empty "type"');
+        LinkParser::fromRaw([['url' => 'https://a', 'type' => '']]);
+    }
+
+    public function testFromRawStringIndexInError(): void
+    {
+        $this->expectException(HandlerException::class);
+        $this->expectExceptionMessage("Nexus link at index 'key1' is not an object (got string)");
+        LinkParser::fromRaw(['key1' => 'bad']);
+    }
+
+    public function testFromProtoEmpty(): void
+    {
+        self::assertSame([], LinkParser::fromProto([]));
+    }
+
+    public function testFromProtoHappyPath(): void
+    {
+        $proto = (new \Temporal\Api\Nexus\V1\Link())
+            ->setUrl('https://p/1')
+            ->setType('com.example.P');
+
+        $links = LinkParser::fromProto([$proto, $proto]);
+
+        self::assertCount(2, $links);
+        self::assertSame('https://p/1', $links[0]->uri);
+        self::assertSame('com.example.P', $links[0]->type);
+    }
+
+    public function testFromProtoRejectsEmptyUrl(): void
+    {
+        $proto = (new \Temporal\Api\Nexus\V1\Link())->setType('com.example.P');
+
+        $this->expectException(HandlerException::class);
+        $this->expectExceptionMessage('Nexus link at proto index 0 has missing or empty "url"');
+        LinkParser::fromProto([$proto]);
+    }
+
+    public function testFromProtoIndexAdvances(): void
+    {
+        $good = (new \Temporal\Api\Nexus\V1\Link())
+            ->setUrl('https://ok')
+            ->setType('t');
+        $bad = (new \Temporal\Api\Nexus\V1\Link())
+            ->setUrl('https://ok');
+
+        $this->expectException(HandlerException::class);
+        $this->expectExceptionMessage('Nexus link at proto index 2 has missing or empty "type"');
+        LinkParser::fromProto([$good, $good, $bad]);
+    }
+}
diff --git a/tests/Nexus/Unit/LinkTest.php b/tests/Nexus/Unit/LinkTest.php
new file mode 100644
index 000000000..7d8bf080b
--- /dev/null
+++ b/tests/Nexus/Unit/LinkTest.php
@@ -0,0 +1,69 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Link;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(Link::class)]
+final class LinkTest extends TestCase
+{
+    public function testConstruction(): void
+    {
+        $link = new Link('http://example.com?k=v', 'com.example.MyResource');
+        self::assertSame('http://example.com?k=v', $link->uri);
+        self::assertSame('com.example.MyResource', $link->type);
+    }
+
+    public function testToString(): void
+    {
+        $link = new Link('http://example.com', 'MyType');
+        $str = (string) $link;
+        self::assertStringContainsString('http://example.com', $str);
+        self::assertStringContainsString('MyType', $str);
+    }
+
+    public function testEquality(): void
+    {
+        $link1 = new Link('http://a.com', 'TypeA');
+        $link2 = new Link('http://a.com', 'TypeA');
+        $link3 = new Link('http://b.com', 'TypeB');
+
+        self::assertEquals($link1, $link2);
+        self::assertNotEquals($link1, $link3);
+    }
+
+    // ── Constructor validation ──────────────────────────────────────
+
+    public function testEmptyUriRejected(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Link URI must not be empty');
+        new Link('', 'some-type');
+    }
+
+    public function testEmptyTypeRejected(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Link type must not be empty');
+        new Link('http://example.com', '');
+    }
+
+    public function testConstructorAcceptsRelativeUri(): void
+    {
+        // The plain constructor is intentionally permissive — only non-emptiness is enforced.
+        $link = new Link('/just-a-path', 'some-type');
+        self::assertSame('/just-a-path', $link->uri);
+    }
+}
diff --git a/tests/Nexus/Unit/NexusFacadeTest.php b/tests/Nexus/Unit/NexusFacadeTest.php
new file mode 100644
index 000000000..bf4df67ac
--- /dev/null
+++ b/tests/Nexus/Unit/NexusFacadeTest.php
@@ -0,0 +1,161 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit;
+
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\Handler\Internal\ServiceHandler;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\NexusOperationContext;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+use Temporal\Tests\Nexus\Support\BindNexusService;
+use Temporal\Tests\Nexus\Support\EncodesValues;
+use Temporal\Tests\Nexus\Support\ExceptionAssertions;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[Service(name: 'FacadeProbeService')]
+final class FacadeProbeService
+{
+    public ?OperationCancelDetails $capturedCancelDetails = null;
+
+    #[Operation]
+    public function probeCancelDetails(string $input): string
+    {
+        Nexus::getCancelDetails();
+        return 'unreachable';
+    }
+
+    #[Operation]
+    public function probeWorkflowClient(string $input): string
+    {
+        Nexus::getWorkflowClient();
+        return 'unreachable';
+    }
+
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function startJob(): FacadeJobHandler
+    {
+        return new FacadeJobHandler($this);
+    }
+}
+
+final class FacadeJobHandler implements OperationHandlerInterface
+{
+    public function __construct(
+        private readonly FacadeProbeService $service,
+    ) {}
+
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        return OperationStartResult::async(new OperationInfo("job-{$param}", OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {
+        $this->service->capturedCancelDetails = Nexus::getCancelDetails();
+    }
+}
+
+#[CoversClass(Nexus::class)]
+final class NexusFacadeTest extends TestCase
+{
+    use BindNexusService;
+    use EncodesValues;
+    use ExceptionAssertions;
+
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    public function testGetCancelDetailsOutsideAnyDispatchThrows(): void
+    {
+        $e = self::assertThrown(\LogicException::class, static fn() => Nexus::getCancelDetails());
+
+        self::assertStringContainsString('only inside a Nexus operation handler', $e->getMessage());
+    }
+
+    public function testGetCancelDetailsDuringStartDispatchThrows(): void
+    {
+        $handler = $this->handler();
+
+        $e = self::assertThrown(\LogicException::class, fn() => $handler->startOperation(
+            $this->context('probeCancelDetails'),
+            new OperationStartDetails(requestId: 'r1'),
+            self::encode('x'),
+            null,
+            new NexusOperationContext(),
+        ));
+
+        self::assertStringContainsString('outside a cancel-operation dispatch', $e->getMessage());
+    }
+
+    public function testGetCancelDetailsAvailableInsideCancelDispatch(): void
+    {
+        $service = new FacadeProbeService();
+        $this->handler($service)->cancelOperation(
+            $this->context('startJob'),
+            new OperationCancelDetails(operationToken: 'job-42'),
+            null,
+            new NexusOperationContext(),
+        );
+
+        self::assertNotNull($service->capturedCancelDetails);
+        self::assertSame('job-42', $service->capturedCancelDetails->operationToken);
+    }
+
+    public function testGetWorkflowClientWithoutClientThrows(): void
+    {
+        $handler = $this->handler();
+
+        $e = self::assertThrown(\LogicException::class, fn() => $handler->startOperation(
+            $this->context('probeWorkflowClient'),
+            new OperationStartDetails(requestId: 'r1'),
+            self::encode('x'),
+            null,
+            new NexusOperationContext(),
+        ));
+
+        self::assertStringContainsString('Nexus::getWorkflowClient() requires a WorkflowClient', $e->getMessage());
+    }
+
+    private function handler(?FacadeProbeService $service = null): ServiceHandler
+    {
+        return ServiceHandler::create(
+            dataConverter: self::dataConverter(),
+            instances: [self::bindNexusService($service ?? new FacadeProbeService())],
+        );
+    }
+
+    private function context(string $operation): OperationContext
+    {
+        return new OperationContext(service: 'FacadeProbeService', operation: $operation, env: $this->env);
+    }
+}
diff --git a/tests/Nexus/Unit/NexusOperationContextTest.php b/tests/Nexus/Unit/NexusOperationContextTest.php
new file mode 100644
index 000000000..ed0c1e7eb
--- /dev/null
+++ b/tests/Nexus/Unit/NexusOperationContextTest.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit;
+
+use Temporal\Nexus\NexusOperationContext;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(NexusOperationContext::class)]
+final class NexusOperationContextTest extends TestCase
+{
+    public function testConstructStoresFields(): void
+    {
+        $ctx = new NexusOperationContext('ns', 'tq');
+
+        self::assertSame('ns', $ctx->namespace);
+        self::assertSame('tq', $ctx->taskQueue);
+    }
+
+    public function testDefaultsAreEmpty(): void
+    {
+        $ctx = new NexusOperationContext();
+
+        self::assertSame('', $ctx->namespace);
+        self::assertSame('', $ctx->taskQueue);
+    }
+}
diff --git a/tests/Nexus/Unit/NexusOperationTypesTest.php b/tests/Nexus/Unit/NexusOperationTypesTest.php
new file mode 100644
index 000000000..2984664ac
--- /dev/null
+++ b/tests/Nexus/Unit/NexusOperationTypesTest.php
@@ -0,0 +1,101 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit;
+
+use Spiral\Attributes\AttributeReader;
+use Temporal\Internal\Declaration\Prototype\NexusOperationPrototype;
+use Temporal\Internal\Declaration\Prototype\NexusServicePrototype;
+use Temporal\Internal\Declaration\Reader\NexusServiceReader;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Tests\Nexus\Fixtures\Service\IntersectionInputServiceInterface;
+use Temporal\Tests\Nexus\Fixtures\Service\NullableInputServiceInterface;
+use Temporal\Tests\Nexus\Fixtures\Service\UnionInputServiceInterface;
+use Temporal\Tests\Nexus\Fixtures\Service\UnionOutputServiceInterface;
+use Temporal\Tests\Nexus\Fixtures\Service\UntypedInputServiceInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(NexusOperationPrototype::class)]
+#[UsesClass(NexusServiceReader::class)]
+#[UsesClass(NexusServicePrototype::class)]
+final class NexusOperationTypesTest extends TestCase
+{
+    public function testAcceptsNullableInputAndOutputType(): void
+    {
+        $proto = self::reader()->fromClass(NullableInputServiceInterface::class);
+
+        self::assertArrayHasKey('operation', $proto->getOperations());
+        $op = $proto->getOperations()['operation'];
+        self::assertSame('string', $op->inputType->getName());
+        self::assertTrue($op->inputType->allowsNull());
+        self::assertSame('string', $op->outputType->getName());
+        self::assertTrue($op->outputType->allowsNull());
+    }
+
+    public function testUnionInputFallsBackToMixed(): void
+    {
+        $proto = self::reader()->fromClass(UnionInputServiceInterface::class);
+
+        self::assertSame('mixed', $proto->getOperations()['operation']->inputType->getName());
+    }
+
+    public function testUnionOutputFallsBackToMixed(): void
+    {
+        $proto = self::reader()->fromClass(UnionOutputServiceInterface::class);
+
+        self::assertSame('mixed', $proto->getOperations()['operation']->outputType->getName());
+    }
+
+    public function testIntersectionInputFallsBackToMixed(): void
+    {
+        $proto = self::reader()->fromClass(IntersectionInputServiceInterface::class);
+
+        self::assertSame('mixed', $proto->getOperations()['operation']->inputType->getName());
+    }
+
+    public function testUntypedParameterFallsBackToMixed(): void
+    {
+        $proto = self::reader()->fromClass(UntypedInputServiceInterface::class);
+
+        $op = $proto->getOperations()['operation'];
+        self::assertSame('mixed', $op->inputType->getName());
+        self::assertSame('string', $op->outputType->getName());
+    }
+
+    public function testRejectsTooManyParameters(): void
+    {
+        $iface = new #[\Temporal\Nexus\Attribute\Service] class {
+            #[\Temporal\Nexus\Attribute\Operation]
+            public function bad(string $a, string $b): void {}
+        };
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Can have no more than one parameter');
+        self::reader()->fromClass($iface::class);
+    }
+
+    public function testRejectsStaticOperation(): void
+    {
+        $iface = new #[\Temporal\Nexus\Attribute\Service] class {
+            #[\Temporal\Nexus\Attribute\Operation]
+            public static function staticOp(): void {}
+        };
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Cannot be static');
+        self::reader()->fromClass($iface::class);
+    }
+
+    private static function reader(): NexusServiceReader
+    {
+        return new NexusServiceReader(new AttributeReader());
+    }
+}
diff --git a/tests/Nexus/Unit/NexusOutboundInterceptorTest.php b/tests/Nexus/Unit/NexusOutboundInterceptorTest.php
new file mode 100644
index 000000000..5cb062cab
--- /dev/null
+++ b/tests/Nexus/Unit/NexusOutboundInterceptorTest.php
@@ -0,0 +1,121 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use Temporal\Interceptor\NexusOperationOutbound\GetInfoInput;
+use Temporal\Interceptor\NexusOperationOutboundCallsInterceptor;
+use Temporal\Interceptor\Trait\NexusOperationOutboundCallsInterceptorTrait;
+use Temporal\Internal\Interceptor\Pipeline;
+use Temporal\Internal\Nexus\NexusContext;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\NexusOperationContext;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+
+#[CoversClass(Nexus::class)]
+#[CoversClass(NexusOperationOutboundCallsInterceptor::class)]
+final class NexusOutboundInterceptorTest extends TestCase
+{
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    protected function tearDown(): void
+    {
+        Nexus::setCurrentContext(null);
+        parent::tearDown();
+    }
+
+    public function testGetInfoPassesThroughInterceptorChain(): void
+    {
+        $log = [];
+        $record = static function (string $name) use (&$log): NexusOperationOutboundCallsInterceptor {
+            return new class($name, $log) implements NexusOperationOutboundCallsInterceptor {
+                use NexusOperationOutboundCallsInterceptorTrait;
+
+                /** @param list<string> $log */
+                public function __construct(
+                    private readonly string $name,
+                    private array &$log,
+                ) {}
+
+                public function getInfo(GetInfoInput $input, callable $next): NexusOperationContext
+                {
+                    $this->log[] = "enter:{$this->name}";
+                    $info = $next($input);
+                    $this->log[] = "exit:{$this->name}";
+                    return $info;
+                }
+            };
+        };
+
+        $info = new NexusOperationContext('ns', 'tq');
+        Nexus::setCurrentContext(new NexusContext(
+            current: new OperationContext(service: 'svc', operation: 'op', env: $this->env),
+            operation: $info,
+            outboundPipeline: Pipeline::prepare([$record('A'), $record('B')]),
+        ));
+
+        $result = Nexus::getOperationContext();
+
+        self::assertSame($info, $result);
+        self::assertSame(['enter:A', 'enter:B', 'exit:B', 'exit:A'], $log);
+    }
+
+    public function testInterceptorCanRewriteReturnedInfo(): void
+    {
+        $rewriting = new class implements NexusOperationOutboundCallsInterceptor {
+            use NexusOperationOutboundCallsInterceptorTrait;
+
+            public function getInfo(GetInfoInput $input, callable $next): NexusOperationContext
+            {
+                $next($input);
+                return new NexusOperationContext('rewritten-ns', 'rewritten-tq');
+            }
+        };
+
+        Nexus::setCurrentContext(new NexusContext(
+            current: new OperationContext(service: 'svc', operation: 'op', env: $this->env),
+            operation: new NexusOperationContext('ns', 'tq'),
+            outboundPipeline: Pipeline::prepare([$rewriting]),
+        ));
+
+        $result = Nexus::getOperationContext();
+
+        self::assertSame('rewritten-ns', $result->namespace);
+        self::assertSame('rewritten-tq', $result->taskQueue);
+    }
+
+    public function testGetInfoReturnsInfoDirectlyWithoutPipeline(): void
+    {
+        $info = new NexusOperationContext('ns', 'tq');
+        Nexus::setCurrentContext(new NexusContext(
+            current: new OperationContext(service: 'svc', operation: 'op', env: $this->env),
+            operation: $info,
+        ));
+
+        self::assertSame($info, Nexus::getOperationContext());
+    }
+
+    public function testGetInfoThrowsOutsideDispatch(): void
+    {
+        $this->expectException(\LogicException::class);
+        Nexus::getOperationContext();
+    }
+}
diff --git a/tests/Nexus/Unit/NexusServiceReaderTest.php b/tests/Nexus/Unit/NexusServiceReaderTest.php
new file mode 100644
index 000000000..9a7a6b65d
--- /dev/null
+++ b/tests/Nexus/Unit/NexusServiceReaderTest.php
@@ -0,0 +1,204 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit;
+
+use Spiral\Attributes\AttributeReader;
+use Temporal\Internal\Declaration\Prototype\NexusServicePrototype;
+use Temporal\Internal\Declaration\Reader\NexusServiceReader;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Exception\NexusException;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\AmbiguousServiceImpl;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\DiamondFinalInterface;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\FactoryWithParametersService;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\EmptyService;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\InvalidAsyncReturnTypeService;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\NullableAsyncReturnTypeService;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\InvalidServiceDuplicateOperation;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\InvalidServiceNoAnnotation;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\NonPublicOperationService;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\InvalidServiceWithOperations;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\InvalidSubService;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\OperationOverrideMismatchService;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\ServiceWithPlainParentInterface;
+use Temporal\Tests\Nexus\Fixtures\ServiceDefinition\ValidServiceWithOperations;
+use Temporal\Tests\Nexus\Fixtures\ServiceImplInstance\ServiceAsClass;
+use Temporal\Tests\Nexus\Fixtures\ServiceHandler\ManualTokenService;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(NexusServiceReader::class)]
+#[UsesClass(NexusServicePrototype::class)]
+final class NexusServiceReaderTest extends TestCase
+{
+    public function testInvalidServiceNoAnnotation(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Missing #[Service] attribute');
+        self::reader()->fromClass(InvalidServiceNoAnnotation::class);
+    }
+
+    public function testServiceAttributeOnClassIsAccepted(): void
+    {
+        $proto = self::reader()->fromClass(ServiceAsClass::class);
+
+        self::assertSame('ServiceAsClass', $proto->getID());
+        self::assertCount(1, $proto->getOperations());
+        self::assertArrayHasKey('classOperation', $proto->getOperations());
+        self::assertSame('string', $proto->getOperations()['classOperation']->inputType->getName());
+        self::assertSame('string', $proto->getOperations()['classOperation']->outputType->getName());
+    }
+
+    public function testMultipleServiceInterfacesAreAmbiguous(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('implements multiple #[Service] types');
+        self::reader()->fromClass(AmbiguousServiceImpl::class);
+    }
+
+    public function testInvalidSubServiceNameMismatch(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('does not match the expected name on the contract');
+        self::reader()->fromClass(InvalidSubService::class);
+    }
+
+    public function testInvalidServiceWithOperations(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('operation(s) were invalid');
+        self::reader()->fromClass(InvalidServiceWithOperations::class);
+    }
+
+    public function testNonPublicOperationMethodIsRejected(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Must be public');
+        self::reader()->fromClass(NonPublicOperationService::class);
+    }
+
+    public function testInvalidServiceDuplicateOperation(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("Multiple operations named 'duplicateWhenNameOverridden1'");
+        self::reader()->fromClass(InvalidServiceDuplicateOperation::class);
+    }
+
+    public function testAsyncOperationWithInvalidReturnTypeIsRejected(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('must declare a `Temporal\Nexus\WorkflowHandle` return type or return an');
+        self::reader()->fromClass(InvalidAsyncReturnTypeService::class);
+    }
+
+    public function testAsyncOperationWithNullableReturnTypeIsRejected(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('must declare a `Temporal\Nexus\WorkflowHandle` return type or return an');
+        self::reader()->fromClass(NullableAsyncReturnTypeService::class);
+    }
+
+    public function testAsyncOperationWithHandlerFactoryReturnTypeIsAccepted(): void
+    {
+        $proto = self::reader()->fromClass(ManualTokenService::class);
+
+        $operations = $proto->getOperations();
+        self::assertTrue($operations['startExternal']->async);
+        self::assertTrue($operations['startUncancellable']->async);
+    }
+
+    public function testFactoryInputTypeComesFromAttribute(): void
+    {
+        $proto = self::reader()->fromClass(ManualTokenService::class);
+
+        self::assertSame('string', $proto->getOperations()['startExternal']->inputType->getName());
+    }
+
+    public function testFactoryWithParametersIsRejected(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('must declare no parameters');
+        self::reader()->fromClass(FactoryWithParametersService::class);
+    }
+
+    public function testValidService(): void
+    {
+        $proto = self::reader()->fromClass(ValidServiceWithOperations::class);
+
+        self::assertSame('ValidServiceWithOperations', $proto->getID());
+
+        self::assertOperation($proto, 'superMethod',           input: 'void',   output: 'void');
+        self::assertOperation($proto, 'superInterfaceOnly',    input: 'void',   output: 'void');
+        self::assertOperation($proto, 'noParamNoReturn',       input: 'void',   output: 'void');
+        self::assertOperation($proto, 'noParamSingleReturn',   input: 'void',   output: 'string');
+        self::assertOperation($proto, 'singleParamNoReturn',   input: 'string', output: 'void');
+        self::assertOperation($proto, 'singleParamSingleReturn', input: 'string', output: 'string');
+        self::assertOperation($proto, 'custom-name',           input: 'void',   output: 'void');
+    }
+
+    public function testEmptyServiceRejected(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('No operations defined');
+        self::reader()->fromClass(EmptyService::class);
+    }
+
+    public function testParentInterfaceWithoutServiceAttributeIsSkipped(): void
+    {
+        $proto = self::reader()->fromClass(ServiceWithPlainParentInterface::class);
+        self::assertSame('ServiceWithPlainParentInterface', $proto->getID());
+        self::assertArrayHasKey('ownOperation', $proto->getOperations());
+        self::assertArrayHasKey('inheritedOperation', $proto->getOperations());
+    }
+
+    public function testOperationOverrideWithMismatchingNameIsRejected(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('mismatches against another operation');
+        self::reader()->fromClass(OperationOverrideMismatchService::class);
+    }
+
+    public function testDiamondInheritanceIsHandled(): void
+    {
+        $proto = self::reader()->fromClass(DiamondFinalInterface::class);
+        self::assertSame('Diamond', $proto->getID());
+        self::assertCount(1, $proto->getOperations());
+        self::assertArrayHasKey('commonOp', $proto->getOperations());
+    }
+
+    private static function reader(): NexusServiceReader
+    {
+        return new NexusServiceReader(new AttributeReader());
+    }
+
+    private static function assertOperation(
+        NexusServicePrototype $proto,
+        string $name,
+        string $input,
+        string $output,
+    ): void {
+        $operations = $proto->getOperations();
+        self::assertArrayHasKey($name, $operations);
+        $op = $operations[$name];
+        self::assertSame($name, $op->name);
+        self::assertSame($input, self::typeName($op->inputType), "inputType for {$name}");
+        self::assertSame($output, self::typeName($op->outputType), "outputType for {$name}");
+    }
+
+    private static function typeName(\Temporal\DataConverter\Type $type): string
+    {
+        $name = $type->getName();
+        return $type->allowsNull() && !\in_array($name, ['mixed', 'void', 'null'], true)
+            ? '?' . $name
+            : $name;
+    }
+}
diff --git a/tests/Nexus/Unit/OperationExceptionTest.php b/tests/Nexus/Unit/OperationExceptionTest.php
new file mode 100644
index 000000000..b2b88f721
--- /dev/null
+++ b/tests/Nexus/Unit/OperationExceptionTest.php
@@ -0,0 +1,89 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit;
+
+use Temporal\Nexus\Exception\OperationException;
+use Temporal\Nexus\OperationState;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(OperationException::class)]
+final class OperationExceptionTest extends TestCase
+{
+    public function testFailureWithMessage(): void
+    {
+        $ex = OperationException::failed('Test failure');
+
+        self::assertSame('Test failure', $ex->getMessage());
+        self::assertNull($ex->getPrevious());
+        self::assertSame(OperationState::Failed, $ex->state);
+    }
+
+    public function testFailureWithCause(): void
+    {
+        $cause = new \RuntimeException('Root cause');
+        $ex = OperationException::failedFromCause($cause);
+
+        self::assertSame($cause, $ex->getPrevious());
+        self::assertSame(OperationState::Failed, $ex->state);
+    }
+
+    public function testFailureWithMessageAndCause(): void
+    {
+        $cause = new \RuntimeException('Root cause');
+        $ex = OperationException::failed('Custom message', $cause);
+
+        self::assertSame('Custom message', $ex->getMessage());
+        self::assertSame($cause, $ex->getPrevious());
+        self::assertSame(OperationState::Failed, $ex->state);
+    }
+
+    public function testCanceledWithMessage(): void
+    {
+        $ex = OperationException::canceled('Test cancellation');
+
+        self::assertSame('Test cancellation', $ex->getMessage());
+        self::assertNull($ex->getPrevious());
+        self::assertSame(OperationState::Canceled, $ex->state);
+    }
+
+    public function testCanceledWithCause(): void
+    {
+        $cause = new \RuntimeException('Cancellation reason');
+        $ex = OperationException::canceledFromCause($cause);
+
+        self::assertSame($cause, $ex->getPrevious());
+        self::assertSame(OperationState::Canceled, $ex->state);
+    }
+
+    public function testCanceledWithMessageAndCause(): void
+    {
+        $cause = new \RuntimeException('Cancellation reason');
+        $ex = OperationException::canceled('Custom cancellation message', $cause);
+
+        self::assertSame('Custom cancellation message', $ex->getMessage());
+        self::assertSame($cause, $ex->getPrevious());
+        self::assertSame(OperationState::Canceled, $ex->state);
+    }
+
+    public function testExceptionChaining(): void
+    {
+        $rootCause = new \Exception('Root cause');
+        $intermediateCause = new \RuntimeException('Intermediate', 0, $rootCause);
+        $ex = OperationException::failed('Operation failed', $intermediateCause);
+
+        self::assertSame('Operation failed', $ex->getMessage());
+        self::assertSame($intermediateCause, $ex->getPrevious());
+        self::assertSame($rootCause, $ex->getPrevious()->getPrevious());
+        self::assertSame(OperationState::Failed, $ex->state);
+    }
+}
diff --git a/tests/Nexus/Unit/OperationInfoTest.php b/tests/Nexus/Unit/OperationInfoTest.php
new file mode 100644
index 000000000..7544496d5
--- /dev/null
+++ b/tests/Nexus/Unit/OperationInfoTest.php
@@ -0,0 +1,58 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+use Temporal\Nexus\Validation\OperationTokenValidator;
+use Temporal\Nexus\Validation\PrintableAsciiValidator;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(OperationInfo::class)]
+#[UsesClass(OperationTokenValidator::class)]
+#[UsesClass(PrintableAsciiValidator::class)]
+#[UsesClass(InvalidArgumentException::class)]
+final class OperationInfoTest extends TestCase
+{
+    public function testConstructsWithTokenAndState(): void
+    {
+        $info = new OperationInfo('tok-1', OperationState::Running);
+
+        self::assertSame('tok-1', $info->token);
+        self::assertSame(OperationState::Running, $info->state);
+    }
+
+    public function testCarriesEachState(): void
+    {
+        foreach (OperationState::cases() as $state) {
+            $info = new OperationInfo('t', $state);
+            self::assertSame($state, $info->state);
+        }
+    }
+
+    public function testRejectsEmptyToken(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Operation Token must not be empty');
+        new OperationInfo('', OperationState::Succeeded);
+    }
+
+    public function testRejectsInvalidTokenBytes(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Operation Token must contain only printable non-whitespace ASCII (0x21–0x7E); got');
+        new OperationInfo("bad\ntoken", OperationState::Failed);
+    }
+}
diff --git a/tests/Nexus/Unit/OperationStateTest.php b/tests/Nexus/Unit/OperationStateTest.php
new file mode 100644
index 000000000..4e253dd78
--- /dev/null
+++ b/tests/Nexus/Unit/OperationStateTest.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit;
+
+use Temporal\Nexus\OperationState;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(OperationState::class)]
+final class OperationStateTest extends TestCase
+{
+    public function testAllStatesUseSpecLowercaseValues(): void
+    {
+        // Values must match https://github.com/nexus-rpc/api/blob/main/SPEC.md
+        // which requires lowercase strings on the wire.
+        self::assertSame('running', OperationState::Running->value);
+        self::assertSame('succeeded', OperationState::Succeeded->value);
+        self::assertSame('failed', OperationState::Failed->value);
+        self::assertSame('canceled', OperationState::Canceled->value);
+    }
+
+    public function testFromString(): void
+    {
+        self::assertSame(OperationState::Running, OperationState::from('running'));
+        self::assertSame(OperationState::Failed, OperationState::from('failed'));
+    }
+}
diff --git a/tests/Nexus/Unit/Validation/OperationNameValidatorTest.php b/tests/Nexus/Unit/Validation/OperationNameValidatorTest.php
new file mode 100644
index 000000000..3b150e907
--- /dev/null
+++ b/tests/Nexus/Unit/Validation/OperationNameValidatorTest.php
@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Validation;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Validation\OperationNameValidator;
+use Temporal\Nexus\Validation\PrintableAsciiValidator;
+use Temporal\Nexus\Validation\ReservedPrefixValidator;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(OperationNameValidator::class)]
+#[UsesClass(PrintableAsciiValidator::class)]
+#[UsesClass(ReservedPrefixValidator::class)]
+final class OperationNameValidatorTest extends TestCase
+{
+    public function testRejectsEmpty(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Operation Name must not be empty');
+        OperationNameValidator::assert('');
+    }
+
+    public function testDelegatesToPrintableAsciiValidator(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Operation Name must contain only printable non-whitespace ASCII (0x21–0x7E); got');
+        OperationNameValidator::assert("bad\nname");
+    }
+
+    public function testRejectsReservedTemporalPrefix(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Operation Name "__temporal_internal" must not start with "__temporal_"');
+        OperationNameValidator::assert('__temporal_internal');
+    }
+}
diff --git a/tests/Nexus/Unit/Validation/OperationTokenValidatorTest.php b/tests/Nexus/Unit/Validation/OperationTokenValidatorTest.php
new file mode 100644
index 000000000..e0db01f4e
--- /dev/null
+++ b/tests/Nexus/Unit/Validation/OperationTokenValidatorTest.php
@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Validation;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Validation\OperationTokenValidator;
+use Temporal\Nexus\Validation\PrintableAsciiValidator;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(OperationTokenValidator::class)]
+#[UsesClass(PrintableAsciiValidator::class)]
+final class OperationTokenValidatorTest extends TestCase
+{
+    public function testRejectsEmpty(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Operation Token must not be empty');
+        OperationTokenValidator::assert('');
+    }
+
+    public function testDelegatesToPrintableAsciiValidator(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Operation Token must contain only printable non-whitespace ASCII (0x21–0x7E); got');
+        OperationTokenValidator::assert("bad\ntoken");
+    }
+}
diff --git a/tests/Nexus/Unit/Validation/PrintableAsciiValidatorTest.php b/tests/Nexus/Unit/Validation/PrintableAsciiValidatorTest.php
new file mode 100644
index 000000000..4a6474efc
--- /dev/null
+++ b/tests/Nexus/Unit/Validation/PrintableAsciiValidatorTest.php
@@ -0,0 +1,80 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Validation;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Validation\PrintableAsciiValidator;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(PrintableAsciiValidator::class)]
+final class PrintableAsciiValidatorTest extends TestCase
+{
+    public function testRejectsEmpty(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Thing must not be empty');
+        PrintableAsciiValidator::assert('', 'Thing');
+    }
+
+    public function testAcceptsPrintableAscii(): void
+    {
+        PrintableAsciiValidator::assert('hello-world.42_%', 'Thing');
+        PrintableAsciiValidator::assert('!~', 'Thing');
+        self::assertTrue(true);
+    }
+
+    public function testAcceptsFullPrintableRange(): void
+    {
+        $value = '';
+        for ($c = 0x21; $c <= 0x7E; $c++) {
+            $value .= \chr($c);
+        }
+
+        PrintableAsciiValidator::assert($value, 'Thing');
+
+        self::assertTrue(true);
+    }
+
+    public function testErrorMessageIncludesByteLengthAndOffset(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('got 6 bytes, first bad char at offset 2');
+        PrintableAsciiValidator::assert("ok\nbad", 'Thing');
+    }
+
+    /**
+     * @return iterable<string, array{string, int}>
+     */
+    public static function badCharProvider(): iterable
+    {
+        yield 'leading space'   => [' a', 0];
+        yield 'embedded space'  => ['a b', 1];
+        yield 'tab'             => ["a\tb", 1];
+        yield 'newline'         => ["a\nb", 1];
+        yield 'carriage return' => ["a\rb", 1];
+        yield 'null byte'       => ["a\0b", 1];
+        yield 'control 0x01'    => ["a\x01b", 1];
+        yield 'del'             => ["a\x7Fb", 1];
+        yield 'high byte'       => ["a\xFFb", 1];
+        yield 'utf-8 multibyte' => ['имя', 0];
+    }
+
+    #[DataProvider('badCharProvider')]
+    public function testRejectsNonPrintable(string $value, int $offset): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("first bad char at offset {$offset}");
+        PrintableAsciiValidator::assert($value, 'Thing');
+    }
+}
diff --git a/tests/Nexus/Unit/Validation/ServiceNameValidatorTest.php b/tests/Nexus/Unit/Validation/ServiceNameValidatorTest.php
new file mode 100644
index 000000000..a31fcc839
--- /dev/null
+++ b/tests/Nexus/Unit/Validation/ServiceNameValidatorTest.php
@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Nexus\Unit\Validation;
+
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Validation\PrintableAsciiValidator;
+use Temporal\Nexus\Validation\ReservedPrefixValidator;
+use Temporal\Nexus\Validation\ServiceNameValidator;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ServiceNameValidator::class)]
+#[UsesClass(PrintableAsciiValidator::class)]
+#[UsesClass(ReservedPrefixValidator::class)]
+final class ServiceNameValidatorTest extends TestCase
+{
+    public function testRejectsEmpty(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Service Name must not be empty');
+        ServiceNameValidator::assert('');
+    }
+
+    public function testDelegatesToPrintableAsciiValidator(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Service Name must contain only printable non-whitespace ASCII (0x21–0x7E); got');
+        ServiceNameValidator::assert("bad\nname");
+    }
+
+    public function testRejectsReservedTemporalPrefix(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Service Name "__temporal_internal" must not start with "__temporal_"');
+        ServiceNameValidator::assert('__temporal_internal');
+    }
+}
diff --git a/tests/Support/FrozenClock.php b/tests/Support/FrozenClock.php
new file mode 100644
index 000000000..1944f32f1
--- /dev/null
+++ b/tests/Support/FrozenClock.php
@@ -0,0 +1,43 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Support;
+
+use Psr\Clock\ClockInterface;
+
+/**
+ * In-memory PSR-20 clock for deterministic deadline tests.
+ *
+ * `advance()` moves time forward without touching the wall clock; `set()`
+ * jumps to an absolute moment. Lets tests exercise deadline-trip paths
+ * without `sleep`/`usleep`.
+ */
+final class FrozenClock implements ClockInterface
+{
+    public function __construct(
+        private \DateTimeImmutable $now = new \DateTimeImmutable('2026-01-01T00:00:00Z'),
+    ) {}
+
+    public function now(): \DateTimeImmutable
+    {
+        return $this->now;
+    }
+
+    public function advance(\DateInterval $interval): void
+    {
+        $this->now = $this->now->add($interval);
+    }
+
+    public function set(\DateTimeImmutable $moment): void
+    {
+        $this->now = $moment;
+    }
+}
diff --git a/tests/Unit/Client/WorkflowOptionsTestCase.php b/tests/Unit/Client/WorkflowOptionsTestCase.php
new file mode 100644
index 000000000..229cc8041
--- /dev/null
+++ b/tests/Unit/Client/WorkflowOptionsTestCase.php
@@ -0,0 +1,107 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Client;
+
+use Temporal\Client\WorkflowOptions;
+use Temporal\Tests\Unit\AbstractUnit;
+use Temporal\Workflow\CompletionCallback;
+
+/**
+ * Covers the Nexus-related additions to {@see WorkflowOptions} — `requestId`
+ * and `completionCallbacks`. The pre-existing builder methods are exercised
+ * indirectly through other suites; this case focuses on the new surface.
+ *
+ * @group unit
+ * @group client
+ */
+final class WorkflowOptionsTestCase extends AbstractUnit
+{
+    public function testRequestIdDefaultsToNull(): void
+    {
+        $options = new WorkflowOptions();
+
+        self::assertNull($options->requestId);
+    }
+
+    public function testWithRequestIdReturnsClone(): void
+    {
+        $original = new WorkflowOptions();
+        $updated = $original->withRequestId('req-1');
+
+        self::assertNull($original->requestId, 'original must not be mutated');
+        self::assertSame('req-1', $updated->requestId);
+        self::assertNotSame($original, $updated);
+    }
+
+    public function testWithRequestIdNullClearsOverride(): void
+    {
+        $options = (new WorkflowOptions())->withRequestId('req-1')->withRequestId(null);
+
+        self::assertNull($options->requestId);
+    }
+
+    public function testCompletionCallbacksDefaultEmpty(): void
+    {
+        $options = new WorkflowOptions();
+
+        self::assertSame([], $options->completionCallbacks);
+    }
+
+    public function testWithNexusCompletionCallbackAccumulates(): void
+    {
+        $options = (new WorkflowOptions())
+            ->withNexusCompletionCallback('https://callback.example/done', ['Nexus-Operation-Token' => 'tok-1'])
+            ->withNexusCompletionCallback('https://callback.example/other', []);
+
+        self::assertCount(2, $options->completionCallbacks);
+        foreach ($options->completionCallbacks as $cb) {
+            self::assertInstanceOf(CompletionCallback::class, $cb);
+        }
+
+        self::assertSame('https://callback.example/done', $options->completionCallbacks[0]->url);
+        self::assertSame(['Nexus-Operation-Token' => 'tok-1'], $options->completionCallbacks[0]->headers);
+
+        self::assertSame('https://callback.example/other', $options->completionCallbacks[1]->url);
+        self::assertSame([], $options->completionCallbacks[1]->headers);
+    }
+
+    public function testWithNexusCompletionCallbackKeepsOriginalUntouched(): void
+    {
+        $original = new WorkflowOptions();
+        $updated = $original->withNexusCompletionCallback('https://x', []);
+
+        self::assertSame([], $original->completionCallbacks);
+        self::assertCount(1, $updated->completionCallbacks);
+    }
+
+    public function testWithCompletionCallbacksReplacesList(): void
+    {
+        $options = (new WorkflowOptions())
+            ->withNexusCompletionCallback('https://a', [])
+            ->withCompletionCallbacks();
+
+        self::assertSame([], $options->completionCallbacks);
+    }
+
+    public function testWithCompletionCallbacksAcceptsValueObjectsDirectly(): void
+    {
+        $cb1 = new CompletionCallback('https://one.example', ['X-Token' => 't1']);
+        $cb2 = new CompletionCallback('https://two.example');
+
+        $options = (new WorkflowOptions())->withCompletionCallbacks($cb1, $cb2);
+
+        self::assertCount(2, $options->completionCallbacks);
+        self::assertSame($cb1, $options->completionCallbacks[0]);
+        self::assertSame($cb2, $options->completionCallbacks[1]);
+    }
+
+    public function testCompletionCallbackRejectsEmptyUrl(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('url must be a non-empty string');
+
+        new CompletionCallback('');
+    }
+}
diff --git a/tests/Unit/DTO/CompletionCallbackTestCase.php b/tests/Unit/DTO/CompletionCallbackTestCase.php
new file mode 100644
index 000000000..7df9a82bb
--- /dev/null
+++ b/tests/Unit/DTO/CompletionCallbackTestCase.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\DTO;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use Temporal\Internal\Nexus\NexusLinkConverter;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Link as NexusLink;
+use Temporal\Workflow\CompletionCallback;
+
+#[CoversClass(CompletionCallback::class)]
+final class CompletionCallbackTestCase extends TestCase
+{
+    public function testNoLinksByDefault(): void
+    {
+        $cb = new CompletionCallback('http://x');
+        self::assertSame([], $cb->links);
+    }
+
+    public function testEmptyUrlRejected(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        new CompletionCallback('');
+    }
+
+    public function testWithNexusLinksConvertsAndKeepsOnlyWorkflowEvent(): void
+    {
+        $uri = 'temporal:///namespaces/n/workflows/w/r/history'
+            . '?referenceType=EventReference&eventID=1&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $cb = CompletionCallback::fromNexusLinks(
+            'http://cb',
+            ['k' => 'v'],
+            [
+                new NexusLink($uri, NexusLinkConverter::TYPE_WORKFLOW_EVENT),
+                new NexusLink('https://custom/abc', 'custom.type'),
+            ],
+        );
+
+        self::assertSame('http://cb', $cb->url);
+        self::assertSame(['k' => 'v'], $cb->headers);
+        self::assertCount(1, $cb->links);
+    }
+
+    public function testWithNexusLinksThrowsOnMalformedUri(): void
+    {
+        $bad = 'https:///namespaces/n/workflows/w/r/history?referenceType=EventReference&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $this->expectException(InvalidArgumentException::class);
+        CompletionCallback::fromNexusLinks('http://cb', [], [new NexusLink($bad, NexusLinkConverter::TYPE_WORKFLOW_EVENT)]);
+    }
+}
diff --git a/tests/Unit/DTO/WorkflowOptionsTestCase.php b/tests/Unit/DTO/WorkflowOptionsTestCase.php
index 86057164e..f2683dc54 100644
--- a/tests/Unit/DTO/WorkflowOptionsTestCase.php
+++ b/tests/Unit/DTO/WorkflowOptionsTestCase.php
@@ -21,6 +21,8 @@
 use Temporal\Common\Uuid;
 use Temporal\Common\WorkflowIdConflictPolicy;
 use Temporal\DataConverter\DataConverter;
+use Temporal\Internal\Nexus\NexusLinkConverter;
+use Temporal\Nexus\Link as NexusLink;
 
 class WorkflowOptionsTestCase extends AbstractDTOMarshalling
 {
@@ -58,7 +60,14 @@ public function testMarshalling(): void
         ];
 
         $result = $this->marshal($dto);
-        unset($result['typedSearchAttributes']);
+        unset(
+            $result['typedSearchAttributes'],
+            // Nexus-specific overrides; not marshalled to Go.
+            $result['requestId'],
+            $result['completionCallbacks'],
+            $result['onConflictOptions'],
+            $result['links'],
+        );
 
         $this->assertSame($expected, $result);
     }
@@ -244,6 +253,24 @@ public function testSetTypedSearchAttributesCasting(): void
         $this->assertCount(1, $result->getIndexedFields());
     }
 
+    public function testLinksDefaultEmpty(): void
+    {
+        $dto = new WorkflowOptions();
+        $this->assertSame([], $dto->links);
+    }
+
+    public function testWithLinksImmutability(): void
+    {
+        $uri = 'temporal:///namespaces/n/workflows/w/r/history'
+            . '?referenceType=EventReference&eventID=1&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $dto = new WorkflowOptions();
+        $newDto = $dto->withLinks([new NexusLink($uri, NexusLinkConverter::TYPE_WORKFLOW_EVENT)]);
+
+        $this->assertNotSame($dto, $newDto);
+        $this->assertSame([], $dto->links);
+        $this->assertCount(1, $newDto->links);
+    }
+
     public function testMergeWithMethodRetryFillsDefaultRetryOptions(): void
     {
         $dto = WorkflowOptions::new()
diff --git a/tests/Unit/Exception/Failure/NexusHandlerFailureTestCase.php b/tests/Unit/Exception/Failure/NexusHandlerFailureTestCase.php
new file mode 100644
index 000000000..d61aa527f
--- /dev/null
+++ b/tests/Unit/Exception/Failure/NexusHandlerFailureTestCase.php
@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Exception\Failure;
+
+use Temporal\Api\Enums\V1\NexusHandlerErrorRetryBehavior;
+use Temporal\Api\Failure\V1\Failure;
+use Temporal\Api\Failure\V1\NexusHandlerFailureInfo;
+use Temporal\DataConverter\DataConverter;
+use Temporal\Exception\Failure\FailureConverter;
+use Temporal\Exception\Failure\NexusHandlerFailure;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\RetryBehavior;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\UsesClass;
+use Temporal\Tests\Unit\AbstractUnit;
+
+#[CoversClass(NexusHandlerFailure::class)]
+#[UsesClass(ErrorType::class)]
+#[UsesClass(RetryBehavior::class)]
+final class NexusHandlerFailureTestCase extends AbstractUnit
+{
+    /** @return iterable<string, array{0: string, 1: ErrorType}> */
+    public static function knownErrorTypes(): iterable
+    {
+        foreach (ErrorType::cases() as $case) {
+            yield "{$case->value}" => [$case->value, $case];
+        }
+    }
+
+    #[DataProvider('knownErrorTypes')]
+    public function testGetErrorTypeReturnsTypedEnumForKnownWireValue(
+        string $rawType,
+        ErrorType $expected,
+    ): void {
+        $failure = new NexusHandlerFailure('m', $rawType, 0);
+
+        self::assertSame($expected, $failure->getErrorType());
+        self::assertSame($rawType, $failure->getType(), 'Raw string preserved alongside typed view');
+    }
+
+    public function testGetErrorTypeFallsBackToUnknownForUnrecognizedWireValue(): void
+    {
+        $failure = new NexusHandlerFailure('m', 'FUTURE_TYPE_X', 0);
+
+        self::assertSame(ErrorType::Unknown, $failure->getErrorType());
+        self::assertSame('FUTURE_TYPE_X', $failure->getType(), 'Raw string preserved');
+    }
+
+    /** @return iterable<string, array{0: int, 1: RetryBehavior}> */
+    public static function retryBehaviors(): iterable
+    {
+        yield 'Unspecified' => [
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_UNSPECIFIED,
+            RetryBehavior::Unspecified,
+        ];
+        yield 'Retryable' => [
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE,
+            RetryBehavior::Retryable,
+        ];
+        yield 'NonRetryable' => [
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE,
+            RetryBehavior::NonRetryable,
+        ];
+    }
+
+    #[DataProvider('retryBehaviors')]
+    public function testGetRetryBehaviorEnumMapsAllProtoValues(int $proto, RetryBehavior $expected): void
+    {
+        $failure = new NexusHandlerFailure('m', 'BAD_REQUEST', $proto);
+
+        self::assertSame($expected, $failure->getRetryBehaviorEnum());
+        self::assertSame($proto, $failure->getRetryBehavior(), 'Raw int preserved alongside typed view');
+    }
+
+    public function testTypedAccessorsOnConsumePathFromProto(): void
+    {
+        $info = new NexusHandlerFailureInfo();
+        $info->setType('NOT_FOUND');
+        $info->setRetryBehavior(NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE);
+
+        $failure = new Failure();
+        $failure->setMessage('vanished');
+        $failure->setNexusHandlerFailureInfo($info);
+
+        $exception = FailureConverter::mapFailureToException($failure, DataConverter::createDefault());
+
+        self::assertInstanceOf(NexusHandlerFailure::class, $exception);
+        self::assertSame(ErrorType::NotFound, $exception->getErrorType());
+        self::assertSame(RetryBehavior::NonRetryable, $exception->getRetryBehaviorEnum());
+    }
+}
diff --git a/tests/Unit/Exception/FailureConverterTestCase.php b/tests/Unit/Exception/FailureConverterTestCase.php
index 5da23292f..7cf1c9d58 100644
--- a/tests/Unit/Exception/FailureConverterTestCase.php
+++ b/tests/Unit/Exception/FailureConverterTestCase.php
@@ -7,13 +7,23 @@
 use Carbon\CarbonInterval;
 use Exception;
 use Google\Protobuf\Duration;
+use Temporal\Nexus\Exception\ErrorType as NexusErrorType;
+use Temporal\Nexus\Exception\HandlerException as NexusHandlerException;
+use Temporal\Nexus\Exception\OperationException as NexusOperationException;
+use Temporal\Nexus\Exception\RetryBehavior as NexusRetryBehavior;
+use Temporal\Api\Enums\V1\NexusHandlerErrorRetryBehavior;
 use Temporal\Api\Failure\V1\Failure;
+use Temporal\Api\Failure\V1\NexusHandlerFailureInfo;
+use Temporal\Api\Failure\V1\NexusOperationFailureInfo;
 use Temporal\DataConverter\DataConverter;
 use Temporal\DataConverter\EncodedValues;
 use Temporal\Exception\Failure\ApplicationErrorCategory;
 use Temporal\Exception\Failure\ApplicationFailure;
 use Temporal\Exception\Failure\FailureConverter;
+use Temporal\Exception\Failure\NexusHandlerFailure;
+use Temporal\Exception\Failure\NexusOperationFailure;
 use Temporal\Tests\Unit\AbstractUnit;
+use PHPUnit\Framework\Attributes\DataProvider;
 
 final class FailureConverterTestCase extends AbstractUnit
 {
@@ -198,4 +208,301 @@ public function testMapAppFailureWithCategory(): void
         self::assertInstanceOf(ApplicationFailure::class, $newException);
         $this->assertSame(ApplicationErrorCategory::Benign, $newException->getApplicationErrorCategory());
     }
+
+    // ── Nexus: HandlerException → NexusHandlerFailureInfo ───────────────
+
+    public function testNexusHandlerExceptionProducesNexusHandlerFailureInfo(): void
+    {
+        $e = NexusHandlerException::create(
+            NexusErrorType::BadRequest,
+            'invalid payload',
+            null,
+            NexusRetryBehavior::NonRetryable,
+        );
+
+        $failure = FailureConverter::mapExceptionToFailure($e, DataConverter::createDefault());
+
+        self::assertTrue($failure->hasNexusHandlerFailureInfo(), 'Nexus handler info must be set');
+        $info = $failure->getNexusHandlerFailureInfo();
+        self::assertSame('BAD_REQUEST', $info->getType(), 'Spec-level error type wire value');
+        self::assertSame(
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE,
+            $info->getRetryBehavior(),
+        );
+        self::assertSame('invalid payload', $failure->getMessage());
+    }
+
+    public function testNexusHandlerExceptionWithRetryableBehavior(): void
+    {
+        $e = NexusHandlerException::create(
+            NexusErrorType::Internal,
+            'transient storage error',
+            null,
+            NexusRetryBehavior::Retryable,
+        );
+
+        $failure = FailureConverter::mapExceptionToFailure($e, DataConverter::createDefault());
+
+        self::assertSame(
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE,
+            $failure->getNexusHandlerFailureInfo()->getRetryBehavior(),
+        );
+    }
+
+    public function testNexusHandlerExceptionUnspecifiedRetryBehaviorIsZero(): void
+    {
+        $e = NexusHandlerException::create(NexusErrorType::NotFound, 'missing');
+
+        $failure = FailureConverter::mapExceptionToFailure($e, DataConverter::createDefault());
+
+        self::assertSame(
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_UNSPECIFIED,
+            $failure->getNexusHandlerFailureInfo()->getRetryBehavior(),
+        );
+    }
+
+    // ── Nexus: OperationException → tagged ApplicationFailureInfo ──────
+
+    public function testNexusOperationExceptionFailedProducesTaggedApplicationFailure(): void
+    {
+        $e = NexusOperationException::failed('user rejected the request');
+
+        $failure = FailureConverter::mapExceptionToFailure($e, DataConverter::createDefault());
+
+        self::assertTrue($failure->hasApplicationFailureInfo(), 'Must use ApplicationFailureInfo for operation errors');
+        self::assertFalse($failure->hasNexusHandlerFailureInfo(), 'Must NOT emit NexusHandlerFailureInfo for operation errors');
+
+        $info = $failure->getApplicationFailureInfo();
+        self::assertSame(
+            'OperationError',
+            $info->getType(),
+            'Go and Java handlers put this exact type on the wire',
+        );
+        self::assertTrue($info->getNonRetryable(), 'Operation errors are terminal states');
+        self::assertSame('user rejected the request', $failure->getMessage());
+    }
+
+    public function testNexusOperationExceptionCanceledProducesCanceledFailure(): void
+    {
+        $e = NexusOperationException::canceled('user canceled');
+
+        $failure = FailureConverter::mapExceptionToFailure($e, DataConverter::createDefault());
+
+        self::assertTrue($failure->hasCanceledFailureInfo(), 'Canceled operations must use CanceledFailureInfo');
+        self::assertFalse($failure->hasApplicationFailureInfo());
+        self::assertSame('user canceled', $failure->getMessage());
+    }
+
+    // ── Nexus: inverse mapping (wire → typed exception) ────────────────
+
+    public function testNexusHandlerFailureInfoMapsToNexusHandlerFailure(): void
+    {
+        $info = new NexusHandlerFailureInfo();
+        $info->setType('BAD_REQUEST');
+        $info->setRetryBehavior(NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE);
+
+        $failure = new Failure();
+        $failure->setMessage('bad payload');
+        $failure->setNexusHandlerFailureInfo($info);
+
+        $exception = FailureConverter::mapFailureToException($failure, DataConverter::createDefault());
+
+        self::assertInstanceOf(NexusHandlerFailure::class, $exception);
+        self::assertSame('bad payload', $exception->getMessage());
+        self::assertSame('BAD_REQUEST', $exception->getType());
+        self::assertSame(
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE,
+            $exception->getRetryBehavior(),
+        );
+    }
+
+    public function testNexusOperationFailureInfoMapsToNexusOperationFailure(): void
+    {
+        $info = new NexusOperationFailureInfo();
+        $info->setScheduledEventId(42);
+        $info->setEndpoint('my-endpoint');
+        $info->setService('MyService');
+        $info->setOperation('doThing');
+        $info->setOperationToken('tok-xyz');
+
+        $failure = new Failure();
+        $failure->setMessage('operation failed');
+        $failure->setNexusOperationExecutionFailureInfo($info);
+
+        $exception = FailureConverter::mapFailureToException($failure, DataConverter::createDefault());
+
+        self::assertInstanceOf(NexusOperationFailure::class, $exception);
+        self::assertSame(42, $exception->getScheduledEventId());
+        self::assertSame('my-endpoint', $exception->getEndpoint());
+        self::assertSame('MyService', $exception->getService());
+        self::assertSame('doThing', $exception->getOperation());
+        self::assertSame('tok-xyz', $exception->getOperationToken());
+    }
+
+    public function testNexusOperationFailureProducesNexusOperationFailureInfo(): void
+    {
+        $e = new NexusOperationFailure(
+            'operation failed',
+            42,
+            'my-endpoint',
+            'MyService',
+            'doThing',
+            'tok-xyz',
+        );
+
+        $failure = FailureConverter::mapExceptionToFailure($e, DataConverter::createDefault());
+
+        self::assertTrue($failure->hasNexusOperationExecutionFailureInfo());
+        $info = $failure->getNexusOperationExecutionFailureInfo();
+        self::assertSame(42, $info->getScheduledEventId());
+        self::assertSame('my-endpoint', $info->getEndpoint());
+        self::assertSame('MyService', $info->getService());
+        self::assertSame('doThing', $info->getOperation());
+        self::assertSame('tok-xyz', $info->getOperationToken());
+    }
+
+    public function testNexusHandlerFailureProducesNexusHandlerFailureInfo(): void
+    {
+        $e = new NexusHandlerFailure(
+            'handler exploded',
+            'BAD_REQUEST',
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE,
+        );
+
+        $failure = FailureConverter::mapExceptionToFailure($e, DataConverter::createDefault());
+
+        self::assertTrue($failure->hasNexusHandlerFailureInfo());
+        $info = $failure->getNexusHandlerFailureInfo();
+        self::assertSame('BAD_REQUEST', $info->getType());
+        self::assertSame(
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE,
+            $info->getRetryBehavior(),
+        );
+    }
+
+    public function testNexusHandlerFailureRoundTrip(): void
+    {
+        $converter = DataConverter::createDefault();
+        $original = new NexusHandlerFailure(
+            'handler exploded',
+            'INTERNAL',
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE,
+        );
+
+        $failure = FailureConverter::mapExceptionToFailure($original, $converter);
+        $restored = FailureConverter::mapFailureToException($failure, $converter);
+
+        self::assertInstanceOf(NexusHandlerFailure::class, $restored);
+        self::assertSame('INTERNAL', $restored->getType());
+        self::assertSame(
+            NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE,
+            $restored->getRetryBehavior(),
+        );
+    }
+
+    public function testNexusOperationFailureRoundTrip(): void
+    {
+        $converter = DataConverter::createDefault();
+        $original = new NexusOperationFailure(
+            'operation failed',
+            7,
+            'endpoint-1',
+            'SvcA',
+            'op-b',
+            'token-c',
+        );
+
+        $failure = FailureConverter::mapExceptionToFailure($original, $converter);
+        $restored = FailureConverter::mapFailureToException($failure, $converter);
+
+        self::assertInstanceOf(NexusOperationFailure::class, $restored);
+        self::assertSame(7, $restored->getScheduledEventId());
+        self::assertSame('endpoint-1', $restored->getEndpoint());
+        self::assertSame('SvcA', $restored->getService());
+        self::assertSame('op-b', $restored->getOperation());
+        self::assertSame('token-c', $restored->getOperationToken());
+    }
+
+    public function testNexusOperationFailureInfoFallsBackToDeprecatedOperationId(): void
+    {
+        // Older servers populate only the deprecated `operation_id` field.
+        // The converter must fall back so callers always get a non-empty
+        // token for async operations.
+        $info = new NexusOperationFailureInfo();
+        $info->setOperationId('legacy-id');
+        // operation_token left empty
+
+        $failure = new Failure();
+        $failure->setMessage('legacy');
+        $failure->setNexusOperationExecutionFailureInfo($info);
+
+        $exception = FailureConverter::mapFailureToException($failure, DataConverter::createDefault());
+
+        self::assertInstanceOf(NexusOperationFailure::class, $exception);
+        self::assertSame('legacy-id', $exception->getOperationToken());
+    }
+
+    /** @return iterable<string, array{0: NexusErrorType, 1: NexusRetryBehavior, 2: int}> */
+    public static function nexusHandlerRoundTripMatrix(): iterable
+    {
+        $protoMap = [
+            NexusRetryBehavior::Unspecified->value => NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_UNSPECIFIED,
+            NexusRetryBehavior::Retryable->value => NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE,
+            NexusRetryBehavior::NonRetryable->value => NexusHandlerErrorRetryBehavior::NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE,
+        ];
+
+        foreach (NexusErrorType::cases() as $type) {
+            foreach (NexusRetryBehavior::cases() as $retry) {
+                yield "{$type->value} + {$retry->value}" => [$type, $retry, $protoMap[$retry->value]];
+            }
+        }
+    }
+
+    #[DataProvider('nexusHandlerRoundTripMatrix')]
+    public function testNexusHandlerRoundTripParametric(
+        NexusErrorType $type,
+        NexusRetryBehavior $retry,
+        int $expectedProtoRetry,
+    ): void {
+        $original = NexusHandlerException::create($type, 'wire round-trip', null, $retry);
+        $converter = DataConverter::createDefault();
+
+        $failure = FailureConverter::mapExceptionToFailure($original, $converter);
+        $restored = FailureConverter::mapFailureToException($failure, $converter);
+
+        self::assertInstanceOf(NexusHandlerFailure::class, $restored);
+        self::assertSame($type->value, $restored->getType());
+        self::assertSame($expectedProtoRetry, $restored->getRetryBehavior());
+        // Stack trace is appended to the message on round-trip; only the leading text is contractual.
+        self::assertStringStartsWith('wire round-trip', $restored->getMessage());
+    }
+
+    public function testNexusOperationFailurePreservesCauseChain(): void
+    {
+        // A NexusOperationFailureInfo typically wraps a cause describing the
+        // underlying handler error. The cause must propagate through the
+        // inverse mapping.
+        $cause = new Failure();
+        $cause->setMessage('handler said no');
+        $causeInfo = new \Temporal\Api\Failure\V1\ApplicationFailureInfo();
+        $causeInfo->setType('OperationError');
+        $causeInfo->setNonRetryable(true);
+        $cause->setApplicationFailureInfo($causeInfo);
+
+        $info = new NexusOperationFailureInfo();
+        $info->setEndpoint('ep');
+        $info->setService('svc');
+        $info->setOperation('op');
+
+        $failure = new Failure();
+        $failure->setMessage('nexus op failure');
+        $failure->setNexusOperationExecutionFailureInfo($info);
+        $failure->setCause($cause);
+
+        $exception = FailureConverter::mapFailureToException($failure, DataConverter::createDefault());
+
+        self::assertInstanceOf(NexusOperationFailure::class, $exception);
+        self::assertInstanceOf(ApplicationFailure::class, $exception->getPrevious());
+        self::assertSame('OperationError', $exception->getPrevious()->getType());
+    }
 }
diff --git a/tests/Unit/Framework/WorkerMock.php b/tests/Unit/Framework/WorkerMock.php
index d09ff2976..e44b12cac 100644
--- a/tests/Unit/Framework/WorkerMock.php
+++ b/tests/Unit/Framework/WorkerMock.php
@@ -190,6 +190,16 @@ public function complete(): void
         $this->execution = [];
     }
 
+    public function registerNexusServiceImplementation(object ...$services): WorkerInterface
+    {
+        return $this;
+    }
+
+    public function getNexusServices(): array
+    {
+        return [];
+    }
+
     public function registerActivityFinalizer(\Closure $finalizer): WorkerInterface
     {
         $this->services->activities->addFinalizer($finalizer);
diff --git a/tests/Unit/Internal/Client/OnConflictOptionsTestCase.php b/tests/Unit/Internal/Client/OnConflictOptionsTestCase.php
new file mode 100644
index 000000000..a743cd34f
--- /dev/null
+++ b/tests/Unit/Internal/Client/OnConflictOptionsTestCase.php
@@ -0,0 +1,51 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Internal\Client;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use Temporal\Internal\Client\OnConflictOptions;
+
+#[CoversClass(OnConflictOptions::class)]
+final class OnConflictOptionsTestCase extends TestCase
+{
+    public function testDefaultsAreAllTrue(): void
+    {
+        $options = new OnConflictOptions();
+
+        self::assertTrue($options->attachRequestId);
+        self::assertTrue($options->attachCompletionCallbacks);
+        self::assertTrue($options->attachLinks);
+    }
+
+    public function testAcceptsExplicitFlags(): void
+    {
+        $options = new OnConflictOptions(
+            attachRequestId: false,
+            attachCompletionCallbacks: true,
+            attachLinks: false,
+        );
+
+        self::assertFalse($options->attachRequestId);
+        self::assertTrue($options->attachCompletionCallbacks);
+        self::assertFalse($options->attachLinks);
+    }
+
+    public function testForNexusCompletionCallbackHardcodesAllTrue(): void
+    {
+        $options = new OnConflictOptions();
+
+        self::assertTrue($options->attachRequestId);
+        self::assertTrue($options->attachCompletionCallbacks);
+        self::assertTrue($options->attachLinks);
+    }
+}
diff --git a/tests/Unit/Internal/Client/WorkflowStarterTestCase.php b/tests/Unit/Internal/Client/WorkflowStarterTestCase.php
index a5f689cf1..932448ba6 100644
--- a/tests/Unit/Internal/Client/WorkflowStarterTestCase.php
+++ b/tests/Unit/Internal/Client/WorkflowStarterTestCase.php
@@ -4,16 +4,27 @@
 
 namespace Temporal\Tests\Unit\Internal\Client;
 
+use Google\Protobuf\Any;
+use Google\Rpc\Status as RpcStatus;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\TestCase;
+use Temporal\Api\Errordetails\V1\WorkflowExecutionAlreadyStartedFailure;
 use Temporal\Api\Workflowservice\V1\StartWorkflowExecutionRequest;
 use Temporal\Api\Workflowservice\V1\StartWorkflowExecutionResponse;
 use Temporal\Client\GRPC\ServiceClientInterface;
+use Temporal\Client\GRPC\StatusCode;
 use Temporal\Client\WorkflowOptions;
+use Temporal\Common\WorkflowIdConflictPolicy;
 use Temporal\DataConverter\DataConverter;
+use Temporal\Exception\Client\ServiceClientException;
+use Temporal\Exception\Client\WorkflowExecutionAlreadyStartedException;
 use Temporal\Internal\Client\WorkflowStarter;
 use Temporal\Internal\Interceptor\Pipeline;
+use Temporal\Internal\Nexus\NexusLinkConverter;
+use Temporal\Internal\Client\OnConflictOptions;
 use Temporal\Internal\Support\DateInterval;
+use Temporal\Nexus\Link as NexusLink;
+use Temporal\Workflow\CompletionCallback;
 
 /**
  * @internal
@@ -70,6 +81,134 @@ public function testDelayIfSpecifiedNanos(): void
         self::assertSame(42000, $request->getWorkflowStartDelay()->getNanos());
     }
 
+    public function testOnConflictOptionsAbsentByDefault(): void
+    {
+        $request = $this->startRequest('test-workflow', new WorkflowOptions());
+
+        self::assertNull($request->getOnConflictOptions());
+    }
+
+    public function testOnConflictOptionsSerializedToProtoWithAllFlags(): void
+    {
+        $options = (new WorkflowOptions())
+            ->withOnConflictOptionsInternal(new OnConflictOptions());
+
+        $request = $this->startRequest('test-workflow', $options);
+
+        $proto = $request->getOnConflictOptions();
+        self::assertNotNull($proto);
+        self::assertTrue($proto->getAttachRequestId());
+        self::assertTrue($proto->getAttachCompletionCallbacks());
+        self::assertTrue($proto->getAttachLinks());
+    }
+
+    public function testOnConflictOptionsSerializedToProtoWithMixedFlags(): void
+    {
+        $options = (new WorkflowOptions())
+            ->withOnConflictOptionsInternal(new OnConflictOptions(
+                attachRequestId: false,
+                attachCompletionCallbacks: true,
+                attachLinks: false,
+            ));
+
+        $request = $this->startRequest('test-workflow', $options);
+
+        $proto = $request->getOnConflictOptions();
+        self::assertNotNull($proto);
+        self::assertFalse($proto->getAttachRequestId());
+        self::assertTrue($proto->getAttachCompletionCallbacks());
+        self::assertFalse($proto->getAttachLinks());
+    }
+
+    public function testWorkflowIdConflictPolicyUseExistingFlowsToProto(): void
+    {
+        $options = (new WorkflowOptions())
+            ->withWorkflowIdConflictPolicy(WorkflowIdConflictPolicy::UseExisting);
+
+        $request = $this->startRequest('test-workflow', $options);
+
+        self::assertSame(WorkflowIdConflictPolicy::UseExisting->value, $request->getWorkflowIdConflictPolicy());
+    }
+
+    public function testAlreadyStartedThrowsEvenWithUseExisting(): void
+    {
+        $exception = $this->alreadyStartedException('existing-run-id');
+
+        $clientOptions = (new \Temporal\Client\ClientOptions())
+            ->withNamespace(self::NAMESPACE)
+            ->withIdentity(self::IDENTITY);
+
+        $clientMock = $this->createMock(ServiceClientInterface::class);
+        $clientMock
+            ->expects($this->once())
+            ->method('StartWorkflowExecution')
+            ->willThrowException($exception);
+
+        $starter = new WorkflowStarter(
+            serviceClient: $clientMock,
+            converter: DataConverter::createDefault(),
+            clientOptions: $clientOptions,
+            interceptors: Pipeline::prepare([]),
+        );
+
+        $options = (new WorkflowOptions())
+            ->withWorkflowId('my-wf-id')
+            ->withWorkflowIdConflictPolicy(WorkflowIdConflictPolicy::UseExisting);
+
+        $this->expectException(WorkflowExecutionAlreadyStartedException::class);
+        $starter->start('test-workflow', $options, []);
+    }
+
+    private function alreadyStartedException(string $runId): ServiceClientException
+    {
+        $any = new Any();
+        $any->pack((new WorkflowExecutionAlreadyStartedFailure())->setRunId($runId));
+
+        $rpcStatus = (new RpcStatus())->setCode(StatusCode::ALREADY_EXISTS);
+        $rpcStatus->setDetails([$any]);
+
+        $status = new \stdClass();
+        $status->code = StatusCode::ALREADY_EXISTS;
+        $status->details = 'workflow execution already started';
+        $status->metadata = ['grpc-status-details-bin' => [$rpcStatus->serializeToString()]];
+
+        return new ServiceClientException($status);
+    }
+
+    public function testStartRequestCarriesTopLevelLinks(): void
+    {
+        $uri = 'temporal:///namespaces/n/workflows/w/r/history'
+            . '?referenceType=EventReference&eventID=1&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $options = (new WorkflowOptions())
+            ->withLinks([new NexusLink($uri, NexusLinkConverter::TYPE_WORKFLOW_EVENT)]);
+
+        $request = $this->startRequest('test-workflow', $options);
+
+        $links = \iterator_to_array($request->getLinks());
+        self::assertCount(1, $links);
+        self::assertNotNull($links[0]->getWorkflowEvent());
+    }
+
+    public function testCompletionCallbackProtoIncludesLinks(): void
+    {
+        $uri = 'temporal:///namespaces/n/workflows/w/r/history'
+            . '?referenceType=EventReference&eventID=1&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $callback = CompletionCallback::fromNexusLinks(
+            'http://cb',
+            [],
+            [new NexusLink($uri, NexusLinkConverter::TYPE_WORKFLOW_EVENT)],
+        );
+        $options = (new WorkflowOptions())->withCompletionCallbacks($callback);
+
+        $request = $this->startRequest('test-workflow', $options);
+
+        $callbacks = \iterator_to_array($request->getCompletionCallbacks());
+        self::assertCount(1, $callbacks);
+        $links = \iterator_to_array($callbacks[0]->getLinks());
+        self::assertCount(1, $links);
+        self::assertNotNull($links[0]->getWorkflowEvent());
+    }
+
     private function startRequest(
         string $workflowType,
         WorkflowOptions $options,
diff --git a/tests/Unit/Internal/Nexus/NexusLinkConverterTestCase.php b/tests/Unit/Internal/Nexus/NexusLinkConverterTestCase.php
new file mode 100644
index 000000000..87008b070
--- /dev/null
+++ b/tests/Unit/Internal/Nexus/NexusLinkConverterTestCase.php
@@ -0,0 +1,501 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Internal\Nexus;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use Temporal\Api\Common\V1\Link\WorkflowEvent;
+use Temporal\Api\Common\V1\Link\WorkflowEvent\EventReference;
+use Temporal\Api\Common\V1\Link\WorkflowEvent\RequestIdReference;
+use Temporal\Api\Enums\V1\EventType;
+use Temporal\Internal\Nexus\NexusLinkConverter;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Nexus\Link as NexusLink;
+
+#[CoversClass(NexusLinkConverter::class)]
+final class NexusLinkConverterTestCase extends TestCase
+{
+    private const TYPE = NexusLinkConverter::TYPE_WORKFLOW_EVENT;
+
+    public function testEventReferenceHappyPath(): void
+    {
+        $uri = 'temporal:///namespaces/default/workflows/wf-123/run-456/history'
+            . '?referenceType=EventReference&eventID=42&eventType=EVENT_TYPE_NEXUS_OPERATION_STARTED';
+        $result = NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+
+        self::assertCount(1, $result);
+        $event = $result[0]->getWorkflowEvent();
+        self::assertNotNull($event);
+        self::assertSame('default', $event->getNamespace());
+        self::assertSame('wf-123', $event->getWorkflowId());
+        self::assertSame('run-456', $event->getRunId());
+
+        $eventRef = $event->getEventRef();
+        self::assertNotNull($eventRef);
+        self::assertSame(42, (int) $eventRef->getEventId());
+        self::assertSame(EventType::EVENT_TYPE_NEXUS_OPERATION_STARTED, $eventRef->getEventType());
+    }
+
+    public function testRequestIdReferenceHappyPath(): void
+    {
+        $uri = 'temporal:///namespaces/default/workflows/wf-1/run-1/history'
+            . '?referenceType=RequestIdReference&requestID=req-abc&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $result = NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+
+        self::assertCount(1, $result);
+        $event = $result[0]->getWorkflowEvent();
+        self::assertNotNull($event);
+        $ref = $event->getRequestIdRef();
+        self::assertNotNull($ref);
+        self::assertSame('req-abc', $ref->getRequestId());
+        self::assertSame(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED, $ref->getEventType());
+    }
+
+    public function testEventReferenceWithoutEventId(): void
+    {
+        $uri = 'temporal:///namespaces/default/workflows/wf/run/history'
+            . '?referenceType=EventReference&eventType=EVENT_TYPE_NEXUS_OPERATION_STARTED';
+        $result = NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+
+        self::assertCount(1, $result);
+        $eventRef = $result[0]->getWorkflowEvent()->getEventRef();
+        self::assertNotNull($eventRef);
+        self::assertSame(0, (int) $eventRef->getEventId());
+    }
+
+    public function testSkipsNonWorkflowEventLinks(): void
+    {
+        $result = NexusLinkConverter::toProtoLinks([
+            new NexusLink('https://custom-tracker/123', 'custom.tracking.event'),
+        ]);
+        self::assertSame([], $result);
+    }
+
+    public function testMixedListKeepsWorkflowEventOnly(): void
+    {
+        $good1 = 'temporal:///namespaces/n/workflows/w/r/history?referenceType=EventReference&eventID=1&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $good2 = 'temporal:///namespaces/n/workflows/w2/r2/history?referenceType=EventReference&eventID=2&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $result = NexusLinkConverter::toProtoLinks([
+            new NexusLink($good1, self::TYPE),
+            new NexusLink('https://custom/abc', 'custom.tracking'),
+            new NexusLink($good2, self::TYPE),
+        ]);
+
+        self::assertCount(2, $result);
+    }
+
+    public function testPathDecodesEscapedSegments(): void
+    {
+        $uri = 'temporal:///namespaces/ns%20with%20space/workflows/wf%2Fslash/run-1/history'
+            . '?referenceType=EventReference&eventID=1&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $result = NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+
+        $event = $result[0]->getWorkflowEvent();
+        self::assertSame('ns with space', $event->getNamespace());
+        self::assertSame('wf/slash', $event->getWorkflowId());
+    }
+
+    public function testRejectsBadScheme(): void
+    {
+        $uri = 'https:///namespaces/n/workflows/w/r/history?referenceType=EventReference&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Nexus link URI scheme must be "temporal", got "https" in ');
+        NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+    }
+
+    public function testRejectsMalformedPath(): void
+    {
+        $uri = 'temporal:///workflows/w/r/history?referenceType=EventReference&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Nexus link URI path does not match /namespaces/{ns}/workflows/{wf}/{run}/history: ');
+        NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+    }
+
+    public function testRejectsUnknownEventType(): void
+    {
+        $uri = 'temporal:///namespaces/n/workflows/w/r/history?referenceType=EventReference&eventType=EVENT_TYPE_DOES_NOT_EXIST';
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('unknown EventType "EVENT_TYPE_DOES_NOT_EXIST" in Nexus link URI ');
+        NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+    }
+
+    public function testRejectsUnknownReferenceType(): void
+    {
+        $uri = 'temporal:///namespaces/n/workflows/w/r/history?referenceType=NotARealType&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('unknown referenceType "NotARealType" in Nexus link URI ');
+        NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+    }
+
+    public function testRejectsNonNumericEventId(): void
+    {
+        $uri = 'temporal:///namespaces/n/workflows/w/r/history?referenceType=EventReference&eventID=abc&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $this->expectException(InvalidArgumentException::class);
+        NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+    }
+
+    public function testAcceptsMissingRequestIdAsEmpty(): void
+    {
+        $uri = 'temporal:///namespaces/n/workflows/w/r/history?referenceType=RequestIdReference&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $result = NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+
+        self::assertCount(1, $result);
+        $ref = $result[0]->getWorkflowEvent()->getRequestIdRef();
+        self::assertNotNull($ref);
+        self::assertSame('', $ref->getRequestId());
+    }
+
+    public function testParsesPascalCaseEventReference(): void
+    {
+        $uri = 'temporal:///namespaces/default/workflows/wf/run/history'
+            . '?referenceType=EventReference&eventID=7&eventType=WorkflowExecutionStarted';
+        $result = NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+
+        self::assertCount(1, $result);
+        $eventRef = $result[0]->getWorkflowEvent()->getEventRef();
+        self::assertNotNull($eventRef);
+        self::assertSame(7, (int) $eventRef->getEventId());
+        self::assertSame(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED, $eventRef->getEventType());
+    }
+
+    public function testParsesPascalCaseRequestIdReference(): void
+    {
+        $uri = 'temporal:///namespaces/default/workflows/wf/run/history'
+            . '?referenceType=RequestIdReference&requestID=req-1&eventType=WorkflowExecutionOptionsUpdated';
+        $result = NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+
+        self::assertCount(1, $result);
+        $ref = $result[0]->getWorkflowEvent()->getRequestIdRef();
+        self::assertNotNull($ref);
+        self::assertSame('req-1', $ref->getRequestId());
+        self::assertSame(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED, $ref->getEventType());
+    }
+
+    public function testParsesNexusOperationScheduledPascalCase(): void
+    {
+        $uri = 'temporal:///namespaces/n/workflows/w/r/history'
+            . '?referenceType=EventReference&eventType=NexusOperationScheduled';
+        $result = NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+
+        $eventRef = $result[0]->getWorkflowEvent()->getEventRef();
+        self::assertSame(EventType::EVENT_TYPE_NEXUS_OPERATION_SCHEDULED, $eventRef->getEventType());
+    }
+
+    public function testRejectsUnknownPascalCase(): void
+    {
+        $uri = 'temporal:///namespaces/n/workflows/w/r/history'
+            . '?referenceType=EventReference&eventType=WorkflowDoesNotExist';
+        $this->expectException(InvalidArgumentException::class);
+        NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+    }
+
+    public function testRejectsLowerCaseEventType(): void
+    {
+        $uri = 'temporal:///namespaces/n/workflows/w/r/history'
+            . '?referenceType=EventReference&eventType=workflowExecutionStarted';
+        $this->expectException(InvalidArgumentException::class);
+        NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+    }
+
+    public function testRejectsEmptyEventType(): void
+    {
+        $uri = 'temporal:///namespaces/n/workflows/w/r/history?referenceType=EventReference&eventType=';
+        $this->expectException(InvalidArgumentException::class);
+        NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+    }
+
+    public function testParsesJavaWireFormatVerbatim(): void
+    {
+        // Fixture from sdk-java LinkConverterTest::testConvertWorkflowEventToNexus_Valid
+        $uri = 'temporal:///namespaces/ns/workflows/wf-id/run-id/history'
+            . '?referenceType=EventReference&eventID=1&eventType=WorkflowExecutionStarted';
+        $result = NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+
+        $event = $result[0]->getWorkflowEvent();
+        self::assertSame('ns', $event->getNamespace());
+        self::assertSame('wf-id', $event->getWorkflowId());
+        self::assertSame('run-id', $event->getRunId());
+        self::assertSame(1, (int) $event->getEventRef()->getEventId());
+        self::assertSame(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED, $event->getEventRef()->getEventType());
+    }
+
+    public function testParsesGoWireFormatVerbatim(): void
+    {
+        $uri = 'temporal:///namespaces/ns/workflows/wf-id/run-id/history'
+            . '?referenceType=EventReference&eventID=1&eventType=EVENT_TYPE_WORKFLOW_EXECUTION_STARTED';
+        $result = NexusLinkConverter::toProtoLinks([new NexusLink($uri, self::TYPE)]);
+
+        self::assertSame(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED, $result[0]->getWorkflowEvent()->getEventRef()->getEventType());
+    }
+
+    // ---- Encoder (Part B) ----
+
+    public function testEncodesToJavaWireFormat(): void
+    {
+        $event = (new WorkflowEvent())
+            ->setNamespace('ns')
+            ->setWorkflowId('wf-id')
+            ->setRunId('run-id');
+        $event->setEventRef(
+            (new EventReference())
+                ->setEventId(1)
+                ->setEventType(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED),
+        );
+
+        $link = NexusLinkConverter::workflowEventToNexusLink($event);
+
+        self::assertSame(self::TYPE, $link->type);
+        self::assertSame(
+            'temporal:///namespaces/ns/workflows/wf-id/run-id/history'
+            . '?referenceType=EventReference&eventID=1&eventType=WorkflowExecutionStarted',
+            $link->uri,
+        );
+    }
+
+    public function testEncodesRequestIdReferenceToJavaWireFormat(): void
+    {
+        $event = (new WorkflowEvent())
+            ->setNamespace('ns')
+            ->setWorkflowId('wf-id')
+            ->setRunId('run-id');
+        $event->setRequestIdRef(
+            (new RequestIdReference())
+                ->setRequestId('random-request-id')
+                ->setEventType(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED),
+        );
+
+        $link = NexusLinkConverter::workflowEventToNexusLink($event);
+
+        self::assertSame(
+            'temporal:///namespaces/ns/workflows/wf-id/run-id/history'
+            . '?referenceType=RequestIdReference&requestID=random-request-id&eventType=WorkflowExecutionOptionsUpdated',
+            $link->uri,
+        );
+    }
+
+    public function testRoundTripEventReferenceWithEventId(): void
+    {
+        $event = (new WorkflowEvent())
+            ->setNamespace('ns')
+            ->setWorkflowId('wf')
+            ->setRunId('run');
+        $event->setEventRef(
+            (new EventReference())
+                ->setEventId(42)
+                ->setEventType(EventType::EVENT_TYPE_NEXUS_OPERATION_STARTED),
+        );
+
+        $link = NexusLinkConverter::workflowEventToNexusLink($event);
+        $decoded = NexusLinkConverter::toProtoLinks([$link])[0]->getWorkflowEvent();
+
+        self::assertSame('ns', $decoded->getNamespace());
+        self::assertSame('wf', $decoded->getWorkflowId());
+        self::assertSame('run', $decoded->getRunId());
+        self::assertSame(42, (int) $decoded->getEventRef()->getEventId());
+        self::assertSame(
+            EventType::EVENT_TYPE_NEXUS_OPERATION_STARTED,
+            $decoded->getEventRef()->getEventType(),
+        );
+    }
+
+    public function testRoundTripRequestIdReference(): void
+    {
+        $event = (new WorkflowEvent())
+            ->setNamespace('default')
+            ->setWorkflowId('wf')
+            ->setRunId('run');
+        $event->setRequestIdRef(
+            (new RequestIdReference())
+                ->setRequestId('req-abc')
+                ->setEventType(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED),
+        );
+
+        $link = NexusLinkConverter::workflowEventToNexusLink($event);
+        $decoded = NexusLinkConverter::toProtoLinks([$link])[0]->getWorkflowEvent();
+
+        self::assertSame('req-abc', $decoded->getRequestIdRef()->getRequestId());
+        self::assertSame(
+            EventType::EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED,
+            $decoded->getRequestIdRef()->getEventType(),
+        );
+    }
+
+    public function testRoundTripEventReferenceWithoutEventId(): void
+    {
+        $event = (new WorkflowEvent())
+            ->setNamespace('ns')
+            ->setWorkflowId('wf')
+            ->setRunId('run');
+        $event->setEventRef(
+            (new EventReference())
+                ->setEventType(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED),
+        );
+
+        $link = NexusLinkConverter::workflowEventToNexusLink($event);
+        self::assertStringNotContainsString('eventID=', $link->uri);
+
+        $decoded = NexusLinkConverter::toProtoLinks([$link])[0]->getWorkflowEvent();
+        self::assertSame(0, (int) $decoded->getEventRef()->getEventId());
+    }
+
+    public function testEncodesSlashInWorkflowId(): void
+    {
+        $event = (new WorkflowEvent())
+            ->setNamespace('ns')
+            ->setWorkflowId('wf-id/')
+            ->setRunId('run-id');
+        $event->setEventRef(
+            (new EventReference())
+                ->setEventId(1)
+                ->setEventType(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED),
+        );
+
+        $link = NexusLinkConverter::workflowEventToNexusLink($event);
+
+        self::assertStringContainsString('/workflows/wf-id%2F/', $link->uri);
+    }
+
+    public function testEncodesAngleInWorkflowId(): void
+    {
+        $event = (new WorkflowEvent())
+            ->setNamespace('ns')
+            ->setWorkflowId('wf-id>')
+            ->setRunId('run-id');
+        $event->setEventRef(
+            (new EventReference())
+                ->setEventId(1)
+                ->setEventType(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED),
+        );
+
+        $link = NexusLinkConverter::workflowEventToNexusLink($event);
+
+        self::assertStringContainsString('/workflows/wf-id%3E/', $link->uri);
+    }
+
+    public function testEncoderRejectsEmptyWorkflowEvent(): void
+    {
+        $event = (new WorkflowEvent())
+            ->setNamespace('ns')
+            ->setWorkflowId('wf')
+            ->setRunId('run');
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('WorkflowEvent must have either event_ref or request_id_ref set');
+        NexusLinkConverter::workflowEventToNexusLink($event);
+    }
+
+    public function testEncoderRejectsUnknownEventTypeEnumValue(): void
+    {
+        $event = (new WorkflowEvent())
+            ->setNamespace('ns')
+            ->setWorkflowId('wf')
+            ->setRunId('run');
+        $event->setEventRef(
+            (new EventReference())->setEventType(99999),
+        );
+
+        $this->expectException(InvalidArgumentException::class);
+        NexusLinkConverter::workflowEventToNexusLink($event);
+    }
+
+    public function testHardcodedTypeWorkflowEventConstant(): void
+    {
+        // Tripwire. The proto-php stubs we depend on don't expose a stable
+        // descriptor.full_name accessor on generated classes today, so we
+        // hardcode the type string in NexusLinkConverter::TYPE_WORKFLOW_EVENT.
+        // If proto-php gains such an accessor (e.g. via descriptor pool),
+        // replace the hardcode and update this test.
+        self::assertSame(
+            'temporal.api.common.v1.Link.WorkflowEvent',
+            NexusLinkConverter::TYPE_WORKFLOW_EVENT,
+        );
+        self::assertTrue(\class_exists(WorkflowEvent::class));
+    }
+
+    public function testEncoderOutputIsAcceptedByOurDecoder(): void
+    {
+        $cases = [
+            // (namespace, workflowId, runId, fn(): WorkflowEvent)
+            [
+                'ns', 'wf', 'run',
+                static fn(): EventReference => (new EventReference())
+                    ->setEventId(1)
+                    ->setEventType(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED),
+                'event',
+            ],
+            [
+                'default', 'wf-x', 'run-y',
+                static fn(): EventReference => (new EventReference())
+                    ->setEventType(EventType::EVENT_TYPE_NEXUS_OPERATION_SCHEDULED),
+                'event',
+            ],
+            [
+                'ns space', 'wf/with/slash', 'run-1',
+                static fn(): RequestIdReference => (new RequestIdReference())
+                    ->setRequestId('rid-1')
+                    ->setEventType(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED),
+                'request',
+            ],
+            [
+                'ns', 'wf', 'run',
+                static fn(): EventReference => (new EventReference())
+                    ->setEventId(0)
+                    ->setEventType(EventType::EVENT_TYPE_WORKFLOW_EXECUTION_STARTED),
+                'event',
+            ],
+        ];
+
+        foreach ($cases as $i => [$ns, $wfId, $runId, $refFactory, $kind]) {
+            $event = (new WorkflowEvent())
+                ->setNamespace($ns)
+                ->setWorkflowId($wfId)
+                ->setRunId($runId);
+            $ref = $refFactory();
+            if ($kind === 'event') {
+                $event->setEventRef($ref);
+            } else {
+                $event->setRequestIdRef($ref);
+            }
+
+            $link = NexusLinkConverter::workflowEventToNexusLink($event);
+            $decoded = NexusLinkConverter::toProtoLinks([$link])[0]->getWorkflowEvent();
+
+            self::assertSame($ns, $decoded->getNamespace(), "case #$i: namespace");
+            self::assertSame($wfId, $decoded->getWorkflowId(), "case #$i: workflowId");
+            self::assertSame($runId, $decoded->getRunId(), "case #$i: runId");
+        }
+    }
+
+    public function testToNexusProtoLinksPassesUrlAndTypeThrough(): void
+    {
+        $uri = 'temporal:///namespaces/default/workflows/wf/run/history'
+            . '?referenceType=EventReference&eventType=WorkflowExecutionStarted';
+        $result = NexusLinkConverter::toNexusProtoLinks([new NexusLink($uri, self::TYPE)]);
+
+        self::assertCount(1, $result);
+        self::assertSame($uri, $result[0]->getUrl());
+        self::assertSame(self::TYPE, $result[0]->getType());
+    }
+
+    public function testToNexusProtoLinksKeepsCustomLinkTypes(): void
+    {
+        $custom = new NexusLink('https://example.com/x', 'custom.user.type');
+        $event = new NexusLink(
+            'temporal:///namespaces/n/workflows/w/r/history?referenceType=EventReference&eventType=WorkflowExecutionStarted',
+            self::TYPE,
+        );
+
+        $result = NexusLinkConverter::toNexusProtoLinks([$custom, $event]);
+
+        self::assertCount(2, $result);
+        self::assertSame('custom.user.type', $result[0]->getType());
+        self::assertSame(self::TYPE, $result[1]->getType());
+    }
+
+    public function testToNexusProtoLinksReturnsEmptyArrayForEmptyInput(): void
+    {
+        self::assertSame([], NexusLinkConverter::toNexusProtoLinks([]));
+    }
+}
diff --git a/tests/Unit/Internal/Support/DateIntervalTestCase.php b/tests/Unit/Internal/Support/DateIntervalTestCase.php
index dd203729e..9056b1808 100644
--- a/tests/Unit/Internal/Support/DateIntervalTestCase.php
+++ b/tests/Unit/Internal/Support/DateIntervalTestCase.php
@@ -201,7 +201,6 @@ public function testParseDetectsIso8601FormatCorrectly(string $interval, bool $s
         // Arrange
         $reflection = new \ReflectionClass(DateInterval::class);
         $method = $reflection->getMethod('isIso8601DurationFormat');
-        $method->setAccessible(true);
 
         // Act
         $result = $method->invoke(null, $interval);
diff --git a/tests/Unit/Internal/Support/SystemClockTestCase.php b/tests/Unit/Internal/Support/SystemClockTestCase.php
new file mode 100644
index 000000000..f875d4e20
--- /dev/null
+++ b/tests/Unit/Internal/Support/SystemClockTestCase.php
@@ -0,0 +1,35 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Internal\Support;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use Temporal\Internal\Support\SystemClock;
+
+#[CoversClass(SystemClock::class)]
+final class SystemClockTestCase extends TestCase
+{
+    public function testNowReturnsUtcMoment(): void
+    {
+        $clock = new SystemClock();
+        $now = $clock->now();
+        self::assertSame('UTC', $now->getTimezone()->getName());
+    }
+
+    public function testTwoCallsAreMonotonic(): void
+    {
+        $clock = new SystemClock();
+        $a = $clock->now();
+        $b = $clock->now();
+        self::assertGreaterThanOrEqual($a, $b);
+    }
+}
diff --git a/tests/Unit/Internal/Transport/Request/GetNexusOperationStartedTestCase.php b/tests/Unit/Internal/Transport/Request/GetNexusOperationStartedTestCase.php
new file mode 100644
index 000000000..0309b39f8
--- /dev/null
+++ b/tests/Unit/Internal/Transport/Request/GetNexusOperationStartedTestCase.php
@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Internal\Transport\Request;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use Temporal\Internal\Transport\Request\GetNexusOperationStarted;
+
+#[CoversClass(GetNexusOperationStarted::class)]
+final class GetNexusOperationStartedTestCase extends TestCase
+{
+    public function testNamePinsWireContract(): void
+    {
+        // Wire contract with RoadRunner — must match the case label in
+        // aggregatedpool/handler.go and the registry name in
+        // internal/protocol.go.
+        self::assertSame('GetNexusOperationStarted', GetNexusOperationStarted::NAME);
+    }
+
+    public function testCarriesStartIdInOptions(): void
+    {
+        $request = new GetNexusOperationStarted(123);
+
+        self::assertSame('GetNexusOperationStarted', $request->getName());
+        self::assertSame(['id' => 123], $request->getOptions());
+    }
+}
diff --git a/tests/Unit/Internal/Transport/Router/GetWorkerInfoTestCase.php b/tests/Unit/Internal/Transport/Router/GetWorkerInfoTestCase.php
new file mode 100644
index 000000000..0d02698df
--- /dev/null
+++ b/tests/Unit/Internal/Transport/Router/GetWorkerInfoTestCase.php
@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Internal\Transport\Router;
+
+use DateTimeImmutable;
+use PHPUnit\Framework\Attributes\CoversClass;
+use React\Promise\Deferred;
+use Temporal\DataConverter\ValuesInterface;
+use Temporal\Internal\Declaration\Prototype\NexusServicePrototype;
+use Temporal\Internal\Marshaller\MarshallerInterface;
+use Temporal\Internal\Repository\ArrayRepository;
+use Temporal\Internal\Transport\Router\GetWorkerInfo as GetWorkerInfoRoute;
+use Temporal\Plugin\PluginRegistry;
+use Temporal\Tests\TestCase;
+use Temporal\Worker\ServiceCredentials;
+use Temporal\Worker\Transport\Command\Server\ServerRequest;
+use Temporal\Worker\Transport\Command\Server\TickInfo;
+use Temporal\Worker\WorkerInterface;
+use Temporal\Worker\WorkerOptions;
+
+#[CoversClass(GetWorkerInfoRoute::class)]
+final class GetWorkerInfoTestCase extends TestCase
+{
+    public function testNexusServicesKeyIsPascalCase(): void
+    {
+        $payload = $this->dispatch(['greet']);
+
+        // Wire contract with rrtemporal: WorkerInfo.NexusServices uses the same
+        // PascalCase convention as every other top-level field. Go's JSON
+        // unmarshal is case-insensitive, so old camelCase `nexusServices`
+        // would also parse — but emitting PascalCase keeps the handshake
+        // self-consistent and matches the Go struct tag.
+        self::assertArrayHasKey('NexusServices', $payload);
+        self::assertArrayNotHasKey('nexusServices', $payload);
+    }
+
+    public function testNexusServicesShape(): void
+    {
+        $payload = $this->dispatch(['greet', 'farewell']);
+
+        self::assertSame(
+            [
+                ['name' => 'GreetingService', 'operations' => ['greet', 'farewell']],
+            ],
+            $payload['NexusServices'],
+        );
+    }
+
+    public function testFlagsDoNotAdvertiseMethodCancel(): void
+    {
+        $payload = $this->dispatch([]);
+
+        // `nexus_method_cancel` was a redundant capability signal — removed.
+        // rrtemporal now infers method-cancel support from NexusServices presence.
+        $flags = (array) $payload['Flags'];
+        self::assertArrayNotHasKey('nexus_method_cancel', $flags);
+    }
+
+    public function testFlagsRetainApiKey(): void
+    {
+        $payload = $this->dispatch([]);
+
+        $flags = (array) $payload['Flags'];
+        self::assertArrayHasKey('ApiKey', $flags);
+        self::assertSame('', $flags['ApiKey']);
+    }
+
+    /**
+     * @param list<string> $operationNames Wire keys for the single registered Nexus service.
+     * @return array<string, mixed> The first worker entry from the resolved payload.
+     */
+    private function dispatch(array $operationNames): array
+    {
+        $worker = $this->createMock(WorkerInterface::class);
+        $worker->method('getID')->willReturn('test-queue');
+        $worker->method('getOptions')->willReturn(WorkerOptions::new());
+        $worker->method('getWorkflows')->willReturn([]);
+        $worker->method('getActivities')->willReturn([]);
+        $worker->method('getNexusServices')->willReturn([
+            new NexusServicePrototype(
+                'GreetingService',
+                \array_fill_keys($operationNames, $this->stubOperationPrototype()),
+                new \ReflectionClass(\stdClass::class),
+            ),
+        ]);
+
+        $marshaller = $this->createMock(MarshallerInterface::class);
+        $marshaller->method('marshal')->willReturn([]);
+
+        $route = new GetWorkerInfoRoute(
+            new ArrayRepository([$worker]),
+            $marshaller,
+            ServiceCredentials::create(),
+            new PluginRegistry(),
+        );
+
+        $deferred = new Deferred();
+        $request = new ServerRequest('GetWorkerInfo', new TickInfo(new DateTimeImmutable()));
+        $route->handle($request, [], $deferred);
+
+        $resolved = null;
+        $deferred->promise()->then(static function (mixed $value) use (&$resolved): void {
+            $resolved = $value;
+        });
+
+        self::assertInstanceOf(ValuesInterface::class, $resolved);
+        $values = $resolved->getValues();
+        self::assertCount(1, $values, 'one worker entry expected');
+        return $values[0];
+    }
+
+    /**
+     * The route only reads operation keys via `array_keys()`, so the value
+     * type is irrelevant for the wire-shape assertion.
+     */
+    private function stubOperationPrototype(): mixed
+    {
+        return null;
+    }
+}
diff --git a/tests/Unit/Internal/Workflow/NexusOperationStubTestCase.php b/tests/Unit/Internal/Workflow/NexusOperationStubTestCase.php
new file mode 100644
index 000000000..ceb04d945
--- /dev/null
+++ b/tests/Unit/Internal/Workflow/NexusOperationStubTestCase.php
@@ -0,0 +1,312 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Internal\Workflow;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use React\Promise\Deferred;
+use React\Promise\PromiseInterface;
+use Temporal\Exception\Failure\ApplicationFailure;
+use Temporal\Exception\Failure\CanceledFailure;
+use Temporal\Exception\Failure\NexusOperationFailure;
+use Temporal\Interceptor\Header;
+use Temporal\Internal\Marshaller\MarshallerInterface;
+use Temporal\Internal\Workflow\NexusOperationStub;
+use Temporal\Workflow\NexusOperationOptions;
+
+use function React\Promise\set_rejection_handler;
+
+/**
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(NexusOperationStub::class)]
+final class NexusOperationStubTestCase extends TestCase
+{
+    public function testStartHandshakeRejectionRejectsWithTheFailure(): void
+    {
+        $started = new Deferred();
+        $result = new Deferred();
+        $token = '';
+        $handlePromise = $this->invokeHandleFromStarted($started->promise(), $result->promise(), $token);
+
+        $captured = null;
+        $handlePromise->then(
+            null,
+            static function (\Throwable $e) use (&$captured): void {
+                $captured = $e;
+            },
+        );
+
+        $failure = $this->makeFailure('start handshake failed');
+        $started->reject($failure);
+        $result->reject($failure);
+
+        self::assertSame($failure, $captured);
+    }
+
+    public function testStartHandshakeRejectionDoesNotLeakTheResultRejection(): void
+    {
+        $recorded = [];
+        $previous = set_rejection_handler(static function (\Throwable $e) use (&$recorded): void {
+            $recorded[] = $e;
+        });
+
+        try {
+            $started = new Deferred();
+            $result = new Deferred();
+            $token = '';
+            $handlePromise = $this->invokeHandleFromStarted($started->promise(), $result->promise(), $token);
+            $handlePromise->then(null, static fn(): null => null);
+
+            $started->reject($this->makeFailure('start handshake failed'));
+            $result->reject($this->makeFailure('result never delivered'));
+
+            unset($handlePromise, $started, $result);
+            \gc_collect_cycles();
+
+            self::assertSame([], $recorded);
+        } finally {
+            set_rejection_handler($previous);
+        }
+    }
+
+    public function testStartRejectsEmptyEndpoint(): void
+    {
+        $stub = $this->makeStub(NexusOperationOptions::new());
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage(
+            "Nexus stub for this operation has no endpoint set. "
+            . "Call NexusOperationOptions::withEndpoint('your-endpoint') "
+            . "before passing options to newNexusServiceStub() or newUntypedNexusOperationStub().",
+        );
+
+        $stub->start('someOp');
+    }
+
+    public function testStartRejectsEmptyEndpointMentionsServiceWhenKnown(): void
+    {
+        $stub = $this->makeStub(
+            NexusOperationOptions::new()->withService('PaymentService'),
+        );
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage(
+            "Nexus stub for service 'PaymentService' has no endpoint set. "
+            . "Call NexusOperationOptions::withEndpoint('your-endpoint') "
+            . "before passing options to newNexusServiceStub() or newUntypedNexusOperationStub().",
+        );
+
+        $stub->start('someOp');
+    }
+
+    public function testStartRejectsEmptyService(): void
+    {
+        $stub = $this->makeStub(
+            NexusOperationOptions::new()->withEndpoint('ep'),
+        );
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Nexus service is empty');
+
+        $stub->start('someOp');
+    }
+
+    public function testStartRejectsEmptyOperationName(): void
+    {
+        $stub = $this->makeStub(
+            NexusOperationOptions::new()
+                ->withEndpoint('ep')
+                ->withService('svc'),
+        );
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Nexus operation name must be a non-empty string');
+
+        $stub->start('');
+    }
+
+    public function testNormalizeFailureWrapsCanceledFailure(): void
+    {
+        $deferred = new Deferred();
+        $normalized = $this->invokeNormalizeFailure($deferred->promise());
+
+        $captured = null;
+        $normalized->then(
+            null,
+            static function (\Throwable $e) use (&$captured): void {
+                $captured = $e;
+            },
+        );
+
+        $deferred->reject(new CanceledFailure('cancelled by caller'));
+
+        self::assertInstanceOf(NexusOperationFailure::class, $captured);
+        self::assertSame('nexus operation cancelled', $captured->getOriginalMessage());
+        self::assertSame('ep', $captured->getEndpoint());
+        self::assertSame('svc', $captured->getService());
+        self::assertSame('place-order', $captured->getOperation());
+        self::assertSame('', $captured->getOperationToken());
+        self::assertSame(0, $captured->getScheduledEventId());
+        self::assertInstanceOf(CanceledFailure::class, $captured->getPrevious());
+    }
+
+    public function testNormalizeFailureWrapsGenericThrowable(): void
+    {
+        $deferred = new Deferred();
+        $normalized = $this->invokeNormalizeFailure($deferred->promise());
+
+        $captured = null;
+        $normalized->then(
+            null,
+            static function (\Throwable $e) use (&$captured): void {
+                $captured = $e;
+            },
+        );
+
+        $original = new ApplicationFailure('boom', 'BoomType', false);
+        $deferred->reject($original);
+
+        self::assertInstanceOf(NexusOperationFailure::class, $captured);
+        self::assertSame('nexus operation completed unsuccessfully', $captured->getOriginalMessage());
+        self::assertSame($original, $captured->getPrevious());
+    }
+
+    public function testNormalizeFailurePassesThroughExistingNexusOperationFailure(): void
+    {
+        $deferred = new Deferred();
+        $normalized = $this->invokeNormalizeFailure($deferred->promise());
+
+        $captured = null;
+        $normalized->then(
+            null,
+            static function (\Throwable $e) use (&$captured): void {
+                $captured = $e;
+            },
+        );
+
+        // Simulates a server-originated failure that already arrived wrapped
+        // — must not be re-wrapped (would lose the real scheduledEventId /
+        // operationToken from the wire).
+        $original = new NexusOperationFailure(
+            message: 'handler returned error',
+            scheduledEventId: 42,
+            endpoint: 'wire-ep',
+            service: 'wire-svc',
+            operation: 'wire-op',
+            operationToken: 'tok-123',
+        );
+        $deferred->reject($original);
+
+        self::assertSame($original, $captured);
+        self::assertSame(42, $captured->getScheduledEventId());
+        self::assertSame('tok-123', $captured->getOperationToken());
+        self::assertSame('wire-ep', $captured->getEndpoint());
+    }
+
+    public function testNormalizeFailureCarriesKnownOperationToken(): void
+    {
+        $deferred = new Deferred();
+        $token = '';
+        $normalized = $this->invokeNormalizeFailure($deferred->promise(), $token);
+
+        $captured = null;
+        $normalized->then(
+            null,
+            static function (\Throwable $e) use (&$captured): void {
+                $captured = $e;
+            },
+        );
+
+        $token = 'tok-async-1';
+        $deferred->reject(new CanceledFailure('cancelled after start'));
+
+        self::assertInstanceOf(NexusOperationFailure::class, $captured);
+        self::assertSame('tok-async-1', $captured->getOperationToken());
+        self::assertSame(0, $captured->getScheduledEventId());
+    }
+
+    public function testNormalizeFailurePassesThroughResolvedValue(): void
+    {
+        $deferred = new Deferred();
+        $normalized = $this->invokeNormalizeFailure($deferred->promise());
+
+        $received = null;
+        $normalized->then(
+            static function ($value) use (&$received): void {
+                $received = $value;
+            },
+        );
+
+        // Verifies the success path is not broken by the new rejection-only
+        // handler — values flow through unchanged.
+        $deferred->resolve('payload');
+
+        self::assertSame('payload', $received);
+    }
+
+    public function testGetOptionsReturnsTheStubOptions(): void
+    {
+        $options = NexusOperationOptions::new()->withEndpoint('ep')->withService('svc');
+        $stub = $this->makeStub($options);
+
+        self::assertSame($options, $stub->getOptions());
+    }
+
+    private function makeFailure(string $message): NexusOperationFailure
+    {
+        return new NexusOperationFailure(
+            message: $message,
+            scheduledEventId: 0,
+            endpoint: 'ep',
+            service: 'svc',
+            operation: 'place-order',
+            operationToken: '',
+        );
+    }
+
+    private function invokeHandleFromStarted(
+        PromiseInterface $startedPromise,
+        PromiseInterface $resultPromise,
+        string &$operationToken,
+    ): PromiseInterface {
+        $stub = $this->makeStub(
+            NexusOperationOptions::new()->withEndpoint('ep')->withService('svc'),
+        );
+
+        $method = new \ReflectionMethod(NexusOperationStub::class, 'handleFromStarted');
+
+        return $method->invokeArgs($stub, [$startedPromise, $resultPromise, null, &$operationToken]);
+    }
+
+    private function makeStub(NexusOperationOptions $options): NexusOperationStub
+    {
+        /** @var MarshallerInterface<array> $marshaller */
+        $marshaller = $this->createStub(MarshallerInterface::class);
+        return new NexusOperationStub(
+            $marshaller,
+            $options,
+            Header::empty(),
+        );
+    }
+
+    /**
+     * Reach into the private normalizeFailure() — the class is final so we
+     * cannot subclass to override request(), and start() requires a real
+     * Workflow context. Reflection keeps the unit boundary at the function
+     * under test without dragging in the workflow runtime.
+     */
+    private function invokeNormalizeFailure(PromiseInterface $promise, string &$operationToken = ''): PromiseInterface
+    {
+        $stub = $this->makeStub(
+            NexusOperationOptions::new()->withEndpoint('ep')->withService('svc'),
+        );
+
+        $method = new \ReflectionMethod(NexusOperationStub::class, 'normalizeFailure');
+
+        return $method->invokeArgs($stub, [$promise, 'ep', 'svc', 'place-order', &$operationToken]);
+    }
+}
diff --git a/tests/Unit/Internal/Workflow/NexusServiceProxyTestCase.php b/tests/Unit/Internal/Workflow/NexusServiceProxyTestCase.php
new file mode 100644
index 000000000..dd95dfac2
--- /dev/null
+++ b/tests/Unit/Internal/Workflow/NexusServiceProxyTestCase.php
@@ -0,0 +1,169 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Internal\Workflow;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use React\Promise\PromiseInterface;
+use Temporal\DataConverter\Type;
+use Temporal\Interceptor\Trait\WorkflowOutboundCallsInterceptorTrait;
+use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteNexusOperationInput;
+use Temporal\Interceptor\WorkflowOutboundCallsInterceptor;
+use Temporal\Internal\Declaration\Prototype\NexusOperationPrototype;
+use Temporal\Internal\Declaration\Prototype\NexusServicePrototype;
+use Temporal\Internal\Interceptor\Pipeline;
+use Temporal\Internal\Workflow\NexusOperationStub;
+use Temporal\Internal\Workflow\NexusServiceProxy;
+use Temporal\Internal\Workflow\WorkflowContext;
+use Temporal\Workflow\NexusOperationOptions;
+
+use function React\Promise\resolve;
+
+/**
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(NexusServiceProxy::class)]
+final class NexusServiceProxyTestCase extends TestCase
+{
+    public function testInterceptorEndpointRewriteChangesOutgoingOptions(): void
+    {
+        $captured = null;
+        $proxy = $this->makeProxy(
+            $this->makeContext($captured),
+            new class implements WorkflowOutboundCallsInterceptor {
+                use WorkflowOutboundCallsInterceptorTrait;
+
+                public function executeNexusOperation(
+                    ExecuteNexusOperationInput $input,
+                    callable $next,
+                ): PromiseInterface {
+                    return $next($input->with(endpoint: 'rewritten-ep'));
+                }
+            },
+        );
+
+        $proxy->placeOrder('order-1');
+
+        self::assertInstanceOf(NexusOperationOptions::class, $captured);
+        self::assertSame('rewritten-ep', $captured->endpoint);
+        self::assertSame('OrderService', $captured->service);
+    }
+
+    public function testInterceptorServiceRewriteChangesOutgoingOptions(): void
+    {
+        $captured = null;
+        $proxy = $this->makeProxy(
+            $this->makeContext($captured),
+            new class implements WorkflowOutboundCallsInterceptor {
+                use WorkflowOutboundCallsInterceptorTrait;
+
+                public function executeNexusOperation(
+                    ExecuteNexusOperationInput $input,
+                    callable $next,
+                ): PromiseInterface {
+                    return $next($input->with(service: 'RewrittenService'));
+                }
+            },
+        );
+
+        $proxy->placeOrder('order-1');
+
+        self::assertInstanceOf(NexusOperationOptions::class, $captured);
+        self::assertSame('orig-ep', $captured->endpoint);
+        self::assertSame('RewrittenService', $captured->service);
+    }
+
+    public function testWithoutInterceptorsOptionsPassThroughUnchanged(): void
+    {
+        $captured = null;
+        $proxy = $this->makeProxy($this->makeContext($captured));
+
+        $proxy->placeOrder('order-1');
+
+        self::assertInstanceOf(NexusOperationOptions::class, $captured);
+        self::assertSame('orig-ep', $captured->endpoint);
+        self::assertSame('OrderService', $captured->service);
+    }
+
+    public function testUnknownMethodThrowsBadMethodCall(): void
+    {
+        $captured = null;
+        $proxy = $this->makeProxy($this->makeContext($captured));
+
+        $this->expectException(\BadMethodCallException::class);
+        $this->expectExceptionMessage('has no operation method "unknownMethod"');
+
+        $proxy->unknownMethod();
+    }
+
+    private function makeProxy(
+        WorkflowContext $ctx,
+        WorkflowOutboundCallsInterceptor ...$interceptors,
+    ): NexusServiceProxy {
+        $reflection = new \ReflectionClass(NexusProxyTestService::class);
+        $operation = new NexusOperationPrototype(
+            name: 'place-order',
+            methodName: 'placeOrder',
+            inputType: Type::create(Type::TYPE_STRING),
+            outputType: Type::create(Type::TYPE_STRING),
+            async: false,
+            handler: $reflection->getMethod('placeOrder'),
+        );
+
+        return new NexusServiceProxy(
+            NexusProxyTestService::class,
+            new NexusServicePrototype('OrderService', ['place-order' => $operation], $reflection),
+            NexusOperationOptions::new()->withEndpoint('orig-ep')->withService('OrderService'),
+            $ctx,
+            Pipeline::prepare($interceptors),
+        );
+    }
+
+    private function makeContext(?NexusOperationOptions &$captured): WorkflowContext
+    {
+        $ctx = $this->createMock(WorkflowContext::class);
+        $ctx->method('newUntypedNexusOperationStub')
+            ->willReturnCallback(static function (NexusOperationOptions $options) use (&$captured) {
+                $captured = $options;
+
+                return new class($options) extends NexusOperationStub {
+                    public function __construct(
+                        private readonly NexusOperationOptions $capturedOptions,
+                    ) {}
+
+                    public function getOptions(): NexusOperationOptions
+                    {
+                        return $this->capturedOptions;
+                    }
+
+                    public function execute(
+                        string $operation,
+                        array $args = [],
+                        Type|string|\ReflectionClass|\ReflectionType|null $returnType = null,
+                        array $nexusHeaders = [],
+                    ): PromiseInterface {
+                        return resolve(null);
+                    }
+
+                    public function start(
+                        string $operation,
+                        array $args = [],
+                        Type|string|\ReflectionClass|\ReflectionType|null $returnType = null,
+                        array $nexusHeaders = [],
+                    ): PromiseInterface {
+                        return resolve(null);
+                    }
+                };
+            });
+
+        return $ctx;
+    }
+}
+
+interface NexusProxyTestService
+{
+    public function placeOrder(string $order): string;
+}
diff --git a/tests/Unit/Internal/Workflow/WorkflowContextNexusOptionsTestCase.php b/tests/Unit/Internal/Workflow/WorkflowContextNexusOptionsTestCase.php
new file mode 100644
index 000000000..55a7d0cb5
--- /dev/null
+++ b/tests/Unit/Internal/Workflow/WorkflowContextNexusOptionsTestCase.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Internal\Workflow;
+
+use PHPUnit\Framework\TestCase;
+use Temporal\Interceptor\WorkflowOutboundCalls\ExecuteNexusOperationInput;
+use Temporal\Workflow\NexusOperationCancellationType;
+use Temporal\Workflow\NexusOperationOptions;
+
+/**
+ * @group unit
+ * @group nexus
+ */
+final class WorkflowContextNexusOptionsTestCase extends TestCase
+{
+    public function testInterceptorEndpointAndServiceRewritesAreHonored(): void
+    {
+        $options = NexusOperationOptions::new()
+            ->withEndpoint('orig-ep')
+            ->withService('OrderService')
+            ->withCancellationType(NexusOperationCancellationType::Abandon);
+        $input = $this->makeInput($options)->with(endpoint: 'new-ep', service: 'NewService');
+
+        $effective = $this->deriveOptions($input);
+
+        self::assertSame('new-ep', $effective->endpoint);
+        self::assertSame('NewService', $effective->service);
+        self::assertSame(NexusOperationCancellationType::Abandon, $effective->cancellationType);
+    }
+
+    public function testUntouchedInputReturnsOriginalOptionsInstance(): void
+    {
+        $options = NexusOperationOptions::new()
+            ->withEndpoint('orig-ep')
+            ->withService('OrderService');
+
+        self::assertSame($options, $this->deriveOptions($this->makeInput($options)));
+    }
+
+    private function makeInput(NexusOperationOptions $options): ExecuteNexusOperationInput
+    {
+        return new ExecuteNexusOperationInput(
+            $options->endpoint,
+            $options->service,
+            'place-order',
+            [],
+            $options,
+            null,
+        );
+    }
+
+    private function deriveOptions(ExecuteNexusOperationInput $input): NexusOperationOptions
+    {
+        return $input->effectiveOptions();
+    }
+}
diff --git a/tests/Unit/Nexus/AwaitsNexusPromise.php b/tests/Unit/Nexus/AwaitsNexusPromise.php
new file mode 100644
index 000000000..08bc2e7a4
--- /dev/null
+++ b/tests/Unit/Nexus/AwaitsNexusPromise.php
@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Nexus;
+
+use PHPUnit\Framework\Assert;
+use React\Promise\Deferred;
+use Temporal\DataConverter\ValuesInterface;
+use Temporal\Worker\Transport\Command\Client\CommandResponse;
+
+/**
+ * Synchronous settle helpers for the already-settled promises produced by Nexus routes.
+ */
+trait AwaitsNexusPromise
+{
+    private function await(Deferred $deferred): mixed
+    {
+        $result = null;
+        $error = null;
+        $settled = false;
+
+        $deferred->promise()->then(
+            static function (mixed $value) use (&$result, &$settled): void {
+                $result = $value;
+                $settled = true;
+            },
+            static function (\Throwable $e) use (&$error): void {
+                $error = $e;
+            },
+        );
+
+        if ($error !== null) {
+            throw $error;
+        }
+
+        Assert::assertTrue($settled, 'promise should resolve');
+        return $result;
+    }
+
+    private function assertResolved(Deferred $deferred): void
+    {
+        $this->await($deferred);
+    }
+
+    private function awaitReply(Deferred $deferred): CommandResponse
+    {
+        $result = $this->await($deferred);
+        Assert::assertInstanceOf(CommandResponse::class, $result);
+        return $result;
+    }
+
+    private function awaitCancelResult(Deferred $deferred): ValuesInterface
+    {
+        $result = $this->await($deferred);
+        Assert::assertInstanceOf(ValuesInterface::class, $result);
+        return $result;
+    }
+}
diff --git a/tests/Unit/Nexus/CancelNexusOperationMethodRouteTestCase.php b/tests/Unit/Nexus/CancelNexusOperationMethodRouteTestCase.php
new file mode 100644
index 000000000..3d76ecc20
--- /dev/null
+++ b/tests/Unit/Nexus/CancelNexusOperationMethodRouteTestCase.php
@@ -0,0 +1,118 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Nexus;
+
+use Temporal\Nexus\Handler\MethodCanceller;
+use React\Promise\Deferred;
+use Temporal\Internal\Nexus\NexusInvocationRegistry;
+use Temporal\Internal\Transport\Router\CancelNexusOperationMethod;
+use PHPUnit\Framework\Attributes\CoversClass;
+use Temporal\Tests\Unit\AbstractUnit;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+use Temporal\Worker\Transport\Command\Server\ServerRequest;
+use Temporal\Worker\Transport\Command\Server\TickInfo;
+
+/**
+ * Unit tests for the `CancelNexusOperationMethod` router.
+ *
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(CancelNexusOperationMethod::class)]
+final class CancelNexusOperationMethodRouteTestCase extends AbstractUnit
+{
+    use AwaitsNexusPromise;
+
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    public function testRouteName(): void
+    {
+        $route = new CancelNexusOperationMethod(new NexusInvocationRegistry());
+
+        self::assertSame('CancelNexusOperationMethod', $route->getName());
+    }
+
+    public function testCancelsRegisteredInvocationWithReason(): void
+    {
+        $registry = new NexusInvocationRegistry();
+        $canceller = new MethodCanceller($this->env);
+        $registry->register(42, $canceller);
+
+        $route = new CancelNexusOperationMethod($registry);
+        $request = $this->makeRequest(['invocationId' => 42, 'reason' => 'deadline']);
+
+        $deferred = new Deferred();
+        $route->handle($request, [], $deferred);
+
+        $this->assertResolved($deferred);
+        self::assertTrue($canceller->isCancelled());
+        self::assertSame('deadline', $canceller->getReason());
+    }
+
+    public function testUnknownInvocationIdIsNoOp(): void
+    {
+        $registry = new NexusInvocationRegistry();
+        $route = new CancelNexusOperationMethod($registry);
+        $request = $this->makeRequest(['invocationId' => 999, 'reason' => 'x']);
+
+        $deferred = new Deferred();
+        $route->handle($request, [], $deferred);
+
+        // Still resolves cleanly — a late cancel after handler finished is legitimate.
+        $this->assertResolved($deferred);
+    }
+
+    public function testZeroInvocationIdSkipsLookup(): void
+    {
+        $registry = new NexusInvocationRegistry();
+        $canceller = new MethodCanceller($this->env);
+        // 0 must NEVER be a valid key — RR assigns monotonic non-zero ids.
+        $registry->register(0, $canceller);
+
+        $route = new CancelNexusOperationMethod($registry);
+        $request = $this->makeRequest(['invocationId' => 0, 'reason' => 'x']);
+
+        $deferred = new Deferred();
+        $route->handle($request, [], $deferred);
+
+        $this->assertResolved($deferred);
+        self::assertFalse(
+            $canceller->isCancelled(),
+            '0 is the sentinel for "no invocation id" and must not touch the registry',
+        );
+    }
+
+    public function testMissingReasonDefaultsToEmptyString(): void
+    {
+        $registry = new NexusInvocationRegistry();
+        $canceller = new MethodCanceller($this->env);
+        $registry->register(5, $canceller);
+
+        $route = new CancelNexusOperationMethod($registry);
+        $request = $this->makeRequest(['invocationId' => 5]);
+
+        $deferred = new Deferred();
+        $route->handle($request, [], $deferred);
+
+        $this->assertResolved($deferred);
+        self::assertSame('', $canceller->getReason());
+    }
+
+    private function makeRequest(array $options): ServerRequest
+    {
+        return new ServerRequest(
+            name: 'CancelNexusOperationMethod',
+            info: new TickInfo(new \DateTimeImmutable()),
+            options: $options,
+        );
+    }
+}
diff --git a/tests/Unit/Nexus/CancelNexusOperationRouteTestCase.php b/tests/Unit/Nexus/CancelNexusOperationRouteTestCase.php
new file mode 100644
index 000000000..dcc651606
--- /dev/null
+++ b/tests/Unit/Nexus/CancelNexusOperationRouteTestCase.php
@@ -0,0 +1,162 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Nexus;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use React\Promise\Deferred;
+use Spiral\Attributes\AttributeReader;
+use Temporal\DataConverter\DataConverter;
+use Temporal\Internal\Declaration\Prototype\NexusServiceCollection;
+use Temporal\Internal\Declaration\Reader\NexusServiceReader;
+use Temporal\Internal\Marshaller\Mapper\AttributeMapperFactory;
+use Temporal\Internal\Marshaller\Marshaller;
+use Temporal\Internal\Nexus\NexusTaskHandler;
+use Temporal\Internal\Transport\Router\CancelNexusOperation;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+use Temporal\Tests\Unit\AbstractUnit;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+use Temporal\Worker\Transport\Command\Server\ServerRequest;
+use Temporal\Worker\Transport\Command\Server\TickInfo;
+
+#[Service(name: 'RouteHeaderService')]
+interface RouteHeaderService
+{
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function op(): RouteHeaderOpHandler;
+}
+
+final class RouteHeaderOpHandler implements OperationHandlerInterface
+{
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        return OperationStartResult::async(new OperationInfo('tok', OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {
+        RouteHeaderServiceImpl::$capturedCancelHeaders = Nexus::getCurrentOperationContext()->headers->all();
+    }
+}
+
+class RouteHeaderServiceImpl implements RouteHeaderService
+{
+    /** @var array<string, string> */
+    public static array $capturedCancelHeaders = [];
+
+    public function op(): RouteHeaderOpHandler
+    {
+        return new RouteHeaderOpHandler();
+    }
+}
+
+/**
+ * Unit tests for the `CancelNexusOperation` router — the `options['headers']`
+ * map (sent by RoadRunner on the cancel command) must surface on the handler's
+ * OperationContext, symmetric with the start path.
+ *
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(CancelNexusOperation::class)]
+final class CancelNexusOperationRouteTestCase extends AbstractUnit
+{
+    use AwaitsNexusPromise;
+
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+        RouteHeaderServiceImpl::$capturedCancelHeaders = [];
+    }
+
+    public function testRouteName(): void
+    {
+        $route = new CancelNexusOperation($this->buildHandler(), $this->buildMarshaller());
+
+        self::assertSame('CancelNexusOperation', $route->getName());
+    }
+
+    public function testForwardsOptionHeadersToHandlerContext(): void
+    {
+        $route = new CancelNexusOperation($this->buildHandler(), $this->buildMarshaller());
+        $request = $this->makeRequest([
+            'service' => 'RouteHeaderService',
+            'operation' => 'op',
+            'operationToken' => 'tok',
+            'headers' => [
+                'X-Nexus-Trace-Id' => 'trace-1',
+                'Authorization' => 'Bearer xyz',
+            ],
+        ]);
+
+        $deferred = new Deferred();
+        $route->handle($request, [], $deferred);
+
+        $this->assertResolved($deferred);
+        // OperationContext lowercases header keys on construction.
+        self::assertSame('trace-1', RouteHeaderServiceImpl::$capturedCancelHeaders['x-nexus-trace-id'] ?? null);
+        self::assertSame('Bearer xyz', RouteHeaderServiceImpl::$capturedCancelHeaders['authorization'] ?? null);
+    }
+
+    public function testMissingHeadersResolvesWithEmptyContextHeaders(): void
+    {
+        $route = new CancelNexusOperation($this->buildHandler(), $this->buildMarshaller());
+        $request = $this->makeRequest([
+            'service' => 'RouteHeaderService',
+            'operation' => 'op',
+            'operationToken' => 'tok',
+        ]);
+
+        $deferred = new Deferred();
+        $route->handle($request, [], $deferred);
+
+        $this->assertResolved($deferred);
+        self::assertSame([], RouteHeaderServiceImpl::$capturedCancelHeaders);
+    }
+
+    private function buildHandler(): NexusTaskHandler
+    {
+        $reader = new NexusServiceReader(new AttributeReader());
+        $collection = new NexusServiceCollection();
+        $prototype = $reader->fromClass(RouteHeaderServiceImpl::class)->withInstance(new RouteHeaderServiceImpl());
+        $collection->add($prototype, false);
+
+        return new NexusTaskHandler($collection, DataConverter::createDefault(), $this->env);
+    }
+
+    private function buildMarshaller(): Marshaller
+    {
+        return new Marshaller(new AttributeMapperFactory(new AttributeReader()));
+    }
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    private function makeRequest(array $options): ServerRequest
+    {
+        return new ServerRequest(
+            name: 'CancelNexusOperation',
+            info: new TickInfo(new \DateTimeImmutable()),
+            options: $options,
+        );
+    }
+}
diff --git a/tests/Unit/Nexus/HandlerErrorMapperTestCase.php b/tests/Unit/Nexus/HandlerErrorMapperTestCase.php
new file mode 100644
index 000000000..b7a5737a1
--- /dev/null
+++ b/tests/Unit/Nexus/HandlerErrorMapperTestCase.php
@@ -0,0 +1,187 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Nexus;
+
+use Google\Rpc\Code;
+use Temporal\DataConverter\EncodedValues;
+use Temporal\Exception\Client\ServiceClientException;
+use Temporal\Exception\Client\WorkflowException;
+use Temporal\Exception\Client\WorkflowExecutionAlreadyStartedException;
+use Temporal\Exception\Client\WorkflowFailedException;
+use Temporal\Exception\Client\WorkflowNotFoundException;
+use Temporal\Exception\Client\WorkflowServiceException;
+use Temporal\Exception\Failure\ApplicationFailure;
+use Temporal\Internal\Nexus\HandlerErrorMapper;
+use Temporal\Workflow\WorkflowExecution;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\RetryBehavior;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\UsesClass;
+use Temporal\Tests\Unit\AbstractUnit;
+
+#[CoversClass(HandlerErrorMapper::class)]
+#[UsesClass(HandlerException::class)]
+#[UsesClass(ErrorType::class)]
+#[UsesClass(RetryBehavior::class)]
+final class HandlerErrorMapperTestCase extends AbstractUnit
+{
+    /**
+     * @return iterable<string, array{0: int, 1: ErrorType, 2: RetryBehavior}>
+     */
+    public static function grpcCodeMatrix(): iterable
+    {
+        // Mirrors Go internal_nexus_task_handler.go:592-647 and Java NexusTaskHandlerImpl.java:236-269.
+        yield 'INVALID_ARGUMENT → BadRequest' => [Code::INVALID_ARGUMENT, ErrorType::BadRequest, RetryBehavior::Unspecified];
+        yield 'ALREADY_EXISTS → Internal/NonRetryable' => [Code::ALREADY_EXISTS, ErrorType::Internal, RetryBehavior::NonRetryable];
+        yield 'FAILED_PRECONDITION → Internal/NonRetryable' => [Code::FAILED_PRECONDITION, ErrorType::Internal, RetryBehavior::NonRetryable];
+        yield 'OUT_OF_RANGE → Internal/NonRetryable' => [Code::OUT_OF_RANGE, ErrorType::Internal, RetryBehavior::NonRetryable];
+        yield 'ABORTED → Unavailable' => [Code::ABORTED, ErrorType::Unavailable, RetryBehavior::Unspecified];
+        yield 'UNAVAILABLE → Unavailable' => [Code::UNAVAILABLE, ErrorType::Unavailable, RetryBehavior::Unspecified];
+        yield 'CANCELLED → Internal' => [Code::CANCELLED, ErrorType::Internal, RetryBehavior::Unspecified];
+        yield 'DATA_LOSS → Internal' => [Code::DATA_LOSS, ErrorType::Internal, RetryBehavior::Unspecified];
+        yield 'INTERNAL → Internal' => [Code::INTERNAL, ErrorType::Internal, RetryBehavior::Unspecified];
+        yield 'UNKNOWN → Internal' => [Code::UNKNOWN, ErrorType::Internal, RetryBehavior::Unspecified];
+        yield 'UNAUTHENTICATED → Internal' => [Code::UNAUTHENTICATED, ErrorType::Internal, RetryBehavior::Unspecified];
+        yield 'PERMISSION_DENIED → Internal' => [Code::PERMISSION_DENIED, ErrorType::Internal, RetryBehavior::Unspecified];
+        yield 'NOT_FOUND → NotFound' => [Code::NOT_FOUND, ErrorType::NotFound, RetryBehavior::Unspecified];
+        yield 'RESOURCE_EXHAUSTED → ResourceExhausted' => [Code::RESOURCE_EXHAUSTED, ErrorType::ResourceExhausted, RetryBehavior::Unspecified];
+        yield 'UNIMPLEMENTED → NotImplemented' => [Code::UNIMPLEMENTED, ErrorType::NotImplemented, RetryBehavior::Unspecified];
+        yield 'DEADLINE_EXCEEDED → UpstreamTimeout' => [Code::DEADLINE_EXCEEDED, ErrorType::UpstreamTimeout, RetryBehavior::Unspecified];
+    }
+
+    #[DataProvider('grpcCodeMatrix')]
+    public function testMapsGrpcCodeToHandlerException(
+        int $code,
+        ErrorType $expectedType,
+        RetryBehavior $expectedRetry,
+    ): void {
+        $exception = self::makeServiceClientException($code, 'wire detail');
+
+        $mapped = HandlerErrorMapper::mapToHandlerException($exception);
+
+        self::assertInstanceOf(HandlerException::class, $mapped);
+        self::assertSame($expectedType, $mapped->errorType);
+        self::assertSame($expectedRetry, $mapped->retryBehavior);
+        self::assertSame($exception, $mapped->getPrevious(), 'Original gRPC exception preserved as cause');
+    }
+
+    public function testUnknownGrpcCodeFallsBackToInternal(): void
+    {
+        $exception = self::makeServiceClientException(9999, 'weird');
+
+        $mapped = HandlerErrorMapper::mapToHandlerException($exception);
+
+        self::assertInstanceOf(HandlerException::class, $mapped);
+        self::assertSame(ErrorType::Internal, $mapped->errorType);
+        self::assertSame(RetryBehavior::Unspecified, $mapped->retryBehavior);
+    }
+
+    public function testNonRetryableApplicationFailureBecomesInternalNonRetryable(): void
+    {
+        $cause = new ApplicationFailure(
+            'business invariant violated',
+            'BusinessError',
+            true,
+            EncodedValues::empty(),
+        );
+
+        $mapped = HandlerErrorMapper::mapToHandlerException($cause);
+
+        self::assertInstanceOf(HandlerException::class, $mapped);
+        self::assertSame(ErrorType::Internal, $mapped->errorType);
+        self::assertSame(RetryBehavior::NonRetryable, $mapped->retryBehavior);
+        self::assertSame($cause, $mapped->getPrevious());
+    }
+
+    public function testRetryableApplicationFailureIsNotMapped(): void
+    {
+        $cause = new ApplicationFailure(
+            'transient',
+            'TransientError',
+            false,
+            EncodedValues::empty(),
+        );
+
+        self::assertNull(HandlerErrorMapper::mapToHandlerException($cause));
+    }
+
+    public function testWorkflowNotFoundExceptionBecomesNotFound(): void
+    {
+        $cause = new WorkflowNotFoundException(null, new WorkflowExecution('wf-id', 'run-id'));
+
+        $mapped = HandlerErrorMapper::mapToHandlerException($cause);
+
+        self::assertInstanceOf(HandlerException::class, $mapped);
+        self::assertSame(ErrorType::NotFound, $mapped->errorType);
+        self::assertSame(RetryBehavior::Unspecified, $mapped->retryBehavior);
+        self::assertSame($cause, $mapped->getPrevious());
+    }
+
+    public function testWorkflowExceptionWithoutGrpcCauseIsMappedToBadRequest(): void
+    {
+        $cause = new WorkflowException(null, new WorkflowExecution('wf-id', 'run-id'));
+
+        $mapped = HandlerErrorMapper::mapToHandlerException($cause);
+
+        self::assertInstanceOf(HandlerException::class, $mapped);
+        self::assertSame(ErrorType::BadRequest, $mapped->errorType);
+        self::assertSame(RetryBehavior::Unspecified, $mapped->retryBehavior);
+        self::assertSame($cause, $mapped->getPrevious());
+    }
+
+    public function testWorkflowFailedExceptionIsMappedToBadRequest(): void
+    {
+        $cause = new WorkflowFailedException(new WorkflowExecution('wf-id', 'run-id'), 'WorkflowType', 1, 0);
+
+        $mapped = HandlerErrorMapper::mapToHandlerException($cause);
+
+        self::assertInstanceOf(HandlerException::class, $mapped);
+        self::assertSame(ErrorType::BadRequest, $mapped->errorType);
+    }
+
+    public function testWorkflowServiceExceptionUnwrapsTransientGrpcCause(): void
+    {
+        $grpc = self::makeServiceClientException(Code::UNAVAILABLE, 'frontend unavailable');
+        $cause = new WorkflowServiceException(null, new WorkflowExecution('wf-id', 'run-id'), null, $grpc);
+
+        $mapped = HandlerErrorMapper::mapToHandlerException($cause);
+
+        self::assertInstanceOf(HandlerException::class, $mapped);
+        self::assertSame(ErrorType::Unavailable, $mapped->errorType);
+        self::assertSame(RetryBehavior::Unspecified, $mapped->retryBehavior);
+        self::assertTrue($mapped->isRetryable());
+        self::assertSame($grpc, $mapped->getPrevious());
+    }
+
+    public function testWorkflowExecutionAlreadyStartedExceptionBecomesInternalNonRetryable(): void
+    {
+        $cause = new WorkflowExecutionAlreadyStartedException(new WorkflowExecution('wf-id', 'run-id'), 'WorkflowType');
+
+        $mapped = HandlerErrorMapper::mapToHandlerException($cause);
+
+        self::assertInstanceOf(HandlerException::class, $mapped);
+        self::assertSame(ErrorType::Internal, $mapped->errorType);
+        self::assertSame(RetryBehavior::NonRetryable, $mapped->retryBehavior);
+        self::assertSame($cause, $mapped->getPrevious());
+    }
+
+    public function testGenericRuntimeExceptionIsNotMapped(): void
+    {
+        self::assertNull(HandlerErrorMapper::mapToHandlerException(new \RuntimeException('boom')));
+        self::assertNull(HandlerErrorMapper::mapToHandlerException(new \LogicException('boom')));
+    }
+
+    private static function makeServiceClientException(int $code, string $detail): ServiceClientException
+    {
+        $status = new \stdClass();
+        $status->code = $code;
+        $status->details = $detail;
+        $status->metadata = [];
+
+        return new ServiceClientException($status);
+    }
+}
diff --git a/tests/Unit/Nexus/NexusContextAccessorTestCase.php b/tests/Unit/Nexus/NexusContextAccessorTestCase.php
new file mode 100644
index 000000000..0510e74f6
--- /dev/null
+++ b/tests/Unit/Nexus/NexusContextAccessorTestCase.php
@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Nexus;
+
+use PHPUnit\Framework\MockObject\MockObject;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Internal\Nexus\NexusContext;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Nexus;
+use PHPUnit\Framework\Attributes\CoversClass;
+use Temporal\Nexus\NexusOperationContext;
+use Temporal\Tests\Unit\AbstractUnit;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+
+/**
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(Nexus::class)]
+final class NexusContextAccessorTestCase extends AbstractUnit
+{
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    protected function tearDown(): void
+    {
+        // Always clear — leaking a context would poison sibling tests that
+        // rely on `getOperationContext()` throwing outside a handler.
+        Nexus::setCurrentContext(null);
+    }
+
+    public function testOutsideDispatchThrows(): void
+    {
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessage('The Nexus facade can be used only inside a Nexus operation handler.');
+        Nexus::getOperationContext();
+    }
+
+    public function testReturnsCurrentContext(): void
+    {
+        /** @var WorkflowClientInterface&MockObject $client */
+        $client = $this->createMock(WorkflowClientInterface::class);
+        $ctx = new NexusOperationContext('ns', 'tq');
+
+        Nexus::setCurrentContext(new NexusContext(
+            current: new OperationContext(service: 'svc', operation: 'op', env: $this->env),
+            operation: $ctx,
+            workflowClient: $client,
+        ));
+
+        self::assertSame($ctx, Nexus::getOperationContext());
+        self::assertSame('ns', Nexus::getOperationContext()->namespace);
+        self::assertSame('tq', Nexus::getOperationContext()->taskQueue);
+    }
+
+    public function testPublicContextDoesNotExposeWorkflowClient(): void
+    {
+        $ctx = new NexusOperationContext('ns', 'tq');
+
+        self::assertFalse(
+            \property_exists($ctx, 'workflowClient'),
+            'NexusOperationContext must not leak the WorkflowClient into public API surface',
+        );
+    }
+
+    public function testClearingRestoresOutsideBehavior(): void
+    {
+        Nexus::setCurrentContext(new NexusContext(
+            current: new OperationContext(service: 'svc', operation: 'op', env: $this->env),
+            operation: new NexusOperationContext('ns', 'tq'),
+        ));
+        Nexus::setCurrentContext(null);
+
+        $this->expectException(\LogicException::class);
+        Nexus::getOperationContext();
+    }
+}
diff --git a/tests/Unit/Nexus/NexusInvocationRegistryTestCase.php b/tests/Unit/Nexus/NexusInvocationRegistryTestCase.php
new file mode 100644
index 000000000..f196eaae5
--- /dev/null
+++ b/tests/Unit/Nexus/NexusInvocationRegistryTestCase.php
@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Nexus;
+
+use Temporal\Nexus\Handler\MethodCanceller;
+use PHPUnit\Framework\Attributes\CoversClass;
+use Temporal\Internal\Nexus\NexusInvocationRegistry;
+use Temporal\Tests\Unit\AbstractUnit;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+
+/**
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(NexusInvocationRegistry::class)]
+final class NexusInvocationRegistryTestCase extends AbstractUnit
+{
+    private EnvironmentInterface $env;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->env = new Environment();
+    }
+
+    public function testGetReturnsNullForUnknownId(): void
+    {
+        $registry = new NexusInvocationRegistry();
+
+        self::assertNull($registry->get(42));
+    }
+
+    public function testUnregisterRemovesEntry(): void
+    {
+        $registry = new NexusInvocationRegistry();
+        $canceller = new MethodCanceller($this->env);
+        $registry->register(5, $canceller);
+
+        $registry->unregister(5);
+
+        self::assertNull($registry->get(5));
+    }
+
+    public function testUnregisterUnknownIdIsNoOp(): void
+    {
+        $registry = new NexusInvocationRegistry();
+
+        // Must not throw.
+        $registry->unregister(999);
+
+        self::assertNull($registry->get(999));
+    }
+
+    public function testEntriesAreIsolatedByKey(): void
+    {
+        $registry = new NexusInvocationRegistry();
+        $a = new MethodCanceller($this->env);
+        $b = new MethodCanceller($this->env);
+        $registry->register(1, $a);
+        $registry->register(2, $b);
+
+        self::assertSame($a, $registry->get(1));
+        self::assertSame($b, $registry->get(2));
+    }
+
+    public function testCancelThroughRegistryAffectsOriginalCanceller(): void
+    {
+        $registry = new NexusInvocationRegistry();
+        $canceller = new MethodCanceller($this->env);
+        $registry->register(7, $canceller);
+
+        $registry->get(7)?->cancel('deadline');
+
+        self::assertTrue($canceller->isCancelled());
+        self::assertSame('deadline', $canceller->getReason());
+    }
+}
diff --git a/tests/Unit/Nexus/NexusOperationRoutesTestCase.php b/tests/Unit/Nexus/NexusOperationRoutesTestCase.php
new file mode 100644
index 000000000..63222dd51
--- /dev/null
+++ b/tests/Unit/Nexus/NexusOperationRoutesTestCase.php
@@ -0,0 +1,732 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Nexus;
+
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Exception\ErrorType as NexusErrorType;
+use Temporal\Nexus\Exception\HandlerException as NexusHandlerException;
+use Temporal\Nexus\Exception\OperationException;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\Link;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+use React\Promise\Deferred;
+use Temporal\DataConverter\DataConverter;
+use Temporal\DataConverter\EncodedValues;
+use Temporal\DataConverter\ValuesInterface;
+use Temporal\Internal\Nexus\NexusTaskHandler;
+use Temporal\Internal\Transport\Router\CancelNexusOperation;
+use Temporal\Internal\Transport\Router\InvokeNexusOperation;
+use PHPUnit\Framework\Attributes\CoversClass;
+use Temporal\Tests\Nexus\Support\ExceptionAssertions;
+use Temporal\Tests\Unit\AbstractUnit;
+use Temporal\Worker\Transport\Command\Client\CommandResponse;
+use Temporal\Worker\Transport\Command\Server\ServerRequest;
+use Temporal\Worker\Transport\Command\Server\TickInfo;
+
+// ── Test service definitions ─────────────────────────────────────────
+
+#[Service(name: 'EchoService')]
+interface EchoServiceInterface
+{
+    #[Operation]
+    public function echo(string $input): string;
+
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function asyncEcho(): EchoAsyncHandler;
+
+    #[Operation]
+    public function failOp(string $input): string;
+
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function cancelOp(): EchoCancelRecordingHandler;
+
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function cancelThrowsOp(): EchoCancelThrowsHandler;
+
+    #[Operation]
+    public function echoWithLinks(string $input): string;
+
+    /**
+     * Reads caller-side links from $details->links and serialises them into the result.
+     */
+    #[Operation]
+    public function reportCallerLinks(string $input): string;
+
+    /**
+     * Reports whether $context->deadline was populated and roughly how far in the future it is.
+     */
+    #[Operation]
+    public function reportDeadline(string $input): string;
+
+    /**
+     * Polls cooperative method cancellation and reports the observed state and reason.
+     */
+    #[Operation]
+    public function pollCancellation(string $input): string;
+
+    /**
+     * Serialises the request headers visible on the handler context into the result.
+     */
+    #[Operation]
+    public function reportHeaders(string $input): string;
+}
+
+final class EchoAsyncHandler implements OperationHandlerInterface
+{
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        return OperationStartResult::async(new OperationInfo('async-token-' . $param, OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {}
+}
+
+final class EchoCancelRecordingHandler implements OperationHandlerInterface
+{
+    public function __construct(
+        private readonly EchoServiceImpl $service,
+    ) {}
+
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        return OperationStartResult::async(new OperationInfo('cancel-token-' . $param, OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {
+        $this->service->canceledTokens[] = $details->operationToken;
+    }
+}
+
+final class EchoCancelThrowsHandler implements OperationHandlerInterface
+{
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        return OperationStartResult::async(new OperationInfo('cancel-throws-token-' . $param, OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {
+        throw new \RuntimeException("cancel routine blew up for {$details->operationToken}");
+    }
+}
+
+class EchoServiceImpl implements EchoServiceInterface
+{
+    /** @var string[] */
+    public array $canceledTokens = [];
+
+    public function echo(string $input): string
+    {
+        return "echo:{$input}";
+    }
+
+    public function asyncEcho(): EchoAsyncHandler
+    {
+        return new EchoAsyncHandler();
+    }
+
+    public function failOp(string $input): string
+    {
+        throw OperationException::failed("fail:{$input}");
+    }
+
+    public function cancelOp(): EchoCancelRecordingHandler
+    {
+        return new EchoCancelRecordingHandler($this);
+    }
+
+    public function cancelThrowsOp(): EchoCancelThrowsHandler
+    {
+        return new EchoCancelThrowsHandler();
+    }
+
+    public function echoWithLinks(string $input): string
+    {
+        Nexus::getCurrentOperationContext()->links->add(
+            new Link('http://test.local/resource/1', 'test.Resource'),
+            new Link('http://test.local/resource/2', 'test.Resource'),
+        );
+        return "linked:{$input}";
+    }
+
+    public function reportCallerLinks(string $input): string
+    {
+        $details = Nexus::getStartDetails();
+        $parts = [];
+        foreach ($details->links as $link) {
+            $parts[] = "{$link->uri}|{$link->type}";
+        }
+        return \sprintf('caller-links:count=%d;items=[%s]', \count($details->links), \implode(';', $parts));
+    }
+
+    public function reportDeadline(string $input): string
+    {
+        $context = Nexus::getCurrentOperationContext();
+        if ($context->deadline === null) {
+            return 'deadline:none';
+        }
+        $delta = $context->deadline->getTimestamp() - (new \DateTimeImmutable('now', new \DateTimeZone('UTC')))->getTimestamp();
+        return "deadline:set;delta_seconds={$delta}";
+    }
+
+    public function pollCancellation(string $input): string
+    {
+        $context = Nexus::getCurrentOperationContext();
+        return \sprintf(
+            'cancelled=%s;reason=%s',
+            $context->isMethodCancelled() ? '1' : '0',
+            $context->getMethodCancellationReason() ?? '',
+        );
+    }
+
+    public function reportHeaders(string $input): string
+    {
+        $parts = [];
+        foreach (Nexus::getCurrentOperationContext()->headers->all() as $name => $value) {
+            $parts[] = "{$name}={$value}";
+        }
+        return \implode(';', $parts);
+    }
+}
+
+// ── Integration tests ─────────────────────────────────────────────
+
+/**
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(NexusTaskHandler::class)]
+final class NexusOperationRoutesTestCase extends AbstractUnit
+{
+    use AwaitsNexusPromise;
+    use ExceptionAssertions;
+
+    private InvokeNexusOperation $invokeRoute;
+    private CancelNexusOperation $cancelRoute;
+    private DataConverter $dataConverter;
+    private EchoServiceImpl $serviceImpl;
+    private \Temporal\Worker\Environment\Environment $env;
+    private \Temporal\Internal\Nexus\NexusInvocationRegistry $invocationRegistry;
+
+    // ── Sync operation ───────────────────────────────────────────
+
+    public function testSyncOperation(): void
+    {
+        $reply = $this->invoke('echo', 'hello');
+
+        self::assertFalse($reply->getOptions()['async']);
+        self::assertNull($reply->getOptions()['token'] ?? null);
+        self::assertSame('echo:hello', $this->decodePayload($reply));
+    }
+
+    public function testSyncOperationWithDifferentInputs(): void
+    {
+        foreach (['simple', 'with spaces', 'unicode: привет'] as $input) {
+            $reply = $this->invoke('echo', $input);
+            self::assertFalse($reply->getOptions()['async']);
+            self::assertSame("echo:{$input}", $this->decodePayload($reply), "Failed for input: {$input}");
+        }
+    }
+
+    // ── Async operation ──────────────────────────────────────────
+
+    public function testAsyncOperationReturnsTokenInReplyOptions(): void
+    {
+        $reply = $this->invoke('asyncEcho', 'test');
+
+        self::assertTrue($reply->getOptions()['async']);
+        self::assertSame('async-token-test', $reply->getOptions()['token'] ?? null);
+        self::assertNull($reply->getPayloads(), 'async reply must not carry payloads');
+    }
+
+    // ── Operation error ──────────────────────────────────────────
+
+    public function testOperationFailurePropagatesOperationException(): void
+    {
+        $request = $this->makeInvokeRequest('EchoService', 'failOp', 'reason');
+        $deferred = new Deferred();
+
+        $this->expectException(OperationException::class);
+        $this->expectExceptionMessage('fail:reason');
+        $this->invokeRoute->handle($request, [], $deferred);
+        $this->awaitReply($deferred);
+    }
+
+    // ── Handler error ────────────────────────────────────────────
+
+    public function testHandlerErrorForUnknownService(): void
+    {
+        $request = $this->makeInvokeRequest('UnknownService', 'op', 'input');
+        $deferred = new Deferred();
+        $e = self::assertThrown(NexusHandlerException::class, function () use ($request, $deferred): void {
+            $this->invokeRoute->handle($request, [], $deferred);
+            $this->awaitReply($deferred);
+        });
+        self::assertSame(NexusErrorType::NotFound, $e->errorType);
+        self::assertSame('NOT_FOUND', $e->errorType->value);
+    }
+
+    public function testHandlerErrorForUnknownOperation(): void
+    {
+        $request = $this->makeInvokeRequest('EchoService', 'nonExistent', 'input');
+        $deferred = new Deferred();
+        $e = self::assertThrown(NexusHandlerException::class, function () use ($request, $deferred): void {
+            $this->invokeRoute->handle($request, [], $deferred);
+            $this->awaitReply($deferred);
+        });
+        self::assertSame(NexusErrorType::NotFound, $e->errorType);
+    }
+
+    // ── Cancel operation ─────────────────────────────────────────
+
+    public function testCancelOperation(): void
+    {
+        $request = $this->makeCancelRequest('EchoService', 'cancelOp', 'my-token');
+        $deferred = new Deferred();
+        $this->cancelRoute->handle($request, [], $deferred);
+        $this->awaitCancelResult($deferred);
+        self::assertContains('my-token', $this->serviceImpl->canceledTokens);
+    }
+
+    public function testCancelUnknownService(): void
+    {
+        $request = $this->makeCancelRequest('UnknownService', 'op', 'token');
+        $deferred = new Deferred();
+        $e = self::assertThrown(NexusHandlerException::class, function () use ($request, $deferred): void {
+            $this->cancelRoute->handle($request, [], $deferred);
+            $this->awaitCancelResult($deferred);
+        });
+        self::assertSame(NexusErrorType::NotFound, $e->errorType);
+    }
+
+    public function testCancelHandlerThrowingIsConvertedToHandlerError(): void
+    {
+        $request = $this->makeCancelRequest('EchoService', 'cancelThrowsOp', 'boom-token');
+        $deferred = new Deferred();
+
+        $this->cancelRoute->handle($request, [], $deferred);
+
+        $error = null;
+        $deferred->promise()->then(
+            null,
+            static function (\Throwable $e) use (&$error): void {
+                $error = $e;
+            },
+        );
+
+        self::assertInstanceOf(
+            NexusHandlerException::class,
+            $error,
+            'A throwing cancel routine must surface as a typed HandlerException rejection, never crash the worker.',
+        );
+        self::assertSame(NexusErrorType::Internal, $error->errorType);
+        self::assertInstanceOf(\RuntimeException::class, $error->getPrevious());
+        self::assertStringContainsString('boom-token', $error->getPrevious()->getMessage());
+    }
+
+    // ── Headers ──────────────────────────────────────────────────
+
+    public function testRequestHeadersSurfaceOnHandlerContext(): void
+    {
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'reportHeaders',
+            'requestId' => 'req-1',
+            'headers' => ['Authorization' => 'Bearer token123'],
+        ], EncodedValues::fromValues(['test'], $this->dataConverter));
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+        $reply = $this->awaitReply($deferred);
+
+        // Header keys are normalized to lowercase on the handler side.
+        self::assertSame('authorization=Bearer token123', $this->decodePayload($reply));
+    }
+
+    // ── Method-cancel registry lifecycle ─────────────────────────
+
+    public function testInvocationUnregisteredAfterSuccessfulStart(): void
+    {
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'echo',
+            'requestId' => 'reg-1',
+            'invocationId' => 7,
+        ], EncodedValues::fromValues(['x'], $this->dataConverter));
+
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+        $reply = $this->awaitReply($deferred);
+
+        self::assertSame('echo:x', $this->decodePayload($reply));
+        self::assertNull($this->invocationRegistry->get(7), 'entry must be unregistered after success');
+    }
+
+    public function testInvocationUnregisteredAfterFailedStart(): void
+    {
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'failOp',
+            'requestId' => 'reg-2',
+            'invocationId' => 7,
+        ], EncodedValues::fromValues(['x'], $this->dataConverter));
+
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+
+        $error = null;
+        $deferred->promise()->then(null, static function (\Throwable $e) use (&$error): void {
+            $error = $e;
+        });
+
+        self::assertInstanceOf(OperationException::class, $error);
+        self::assertNull($this->invocationRegistry->get(7), 'entry must be unregistered after failure');
+    }
+
+    // ── Caller-side Nexus-Link propagation ───────────────────────
+
+    public function testCallerLinksPropagateFromOptionsToHandler(): void
+    {
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'reportCallerLinks',
+            'requestId' => 'links-1',
+            'links' => [
+                ['url' => 'https://caller.test/one', 'type' => 'example.one'],
+                ['url' => 'https://caller.test/two', 'type' => 'example.two'],
+            ],
+        ], EncodedValues::fromValues(['ignored'], $this->dataConverter));
+
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+        $reply = $this->awaitReply($deferred);
+        $result = $this->decodePayload($reply);
+
+        self::assertStringContainsString('count=2', $result);
+        self::assertStringContainsString('https://caller.test/one|example.one', $result);
+        self::assertStringContainsString('https://caller.test/two|example.two', $result);
+    }
+
+    public function testMalformedCallerLinkRejectsRequest(): void
+    {
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'reportCallerLinks',
+            'requestId' => 'links-2',
+            'links' => [
+                ['url' => 'https://ok.test/a', 'type' => 'ok'],
+                ['url' => 'https://missing-type.test/b'], // no type → reject
+            ],
+        ], EncodedValues::fromValues(['x'], $this->dataConverter));
+
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+
+        $error = null;
+        $deferred->promise()->then(null, static function (\Throwable $e) use (&$error): void {
+            $error = $e;
+        });
+        self::assertInstanceOf(\Temporal\Nexus\Exception\HandlerException::class, $error);
+        self::assertSame(
+            \Temporal\Nexus\Exception\ErrorType::BadRequest,
+            $error->errorType,
+        );
+        self::assertStringContainsString('missing or empty "type"', $error->getMessage());
+    }
+
+    public function testLinksPayloadWrongShapeRejectsRequest(): void
+    {
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'reportCallerLinks',
+            'requestId' => 'links-3',
+            'links' => 'not-a-list',
+        ], EncodedValues::fromValues(['x'], $this->dataConverter));
+
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+
+        $error = null;
+        $deferred->promise()->then(null, static function (\Throwable $e) use (&$error): void {
+            $error = $e;
+        });
+        self::assertInstanceOf(\Temporal\Nexus\Exception\HandlerException::class, $error);
+        self::assertSame(
+            \Temporal\Nexus\Exception\ErrorType::BadRequest,
+            $error->errorType,
+        );
+    }
+
+    public function testAbsentLinksMeansEmptyList(): void
+    {
+        $reply = $this->invoke('reportCallerLinks', 'x');
+        $result = $this->decodePayload($reply);
+
+        self::assertStringContainsString('count=0', $result);
+    }
+
+    // ── Handler-side links → reply.options.links ────────────
+
+    public function testHandlerAddedLinksAreSerializedIntoReplyOptions(): void
+    {
+        $reply = $this->invoke('echoWithLinks', 'hi');
+
+        self::assertFalse($reply->getOptions()['async']);
+
+        $links = $reply->getOptions()['links'] ?? [];
+        self::assertCount(2, $links);
+        self::assertSame('http://test.local/resource/1', $links[0]['url']);
+        self::assertSame('test.Resource', $links[0]['type']);
+        self::assertSame('http://test.local/resource/2', $links[1]['url']);
+    }
+
+    public function testNoLinksMeansEmptyLinksList(): void
+    {
+        $reply = $this->invoke('echo', 'hello');
+
+        self::assertSame([], $reply->getOptions()['links'] ?? [], 'links field must be empty when handler adds none');
+    }
+
+    // ── Deadline from Nexus timeout headers ──────────────────────
+
+    public function testOperationTimeoutHeaderDoesNotSetDeadline(): void
+    {
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'reportDeadline',
+            'requestId' => 'dl-1',
+            'headers' => ['Operation-Timeout' => '30s'],
+        ], EncodedValues::fromValues(['x'], $this->dataConverter));
+
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+        $reply = $this->awaitReply($deferred);
+        $result = $this->decodePayload($reply);
+
+        self::assertStringContainsString('deadline:none', $result);
+    }
+
+    public function testRequestTimeoutSetsDeadline(): void
+    {
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'reportDeadline',
+            'requestId' => 'dl-2',
+            'headers' => ['Request-Timeout' => '10s'],
+        ], EncodedValues::fromValues(['x'], $this->dataConverter));
+
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+        $reply = $this->awaitReply($deferred);
+        $result = $this->decodePayload($reply);
+
+        self::assertStringContainsString('deadline:set', $result);
+        self::assertMatchesRegularExpression('/delta_seconds=([5-9]|1[0-1])/', $result);
+    }
+
+    public function testRequestTimeoutUsedIgnoringOperationTimeout(): void
+    {
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'reportDeadline',
+            'requestId' => 'dl-3',
+            'headers' => [
+                'Request-Timeout'   => '5s',
+                'Operation-Timeout' => '120s',
+            ],
+        ], EncodedValues::fromValues(['x'], $this->dataConverter));
+
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+        $reply = $this->awaitReply($deferred);
+        $result = $this->decodePayload($reply);
+
+        self::assertStringContainsString('deadline:set', $result);
+        self::assertMatchesRegularExpression('/delta_seconds=[1-5]/', $result);
+    }
+
+    public function testMalformedTimeoutHeaderIsSilentlyIgnored(): void
+    {
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'reportDeadline',
+            'requestId' => 'dl-4',
+            'headers' => ['Request-Timeout' => 'garbage'],
+        ], EncodedValues::fromValues(['x'], $this->dataConverter));
+
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+        $reply = $this->awaitReply($deferred);
+        $result = $this->decodePayload($reply);
+
+        self::assertStringContainsString('deadline:none', $result);
+    }
+
+    public function testCaseInsensitiveTimeoutHeaderLookup(): void
+    {
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'reportDeadline',
+            'requestId' => 'dl-5',
+            'headers' => ['request-timeout' => '15s'],
+        ], EncodedValues::fromValues(['x'], $this->dataConverter));
+
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+        $reply = $this->awaitReply($deferred);
+        $result = $this->decodePayload($reply);
+
+        self::assertStringContainsString('deadline:set', $result);
+    }
+
+    // ── Cooperative deadline-trip via env->now() ─────────────────
+
+    public function testHandlerObservesDeadlineTripViaEnvNow(): void
+    {
+        // Advance env time past the handler deadline; a handler polling
+        // isMethodCancelled() must observe the cooperative deadline trip,
+        // and the reason must surface through env->now()-based checking.
+        $this->env->update(new TickInfo(new \DateTimeImmutable('+1 hour')));
+
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'pollCancellation',
+            'requestId' => 'cancel-trip-1',
+            'headers' => ['Request-Timeout' => '1s'],
+        ], EncodedValues::fromValues(['x'], $this->dataConverter));
+
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+        $result = $this->decodePayload($this->awaitReply($deferred));
+
+        self::assertStringStartsWith('cancelled=1', $result);
+        self::assertStringContainsString('deadline exceeded', $result);
+    }
+
+    public function testHandlerSeesNoCancellationBeforeDeadline(): void
+    {
+        $request = $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => 'EchoService',
+            'operation' => 'pollCancellation',
+            'requestId' => 'cancel-trip-2',
+            'headers' => ['Request-Timeout' => '3600s'],
+        ], EncodedValues::fromValues(['x'], $this->dataConverter));
+
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+        $result = $this->decodePayload($this->awaitReply($deferred));
+
+        self::assertStringStartsWith('cancelled=0', $result);
+    }
+
+    // ── Route names ──────────────────────────────────────────────
+
+    public function testInvokeNexusOperationRouteName(): void
+    {
+        self::assertSame('InvokeNexusOperation', $this->invokeRoute->getName());
+    }
+
+    public function testCancelNexusOperationRouteName(): void
+    {
+        self::assertSame('CancelNexusOperation', $this->cancelRoute->getName());
+    }
+
+    protected function setUp(): void
+    {
+        $this->dataConverter = DataConverter::createDefault();
+
+        $this->serviceImpl = new EchoServiceImpl();
+
+        $reader = new \Temporal\Internal\Declaration\Reader\NexusServiceReader(new \Spiral\Attributes\AttributeReader());
+        $prototype = $reader->fromClass($this->serviceImpl::class)->withInstance($this->serviceImpl);
+
+        $repository = new \Temporal\Internal\Declaration\Prototype\NexusServiceCollection();
+        $repository->add($prototype, false);
+
+        $this->env = new \Temporal\Worker\Environment\Environment();
+
+        $taskHandler = new \Temporal\Internal\Nexus\NexusTaskHandler(
+            $repository,
+            $this->dataConverter,
+            $this->env,
+        );
+
+        $marshaller = new \Temporal\Internal\Marshaller\Marshaller(
+            new \Temporal\Internal\Marshaller\Mapper\AttributeMapperFactory(new \Spiral\Attributes\AttributeReader()),
+        );
+        $this->invocationRegistry = new \Temporal\Internal\Nexus\NexusInvocationRegistry();
+        $this->invokeRoute = new InvokeNexusOperation($taskHandler, $this->invocationRegistry, $this->dataConverter, $marshaller, $this->env);
+        $this->cancelRoute = new CancelNexusOperation($taskHandler, $marshaller);
+    }
+
+    // ── Helpers ──────────────────────────────────────────────────
+
+    private function invoke(string $operation, string $input): CommandResponse
+    {
+        $request = $this->makeInvokeRequest('EchoService', $operation, $input);
+        $deferred = new Deferred();
+        $this->invokeRoute->handle($request, [], $deferred);
+        return $this->awaitReply($deferred);
+    }
+
+    private function decodePayload(CommandResponse $reply): string
+    {
+        $payloads = $reply->getPayloads();
+        self::assertNotNull($payloads, 'sync reply must carry a payload');
+        return $payloads->getValue(0, 'string');
+    }
+
+    private function makeInvokeRequest(string $service, string $operation, string $input): ServerRequest
+    {
+        return $this->makeServerRequest('InvokeNexusOperation', [
+            'service' => $service,
+            'operation' => $operation,
+            'requestId' => 'test-' . \bin2hex(\random_bytes(4)),
+        ], EncodedValues::fromValues([$input], $this->dataConverter));
+    }
+
+    private function makeCancelRequest(string $service, string $operation, string $token): ServerRequest
+    {
+        return $this->makeServerRequest('CancelNexusOperation', [
+            'service' => $service,
+            'operation' => $operation,
+            'operationToken' => $token,
+        ]);
+    }
+
+    private function makeServerRequest(string $name, array $options, ?ValuesInterface $payloads = null): ServerRequest
+    {
+        return new ServerRequest(
+            name: $name,
+            info: new TickInfo(new \DateTimeImmutable()),
+            options: $options,
+            payloads: $payloads,
+        );
+    }
+}
diff --git a/tests/Unit/Nexus/NexusServiceCollectionTestCase.php b/tests/Unit/Nexus/NexusServiceCollectionTestCase.php
new file mode 100644
index 000000000..715cdef6f
--- /dev/null
+++ b/tests/Unit/Nexus/NexusServiceCollectionTestCase.php
@@ -0,0 +1,138 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Nexus;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+use Spiral\Attributes\AttributeReader;
+use Temporal\Internal\Declaration\Prototype\NexusServiceCollection;
+use Temporal\Internal\Declaration\Prototype\NexusServicePrototype;
+use Temporal\Internal\Declaration\Reader\NexusServiceReader;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Tests\Unit\AbstractUnit;
+
+// Two interfaces declaring the same service name "Dup" — used to exercise the dedup path.
+#[Service(name: 'Dup')]
+interface DupAlphaInterface
+{
+    #[Operation]
+    public function op(string $in): string;
+}
+
+#[Service(name: 'Dup')]
+interface DupBetaInterface
+{
+    #[Operation]
+    public function op(string $in): string;
+}
+
+class DupAlphaImpl implements DupAlphaInterface
+{
+    public function op(string $in): string
+    {
+        return "alpha:{$in}";
+    }
+}
+
+class DupBetaImpl implements DupBetaInterface
+{
+    public function op(string $in): string
+    {
+        return "beta:{$in}";
+    }
+}
+
+#[Service(name: 'CollectionSolo')]
+interface CollectionSoloInterface
+{
+    #[Operation]
+    public function op(string $in): string;
+}
+
+class CollectionSoloImpl implements CollectionSoloInterface
+{
+    public function op(string $in): string
+    {
+        return "solo:{$in}";
+    }
+}
+
+/**
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(NexusServiceCollection::class)]
+#[UsesClass(NexusServicePrototype::class)]
+#[UsesClass(NexusServiceReader::class)]
+final class NexusServiceCollectionTestCase extends AbstractUnit
+{
+    public function testEmptyRepository(): void
+    {
+        $repo = new NexusServiceCollection();
+
+        self::assertCount(0, $repo);
+    }
+
+    public function testAddAndRetrieve(): void
+    {
+        $repo = new NexusServiceCollection();
+        $prototype = self::buildPrototype(new CollectionSoloImpl());
+
+        $repo->add($prototype);
+
+        self::assertCount(1, $repo);
+        $items = \iterator_to_array($repo);
+        self::assertSame($prototype, \reset($items));
+    }
+
+    public function testRejectsDuplicateServiceName(): void
+    {
+        $repo = new NexusServiceCollection();
+        $repo->add(self::buildPrototype(new DupAlphaImpl()));
+
+        $this->expectException(\OutOfBoundsException::class);
+        $this->expectExceptionMessage('Entry with same identifier "Dup" already has been registered');
+        $repo->add(self::buildPrototype(new DupBetaImpl()));
+    }
+
+    public function testGetIteratorReturnsItemsInInsertionOrder(): void
+    {
+        $repo = new NexusServiceCollection();
+
+        $alpha = self::buildPrototype(new DupAlphaImpl());
+        $solo = self::buildPrototype(new CollectionSoloImpl());
+
+        $repo->add($alpha);
+        $repo->add($solo);
+
+        self::assertCount(2, $repo);
+        $items = \array_values(\iterator_to_array($repo));
+        self::assertSame($alpha, $items[0]);
+        self::assertSame($solo, $items[1]);
+    }
+
+    public function testSelfRegistrationRejected(): void
+    {
+        // Registering reflection-built prototypes from the same class twice fails:
+        // both produce the same service name, and the collection guards by ID.
+        $repo = new NexusServiceCollection();
+        $instance = new DupAlphaImpl();
+        $repo->add(self::buildPrototype($instance));
+
+        $this->expectException(\OutOfBoundsException::class);
+        $repo->add(self::buildPrototype($instance));
+    }
+
+    /**
+     * Reproduces the Worker registration flow: read prototype, bind the
+     * service instance via factory closure.
+     */
+    private static function buildPrototype(object $instance): NexusServicePrototype
+    {
+        $reader = new NexusServiceReader(new AttributeReader());
+        return $reader->fromClass($instance::class)->withInstance($instance);
+    }
+}
diff --git a/tests/Unit/Nexus/NexusTaskHandlerTestCase.php b/tests/Unit/Nexus/NexusTaskHandlerTestCase.php
new file mode 100644
index 000000000..9438e67d1
--- /dev/null
+++ b/tests/Unit/Nexus/NexusTaskHandlerTestCase.php
@@ -0,0 +1,649 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Nexus;
+
+use Google\Rpc\Code;
+use Temporal\DataConverter\EncodedValues;
+use Temporal\Exception\Client\ServiceClientException;
+use Temporal\Exception\Failure\ApplicationFailure;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Exception\OperationException;
+use Temporal\Nexus\Exception\RetryBehavior;
+use Spiral\Attributes\AttributeReader;
+use Temporal\Internal\Declaration\Prototype\NexusServiceCollection;
+use Temporal\Internal\Declaration\Reader\NexusServiceReader;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\Link;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+use Temporal\Api\Nexus\V1\CancelOperationRequest;
+use Temporal\Api\Nexus\V1\Request;
+use Temporal\Api\Nexus\V1\StartOperationRequest;
+use Temporal\DataConverter\DataConverter;
+use Temporal\DataConverter\DataConverterInterface;
+use Temporal\Nexus\NexusOperationContext;
+use PHPUnit\Framework\Attributes\CoversClass;
+use Temporal\Internal\Nexus\NexusTaskHandler;
+use Temporal\Tests\Unit\AbstractUnit;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Tests\Nexus\Support\ExceptionAssertions;
+use Temporal\Worker\Environment\EnvironmentInterface;
+
+#[Service]
+interface TestGreetingService
+{
+    #[Operation]
+    public function sayHello(string $name): string;
+
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function asyncOp(): GreetingAsyncOpHandler;
+
+    #[Operation]
+    public function failingOp(string $input): string;
+
+    #[Operation]
+    public function richCauseFailingOp(string $input): string;
+
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function cancelableOp(): GreetingCancelableOpHandler;
+
+    #[Operation]
+    public function shout(string $input): string;
+
+    #[Operation]
+    public function grpcFailingOp(string $input): string;
+
+    #[Operation]
+    public function appFailureOp(string $input): string;
+
+    #[Operation]
+    public function genericFailingOp(string $input): string;
+
+    #[Operation]
+    public function deadlineEchoOp(string $input): string;
+}
+
+class TestGreetingServiceImpl implements TestGreetingService
+{
+    /** @var array<string, string> Headers seen by the most recent start dispatch. */
+    public static array $capturedStartHeaders = [];
+
+    /** @var array<string, string> Headers seen by the most recent cancel dispatch. */
+    public static array $capturedCancelHeaders = [];
+
+    /** @var \DateTimeImmutable|null Deadline seen by the most recent cancel dispatch. */
+    public static ?\DateTimeImmutable $capturedCancelDeadline = null;
+
+    /** @var string|null Namespace seen by the most recent start dispatch. */
+    public static ?string $capturedStartNamespace = null;
+
+    /** @var string|null Task queue seen by the most recent start dispatch. */
+    public static ?string $capturedStartTaskQueue = null;
+
+    public function sayHello(string $name): string
+    {
+        self::$capturedStartHeaders = Nexus::getCurrentOperationContext()->headers->all();
+        if (Nexus::getCurrentContext()->operation !== null) {
+            self::$capturedStartNamespace = Nexus::getOperationContext()->namespace;
+            self::$capturedStartTaskQueue = Nexus::getOperationContext()->taskQueue;
+        }
+        return "Hello, {$name}!";
+    }
+
+    public function asyncOp(): GreetingAsyncOpHandler
+    {
+        return new GreetingAsyncOpHandler();
+    }
+
+    public function failingOp(string $input): string
+    {
+        throw OperationException::failed('Something went wrong');
+    }
+
+    public function richCauseFailingOp(string $input): string
+    {
+        throw OperationException::failed(
+            'outer-failure',
+            new ApplicationFailure(
+                'inner-detail',
+                'CustomBusinessType',
+                false,
+                EncodedValues::fromValues(['marker']),
+            ),
+        );
+    }
+
+    public function cancelableOp(): GreetingCancelableOpHandler
+    {
+        return new GreetingCancelableOpHandler();
+    }
+
+    public function shout(string $input): string
+    {
+        return \strtoupper($input) . '!';
+    }
+
+    public function grpcFailingOp(string $input): string
+    {
+        $status = new \stdClass();
+        $status->code = Code::NOT_FOUND;
+        $status->details = 'workflow vanished';
+        $status->metadata = [];
+        throw new ServiceClientException($status);
+    }
+
+    public function appFailureOp(string $input): string
+    {
+        throw new ApplicationFailure(
+            'business invariant violated',
+            'BusinessError',
+            true, // nonRetryable
+            EncodedValues::empty(),
+        );
+    }
+
+    public function genericFailingOp(string $input): string
+    {
+        throw new \RuntimeException('something blew up');
+    }
+
+    public function deadlineEchoOp(string $input): string
+    {
+        $deadline = Nexus::getCurrentOperationContext()->deadline;
+        return $deadline === null ? 'none' : $deadline->format(\DATE_ATOM);
+    }
+}
+
+final class GreetingAsyncOpHandler implements OperationHandlerInterface
+{
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        Nexus::getCurrentOperationContext()->links->add(
+            new Link('http://example.com/workflow/123', 'temporal.workflow'),
+        );
+        return OperationStartResult::async(new OperationInfo('op-token-123', OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {}
+}
+
+final class GreetingCancelableOpHandler implements OperationHandlerInterface
+{
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        return OperationStartResult::async(new OperationInfo('cancel-token-456', OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {
+        TestGreetingServiceImpl::$capturedCancelHeaders = Nexus::getCurrentOperationContext()->headers->all();
+        TestGreetingServiceImpl::$capturedCancelDeadline = Nexus::getCurrentOperationContext()->deadline;
+        if ($details->operationToken === 'unknown') {
+            throw HandlerException::create(ErrorType::NotFound, 'Not found');
+        }
+    }
+}
+
+/**
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(NexusTaskHandler::class)]
+final class NexusTaskHandlerTestCase extends AbstractUnit
+{
+    use ExceptionAssertions;
+
+    private NexusTaskHandler $handler;
+    private DataConverterInterface $dataConverter;
+    private EnvironmentInterface $env;
+
+    public function testStartSyncOperation(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'sayHello', 'World');
+
+        $response = $this->handler->handleStartOperation($request, new NexusOperationContext());
+
+        self::assertTrue($response->hasStartOperation());
+        $startResp = $response->getStartOperation();
+        self::assertTrue($startResp->hasSyncSuccess());
+
+        $payload = $startResp->getSyncSuccess()->getPayload();
+        self::assertNotNull($payload);
+
+        $result = $this->dataConverter->fromPayload($payload, 'string');
+        self::assertSame('Hello, World!', $result);
+    }
+
+    public function testStartAsyncOperation(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'asyncOp', 'input');
+
+        $response = $this->handler->handleStartOperation($request, new NexusOperationContext());
+
+        self::assertTrue($response->hasStartOperation());
+        $startResp = $response->getStartOperation();
+        self::assertTrue($startResp->hasAsyncSuccess());
+
+        $asyncResp = $startResp->getAsyncSuccess();
+        self::assertSame('op-token-123', $asyncResp->getOperationToken());
+
+        $links = $asyncResp->getLinks();
+        self::assertCount(1, $links);
+        self::assertSame('http://example.com/workflow/123', $links[0]->getUrl());
+        self::assertSame('temporal.workflow', $links[0]->getType());
+    }
+
+    public function testStartOperationWithOperationException(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'failingOp', 'input');
+
+        $this->expectException(OperationException::class);
+        $this->expectExceptionMessage('Something went wrong');
+        $this->handler->handleStartOperation($request, new NexusOperationContext());
+    }
+
+    public function testStartOperationPropagatesOperationExceptionCauseChain(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'richCauseFailingOp', 'input');
+
+        $e = self::assertThrown(
+            OperationException::class,
+            fn() => $this->handler->handleStartOperation($request, new NexusOperationContext()),
+        );
+        self::assertSame('outer-failure', $e->getMessage());
+
+        $cause = $e->getPrevious();
+        self::assertInstanceOf(ApplicationFailure::class, $cause);
+        self::assertSame('CustomBusinessType', $cause->getType());
+        self::assertSame('inner-detail', $cause->getOriginalMessage());
+        self::assertSame('marker', $cause->getDetails()->getValue(0, 'string'));
+    }
+
+    public function testStartOperationWithUnknownService(): void
+    {
+        $request = $this->buildStartRequest('NonExistentService', 'op', 'input');
+
+        $this->expectException(HandlerException::class);
+        $this->handler->handleStartOperation($request, new NexusOperationContext());
+    }
+
+    public function testCancelOperation(): void
+    {
+        $request = $this->buildCancelRequest('TestGreetingService', 'cancelableOp', 'cancel-token-456');
+
+        $response = $this->handler->handleCancelOperation($request, new NexusOperationContext());
+
+        self::assertTrue($response->hasCancelOperation());
+    }
+
+    public function testCancelOperationWithHandlerException(): void
+    {
+        $request = $this->buildCancelRequest('TestGreetingService', 'cancelableOp', 'unknown');
+
+        $this->expectException(HandlerException::class);
+        $this->handler->handleCancelOperation($request, new NexusOperationContext());
+    }
+
+    public function testCancelOperationWithUnknownService(): void
+    {
+        $request = $this->buildCancelRequest('NonExistentService', 'op', 'token');
+
+        $this->expectException(HandlerException::class);
+        $this->handler->handleCancelOperation($request, new NexusOperationContext());
+    }
+
+    public function testCancelOperationWithEmptyTokenIsBadRequest(): void
+    {
+        $request = $this->buildCancelRequest('TestGreetingService', 'cancelableOp', '');
+
+        $e = self::assertThrown(
+            HandlerException::class,
+            fn() => $this->handler->handleCancelOperation($request, new NexusOperationContext()),
+        );
+        self::assertSame(ErrorType::BadRequest, $e->errorType);
+        self::assertSame(RetryBehavior::NonRetryable, $e->retryBehavior);
+    }
+
+    public function testCancelOperationPropagatesHeadersToContext(): void
+    {
+        $request = $this->buildCancelRequest('TestGreetingService', 'cancelableOp', 'cancel-token-456', [
+            'X-Nexus-Trace-Id' => 'trace-1',
+            'Authorization' => 'Bearer xyz',
+        ]);
+
+        $this->handler->handleCancelOperation($request, new NexusOperationContext());
+
+        self::assertSame('trace-1', TestGreetingServiceImpl::$capturedCancelHeaders['x-nexus-trace-id'] ?? null);
+        self::assertSame('Bearer xyz', TestGreetingServiceImpl::$capturedCancelHeaders['authorization'] ?? null);
+    }
+
+    public function testStartOperationPropagatesHeadersToContext(): void
+    {
+        $startReq = new StartOperationRequest();
+        $startReq->setService('TestGreetingService');
+        $startReq->setOperation('sayHello');
+        $startReq->setRequestId('req-h1');
+        $startReq->setPayload($this->dataConverter->toPayload('World'));
+
+        $request = new Request();
+        $request->setStartOperation($startReq);
+        $request->setHeader(['X-Nexus-Trace-Id' => 'trace-2']);
+
+        $this->handler->handleStartOperation($request, new NexusOperationContext());
+
+        self::assertSame('trace-2', TestGreetingServiceImpl::$capturedStartHeaders['x-nexus-trace-id'] ?? null);
+    }
+
+    public function testStartOperationUsesWireNamespace(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'sayHello', 'World');
+
+        $operationContext = new NexusOperationContext();
+        $operationContext->namespace = 'wire-ns';
+        $operationContext->taskQueue = 'wire-tq';
+        $this->handler->handleStartOperation($request, $operationContext);
+
+        self::assertSame('wire-ns', TestGreetingServiceImpl::$capturedStartNamespace);
+    }
+
+    public function testStartOperationHasNoNamespaceWhenWireAbsent(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'sayHello', 'World');
+
+        $this->handler->handleStartOperation($request, new NexusOperationContext());
+
+        self::assertNull(TestGreetingServiceImpl::$capturedStartNamespace);
+    }
+
+    public function testStartOperationUsesWireTaskQueue(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'sayHello', 'World');
+
+        $operationContext = new NexusOperationContext();
+        $operationContext->namespace = 'wire-ns';
+        $operationContext->taskQueue = 'wire-tq';
+        $this->handler->handleStartOperation($request, $operationContext);
+
+        self::assertSame('wire-tq', TestGreetingServiceImpl::$capturedStartTaskQueue);
+    }
+
+    public function testStartOperationHasNoTaskQueueWhenWireAbsent(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'sayHello', 'World');
+
+        $this->handler->handleStartOperation($request, new NexusOperationContext());
+
+        self::assertNull(TestGreetingServiceImpl::$capturedStartTaskQueue);
+    }
+
+    public function testHandlerErrorContainsErrorType(): void
+    {
+        $request = $this->buildStartRequest('NonExistentService', 'op', 'input');
+
+        $e = self::assertThrown(
+            HandlerException::class,
+            fn() => $this->handler->handleStartOperation($request, new NexusOperationContext()),
+        );
+        self::assertSame(ErrorType::NotFound, $e->errorType);
+        self::assertNotEmpty($e->getMessage());
+    }
+
+    public function testGrpcServiceClientExceptionMapsToHandlerError(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'grpcFailingOp', 'input');
+
+        $e = self::assertThrown(
+            HandlerException::class,
+            fn() => $this->handler->handleStartOperation($request, new NexusOperationContext()),
+        );
+        self::assertSame(ErrorType::NotFound, $e->errorType);
+        self::assertInstanceOf(ServiceClientException::class, $e->getPrevious());
+    }
+
+    public function testNonRetryableApplicationFailureMapsToInternalNonRetryable(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'appFailureOp', 'input');
+
+        $e = self::assertThrown(
+            HandlerException::class,
+            fn() => $this->handler->handleStartOperation($request, new NexusOperationContext()),
+        );
+        self::assertSame(ErrorType::Internal, $e->errorType);
+        self::assertSame(RetryBehavior::NonRetryable, $e->retryBehavior);
+    }
+
+    public function testGenericThrowableNeverEscapesAsRawException(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'genericFailingOp', 'input');
+
+        $e = self::assertThrown(
+            HandlerException::class,
+            fn() => $this->handler->handleStartOperation($request, new NexusOperationContext()),
+        );
+        self::assertSame(ErrorType::Internal, $e->errorType);
+        self::assertInstanceOf(\RuntimeException::class, $e->getPrevious());
+    }
+
+    public function testStartOperationWithMalformedTimeoutHeaderIsIgnored(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'deadlineEchoOp', 'input');
+        $request->setHeader(['Request-Timeout' => 'not-a-duration']);
+
+        $response = $this->handler->handleStartOperation($request, new NexusOperationContext());
+
+        self::assertTrue($response->getStartOperation()->hasSyncSuccess());
+        self::assertSame('none', $this->decodeSyncStringResult($response->getStartOperation()));
+    }
+
+    public function testStartOperationWithValidTimeoutHeaderSetsDeadline(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'deadlineEchoOp', 'input');
+        $request->setHeader(['Request-Timeout' => '30s']);
+
+        $response = $this->handler->handleStartOperation($request, new NexusOperationContext());
+
+        self::assertTrue($response->getStartOperation()->hasSyncSuccess());
+        self::assertNotSame('none', $this->decodeSyncStringResult($response->getStartOperation()));
+    }
+
+    public function testStartOperationWithAbsentTimeoutHeaderHasNoDeadline(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'deadlineEchoOp', 'input');
+
+        $response = $this->handler->handleStartOperation($request, new NexusOperationContext());
+
+        self::assertTrue($response->getStartOperation()->hasSyncSuccess());
+        self::assertSame('none', $this->decodeSyncStringResult($response->getStartOperation()));
+    }
+
+    public function testDeadlineFromHeadersIgnoresOperationTimeout(): void
+    {
+        self::assertNull(NexusTaskHandler::deadlineFromHeaders(['Operation-Timeout' => '30s']));
+    }
+
+    public function testDeadlineFromHeadersUsesRequestTimeoutNotOperationTimeout(): void
+    {
+        $before = new \DateTimeImmutable();
+
+        $deadline = NexusTaskHandler::deadlineFromHeaders([
+            'Request-Timeout' => '5s',
+            'Operation-Timeout' => '120s',
+        ]);
+
+        self::assertNotNull($deadline);
+        $delta = $deadline->getTimestamp() - $before->getTimestamp();
+        self::assertLessThanOrEqual(
+            60,
+            $delta,
+            'deadline must derive from Request-Timeout (5s), not Operation-Timeout (120s)',
+        );
+    }
+
+    public function testCancelOperationSetsDeadlineFromRequestTimeout(): void
+    {
+        $request = $this->buildCancelRequest('TestGreetingService', 'cancelableOp', 'cancel-token-456', [
+            'Request-Timeout' => '30s',
+        ]);
+
+        $this->handler->handleCancelOperation($request, new NexusOperationContext());
+
+        self::assertNotNull(TestGreetingServiceImpl::$capturedCancelDeadline);
+    }
+
+    public function testCancelOperationHasNoDeadlineWithoutRequestTimeout(): void
+    {
+        $request = $this->buildCancelRequest('TestGreetingService', 'cancelableOp', 'cancel-token-456');
+
+        $this->handler->handleCancelOperation($request, new NexusOperationContext());
+
+        self::assertNull(TestGreetingServiceImpl::$capturedCancelDeadline);
+    }
+
+    public function testStartOperationWithCallbackUrl(): void
+    {
+        $startReq = new StartOperationRequest();
+        $startReq->setService('TestGreetingService');
+        $startReq->setOperation('sayHello');
+        $startReq->setRequestId('req-123');
+        $startReq->setCallback('http://callback.example.com/complete');
+        $startReq->setCallbackHeader(['Authorization' => 'Bearer token']);
+        $startReq->setPayload($this->dataConverter->toPayload('World'));
+
+        $request = new Request();
+        $request->setStartOperation($startReq);
+        $request->setHeader(['content-type' => 'application/json']);
+
+        $response = $this->handler->handleStartOperation($request, new NexusOperationContext());
+
+        self::assertTrue($response->hasStartOperation());
+        self::assertTrue($response->getStartOperation()->hasSyncSuccess());
+    }
+
+    public function testShoutSyncOperation(): void
+    {
+        $request = $this->buildStartRequest('TestGreetingService', 'shout', 'hello');
+
+        $response = $this->handler->handleStartOperation($request, new NexusOperationContext());
+
+        self::assertTrue($response->hasStartOperation());
+        $startResp = $response->getStartOperation();
+        self::assertTrue($startResp->hasSyncSuccess());
+
+        self::assertSame('HELLO!', $this->decodeSyncStringResult($startResp));
+    }
+
+    public function testStartOperationWithLinks(): void
+    {
+        $link = new \Temporal\Api\Nexus\V1\Link();
+        $link->setUrl('http://caller.example.com/resource/1');
+        $link->setType('caller.resource');
+
+        $startReq = new StartOperationRequest();
+        $startReq->setService('TestGreetingService');
+        $startReq->setOperation('sayHello');
+        $startReq->setRequestId('req-456');
+        $startReq->setLinks([$link]);
+        $startReq->setPayload($this->dataConverter->toPayload('World'));
+
+        $request = new Request();
+        $request->setStartOperation($startReq);
+
+        $response = $this->handler->handleStartOperation($request, new NexusOperationContext());
+        self::assertTrue($response->getStartOperation()->hasSyncSuccess());
+    }
+
+    protected function setUp(): void
+    {
+        $this->dataConverter = DataConverter::createDefault();
+        $this->env = new Environment();
+
+        TestGreetingServiceImpl::$capturedStartHeaders = [];
+        TestGreetingServiceImpl::$capturedCancelHeaders = [];
+        TestGreetingServiceImpl::$capturedStartNamespace = null;
+        TestGreetingServiceImpl::$capturedStartTaskQueue = null;
+
+        $this->handler = new NexusTaskHandler(
+            self::buildRepository(new TestGreetingServiceImpl()),
+            $this->dataConverter,
+            $this->env,
+        );
+    }
+
+    /**
+     * Build a {@see NexusServiceCollection} populated with the given service instances,
+     * using the same Reader wiring as the Worker.
+     */
+    private static function buildRepository(object ...$instances): NexusServiceCollection
+    {
+        $reader = new NexusServiceReader(new AttributeReader());
+
+        $collection = new NexusServiceCollection();
+        foreach ($instances as $instance) {
+            $prototype = $reader->fromClass(\get_class($instance))->withInstance($instance);
+            $collection->add($prototype, false);
+        }
+        return $collection;
+    }
+
+    private function buildStartRequest(string $service, string $operation, string $input): Request
+    {
+        $startReq = new StartOperationRequest();
+        $startReq->setService($service);
+        $startReq->setOperation($operation);
+        $startReq->setRequestId('test-request-id');
+        $startReq->setPayload($this->dataConverter->toPayload($input));
+
+        $request = new Request();
+        $request->setStartOperation($startReq);
+        return $request;
+    }
+
+    private function decodeSyncStringResult(
+        \Temporal\Api\Nexus\V1\StartOperationResponse $startResp,
+    ): string {
+        $payload = $startResp->getSyncSuccess()->getPayload();
+        self::assertNotNull($payload);
+
+        return (string) $this->dataConverter->fromPayload($payload, 'string');
+    }
+
+    /**
+     * @param array<string, string> $headers
+     */
+    private function buildCancelRequest(string $service, string $operation, string $token, array $headers = []): Request
+    {
+        $cancelReq = new CancelOperationRequest();
+        $cancelReq->setService($service);
+        $cancelReq->setOperation($operation);
+        $cancelReq->setOperationToken($token);
+
+        $request = new Request();
+        $request->setCancelOperation($cancelReq);
+        if ($headers !== []) {
+            $request->setHeader($headers);
+        }
+        return $request;
+    }
+}
diff --git a/tests/Unit/Nexus/WorkflowRunOperationTestCase.php b/tests/Unit/Nexus/WorkflowRunOperationTestCase.php
new file mode 100644
index 000000000..c4ae85e97
--- /dev/null
+++ b/tests/Unit/Nexus/WorkflowRunOperationTestCase.php
@@ -0,0 +1,402 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Nexus;
+
+use Spiral\Attributes\AttributeReader;
+use Temporal\Internal\Declaration\Reader\NexusServiceReader;
+use Temporal\Nexus\Handler\Internal\MethodOperationHandler;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+use PHPUnit\Framework\MockObject\MockObject;
+use Temporal\Client\WorkflowClientInterface;
+use Temporal\Client\WorkflowOptions;
+use Temporal\Client\WorkflowStubInterface;
+use Temporal\Common\WorkflowIdConflictPolicy;
+use Temporal\Internal\Nexus\NexusContext;
+use Temporal\Nexus\Exception\ErrorType;
+use Temporal\Nexus\Exception\HandlerException;
+use Temporal\Nexus\Internal\WorkflowRunOperationToken;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Nexus;
+use Temporal\Nexus\NexusOperationContext;
+use Temporal\Nexus\WorkflowHandle;
+use PHPUnit\Framework\Attributes\CoversClass;
+use Temporal\Nexus\Handler\Internal\WorkflowRunStarter;
+use Temporal\Nexus\WorkflowRunOperation;
+use Temporal\Tests\Nexus\Fixtures\Service\GreetingService;
+use Temporal\Tests\Nexus\Support\ExceptionAssertions;
+use Temporal\Tests\Unit\AbstractUnit;
+use Temporal\Worker\Environment\Environment;
+use Temporal\Worker\Environment\EnvironmentInterface;
+
+/**
+ * Mocks the WorkflowClient and exercises the {@see WorkflowRunOperation}
+ * helper end-to-end (sans the actual Temporal server).
+ *
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(WorkflowRunOperation::class)]
+#[CoversClass(WorkflowRunStarter::class)]
+#[CoversClass(MethodOperationHandler::class)]
+final class WorkflowRunOperationTestCase extends AbstractUnit
+{
+    use ExceptionAssertions;
+
+    private const NS = 'sample-ns';
+    private const WID = 'sample-wid';
+
+    /** @var WorkflowClientInterface&MockObject */
+    private WorkflowClientInterface $client;
+
+    private EnvironmentInterface $env;
+
+    public function testStartReturnsAsyncTokenAndStartsWorkflow(): void
+    {
+        $stub = $this->createMock(WorkflowStubInterface::class);
+
+        $capturedOptions = null;
+        $this->client->expects(self::once())
+            ->method('newWorkflowStub')
+            ->willReturnCallback(static function (string $class, ?WorkflowOptions $options = null) use ($stub, &$capturedOptions) {
+                $capturedOptions = $options;
+                return $stub;
+            });
+
+        $this->client->expects(self::once())
+            ->method('start')
+            ->with($stub, 42)
+            ->willReturn($this->createMock(\Temporal\Workflow\WorkflowRunInterface::class));
+
+        $handle = WorkflowHandle::fromWorkflowMethod(
+            FakeWorkflow::class,
+            WorkflowOptions::new()->withWorkflowId(self::WID),
+            42,
+        );
+
+        $info = WorkflowRunStarter::start(
+            $handle,
+            new OperationStartDetails(
+                requestId: 'req-1',
+                callbackUrl: 'https://callback.example/done',
+                callbackHeaders: ['X-Caller' => 'demo'],
+                links: [],
+            ),
+        );
+
+        self::assertInstanceOf(OperationInfo::class, $info);
+        self::assertSame(OperationState::Running, $info->state);
+
+        $expectedToken = WorkflowRunOperationToken::generate(self::NS, self::WID);
+        self::assertSame($expectedToken, $info->token);
+
+        self::assertNotNull($capturedOptions);
+        self::assertSame('req-1', $capturedOptions->requestId);
+        self::assertCount(1, $capturedOptions->completionCallbacks);
+
+        $callback = $capturedOptions->completionCallbacks[0];
+        self::assertSame('https://callback.example/done', $callback->url);
+        self::assertSame('demo', $callback->headers['X-Caller']);
+        self::assertSame($expectedToken, $callback->headers['Nexus-Operation-Token']);
+        self::assertSame($expectedToken, $callback->headers['Nexus-Operation-Id']);
+    }
+
+    public function testStartPreservesCallerProvidedTokenHeaders(): void
+    {
+        $stub = $this->createMock(WorkflowStubInterface::class);
+
+        $captured = null;
+        $this->client->method('newWorkflowStub')->willReturnCallback(
+            static function (string $class, ?WorkflowOptions $options = null) use ($stub, &$captured) {
+                $captured = $options;
+                return $stub;
+            },
+        );
+        $this->client->method('start')->willReturn($this->createMock(\Temporal\Workflow\WorkflowRunInterface::class));
+
+        WorkflowRunStarter::start(
+            WorkflowHandle::fromWorkflowMethod(
+                FakeWorkflow::class,
+                WorkflowOptions::new()->withWorkflowId(self::WID),
+            ),
+            new OperationStartDetails(
+                requestId: 'req-1',
+                callbackUrl: 'https://callback.example/done',
+                callbackHeaders: [
+                    'nexus-operation-token' => 'caller-token',
+                    'Nexus-Operation-Id' => 'caller-id',
+                ],
+                links: [],
+            ),
+        );
+
+        $callback = $captured->completionCallbacks[0];
+        self::assertSame('caller-token', $callback->headers['nexus-operation-token']);
+        self::assertSame('caller-id', $callback->headers['Nexus-Operation-Id']);
+        self::assertArrayNotHasKey('Nexus-Operation-Token', $callback->headers);
+        self::assertCount(2, $callback->headers);
+    }
+
+    public function testStartWithoutCallbackOmitsCompletionCallback(): void
+    {
+        $stub = $this->createMock(WorkflowStubInterface::class);
+
+        $captured = null;
+        $this->client->method('newWorkflowStub')->willReturnCallback(
+            static function (string $class, ?WorkflowOptions $options = null) use ($stub, &$captured) {
+                $captured = $options;
+                return $stub;
+            },
+        );
+        $this->client->method('start')->willReturn($this->createMock(\Temporal\Workflow\WorkflowRunInterface::class));
+
+        WorkflowRunStarter::start(
+            WorkflowHandle::fromWorkflowMethod(
+                FakeWorkflow::class,
+                WorkflowOptions::new()->withWorkflowId(self::WID),
+            ),
+            new OperationStartDetails(requestId: 'req-no-cb', callbackUrl: null, callbackHeaders: [], links: []),
+        );
+
+        self::assertSame([], $captured->completionCallbacks);
+        self::assertSame('req-no-cb', $captured->requestId);
+    }
+
+    public function testStartUsesNexusContextTaskQueueByDefault(): void
+    {
+        $stub = $this->createMock(WorkflowStubInterface::class);
+
+        $captured = null;
+        $this->client->method('newWorkflowStub')->willReturnCallback(
+            static function (string $class, ?WorkflowOptions $options = null) use ($stub, &$captured) {
+                $captured = $options;
+                return $stub;
+            },
+        );
+        $this->client->method('start')->willReturn($this->createMock(\Temporal\Workflow\WorkflowRunInterface::class));
+
+        WorkflowRunStarter::start(
+            WorkflowHandle::fromWorkflowMethod(
+                FakeWorkflow::class,
+                WorkflowOptions::new()->withWorkflowId(self::WID),
+            ),
+            new OperationStartDetails(requestId: 'req-test', callbackUrl: null, callbackHeaders: [], links: []),
+        );
+
+        self::assertSame('tq', $captured->taskQueue, 'task queue should fall back to Nexus context value');
+    }
+
+    public function testStartPreservesUserProvidedTaskQueue(): void
+    {
+        $stub = $this->createMock(WorkflowStubInterface::class);
+
+        $captured = null;
+        $this->client->method('newWorkflowStub')->willReturnCallback(
+            static function (string $class, ?WorkflowOptions $options = null) use ($stub, &$captured) {
+                $captured = $options;
+                return $stub;
+            },
+        );
+        $this->client->method('start')->willReturn($this->createMock(\Temporal\Workflow\WorkflowRunInterface::class));
+
+        WorkflowRunStarter::start(
+            WorkflowHandle::fromWorkflowMethod(
+                FakeWorkflow::class,
+                WorkflowOptions::new()
+                    ->withWorkflowId(self::WID)
+                    ->withTaskQueue('explicit-queue'),
+            ),
+            new OperationStartDetails(requestId: 'req-test', callbackUrl: null, callbackHeaders: [], links: []),
+        );
+
+        self::assertSame('explicit-queue', $captured->taskQueue);
+    }
+
+    public function testStartAddsSelfLinkToOperationContext(): void
+    {
+        $stub = $this->createMock(WorkflowStubInterface::class);
+        $this->client->method('newWorkflowStub')->willReturn($stub);
+
+        $run = $this->createMock(\Temporal\Workflow\WorkflowRunInterface::class);
+        $run->method('getExecution')->willReturn(
+            new \Temporal\Workflow\WorkflowExecution(self::WID, 'run-xyz'),
+        );
+        $this->client->method('start')->willReturn($run);
+
+        WorkflowRunStarter::start(
+            WorkflowHandle::fromWorkflowMethod(
+                FakeWorkflow::class,
+                WorkflowOptions::new()->withWorkflowId(self::WID),
+            ),
+            new OperationStartDetails(requestId: 'req-1', callbackUrl: null, callbackHeaders: [], links: []),
+        );
+
+        $links = Nexus::getCurrentOperationContext()->links->all();
+        self::assertCount(1, $links);
+        self::assertSame(\Temporal\Internal\Nexus\NexusLinkConverter::TYPE_WORKFLOW_EVENT, $links[0]->type);
+        self::assertStringContainsString('/namespaces/' . self::NS . '/', $links[0]->uri);
+        self::assertStringContainsString('/workflows/' . self::WID . '/run-xyz/history', $links[0]->uri);
+        self::assertStringContainsString('eventType=WorkflowExecutionStarted', $links[0]->uri);
+    }
+
+    public function testStartDoesNotForceConflictPolicyAndAlwaysAttachesOnConflictOptions(): void
+    {
+        $captured = $this->captureStartOptions(
+            WorkflowOptions::new()->withWorkflowId(self::WID),
+        );
+
+        self::assertSame(WorkflowIdConflictPolicy::Unspecified, $captured->workflowIdConflictPolicy);
+        self::assertNotNull($captured->onConflictOptions);
+    }
+
+    public function testStartPreservesExplicitFailConflictPolicyAndStillAttachesOnConflictOptions(): void
+    {
+        $captured = $this->captureStartOptions(
+            WorkflowOptions::new()
+                ->withWorkflowId(self::WID)
+                ->withWorkflowIdConflictPolicy(WorkflowIdConflictPolicy::Fail),
+        );
+
+        self::assertSame(WorkflowIdConflictPolicy::Fail, $captured->workflowIdConflictPolicy);
+        self::assertNotNull($captured->onConflictOptions);
+    }
+
+    public function testStartPreservesExplicitUseExistingConflictPolicy(): void
+    {
+        $captured = $this->captureStartOptions(
+            WorkflowOptions::new()
+                ->withWorkflowId(self::WID)
+                ->withWorkflowIdConflictPolicy(WorkflowIdConflictPolicy::UseExisting),
+        );
+
+        self::assertSame(WorkflowIdConflictPolicy::UseExisting, $captured->workflowIdConflictPolicy);
+        self::assertNotNull($captured->onConflictOptions);
+    }
+
+    public function testStartAcceptsExplicitWorkflowId(): void
+    {
+        $captured = $this->captureStartOptions(
+            WorkflowOptions::new()->withWorkflowId(self::WID),
+        );
+
+        self::assertSame(self::WID, $captured->workflowId);
+    }
+
+    public function testCancelDecodesTokenAndCancelsWorkflow(): void
+    {
+        $token = WorkflowRunOperationToken::generate(self::NS, self::WID);
+        $stub = $this->createMock(WorkflowStubInterface::class);
+        $stub->expects(self::once())->method('cancel');
+
+        $this->client->expects(self::once())
+            ->method('newUntypedRunningWorkflowStub')
+            ->with(self::WID)
+            ->willReturn($stub);
+
+        WorkflowRunOperation::cancel($token);
+    }
+
+    public function testCancelRejectsBadTokenAsBadRequest(): void
+    {
+        $e = self::assertThrown(
+            HandlerException::class,
+            static fn() => WorkflowRunOperation::cancel('not-a-real-token'),
+        );
+        self::assertSame(ErrorType::BadRequest, $e->errorType);
+        self::assertFalse($e->isRetryable());
+        self::assertStringContainsString('failed to parse operation token', $e->getMessage());
+    }
+
+    public function testCancelIgnoresTokenNamespaceAndCancelsByWorkflowId(): void
+    {
+        $token = WorkflowRunOperationToken::generate('other-ns', self::WID);
+
+        $stub = $this->createMock(WorkflowStubInterface::class);
+        $stub->expects(self::once())->method('cancel');
+
+        $this->client->expects(self::once())
+            ->method('newUntypedRunningWorkflowStub')
+            ->with(self::WID)
+            ->willReturn($stub);
+
+        WorkflowRunOperation::cancel($token);
+    }
+
+    public function testHandlerWithoutCancelRoutineAutoCancelsWorkflowRun(): void
+    {
+        $token = WorkflowRunOperationToken::generate(self::NS, self::WID);
+
+        $stub = $this->createMock(WorkflowStubInterface::class);
+        $stub->expects(self::once())->method('cancel');
+
+        $this->client->expects(self::once())
+            ->method('newUntypedRunningWorkflowStub')
+            ->with(self::WID)
+            ->willReturn($stub);
+
+        $service = new GreetingService(static fn(string $n): string => $n);
+        $this->handlerFor($service, 'sayHello2')->cancel(
+            new OperationContext(service: 'svc', operation: 'sayHello2', env: $this->env),
+            new OperationCancelDetails(operationToken: $token),
+        );
+    }
+
+    protected function setUp(): void
+    {
+        $this->env = new Environment();
+        $this->client = $this->createMock(WorkflowClientInterface::class);
+        Nexus::setCurrentContext(new NexusContext(
+            operation: new NexusOperationContext(self::NS, 'tq'),
+            workflowClient: $this->client,
+            current: new OperationContext(service: 'svc', operation: 'op', env: $this->env),
+        ));
+    }
+
+    protected function tearDown(): void
+    {
+        Nexus::setCurrentContext(null);
+    }
+
+    private function handlerFor(object $service, string $operation): MethodOperationHandler
+    {
+        $prototype = (new NexusServiceReader(new AttributeReader()))->fromClass(\get_class($service));
+        $operationPrototype = $prototype->getOperations()[$operation];
+
+        return new MethodOperationHandler(
+            instance: $service,
+            startMethod: new \ReflectionMethod($service, $operationPrototype->methodName),
+            operation: $operationPrototype,
+        );
+    }
+
+    private function captureStartOptions(WorkflowOptions $handleOptions): WorkflowOptions
+    {
+        $stub = $this->createMock(WorkflowStubInterface::class);
+
+        $captured = null;
+        $this->client->method('newWorkflowStub')->willReturnCallback(
+            static function (string $class, ?WorkflowOptions $options = null) use ($stub, &$captured) {
+                $captured = $options;
+                return $stub;
+            },
+        );
+        $this->client->method('start')->willReturn($this->createMock(\Temporal\Workflow\WorkflowRunInterface::class));
+
+        WorkflowRunStarter::start(
+            WorkflowHandle::fromWorkflowMethod(FakeWorkflow::class, $handleOptions),
+            new OperationStartDetails(requestId: 'req-policy', callbackUrl: null, callbackHeaders: [], links: []),
+        );
+
+        self::assertNotNull($captured);
+        return $captured;
+    }
+}
+
+/**
+ * @internal Local fixture — needed only as a class-string for WorkflowHandle.
+ */
+final class FakeWorkflow {}
diff --git a/tests/Unit/Nexus/WorkflowRunOperationTokenTestCase.php b/tests/Unit/Nexus/WorkflowRunOperationTokenTestCase.php
new file mode 100644
index 000000000..0f52dae65
--- /dev/null
+++ b/tests/Unit/Nexus/WorkflowRunOperationTokenTestCase.php
@@ -0,0 +1,129 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Nexus;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Temporal\Nexus\Internal\WorkflowRunOperationToken;
+use Temporal\Tests\Unit\AbstractUnit;
+
+/**
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(WorkflowRunOperationToken::class)]
+final class WorkflowRunOperationTokenTestCase extends AbstractUnit
+{
+    /**
+     * Golden vectors generated by the Go reference at
+     * `sdk-go/temporalnexus/token.go::generateWorkflowRunOperationToken` —
+     * the wire format must stay byte-identical so PHP-issued tokens decode
+     * cleanly on a Go-typed handler/server and vice-versa.
+     */
+    public static function goldenVectors(): array
+    {
+        return [
+            'sample-style' => [
+                'namespace' => 'my-target-namespace',
+                'workflowId' => 'my-workflow-id',
+                'expected' => 'eyJ0IjoxLCJucyI6Im15LXRhcmdldC1uYW1lc3BhY2UiLCJ3aWQiOiJteS13b3JrZmxvdy1pZCJ9',
+            ],
+            'short' => [
+                'namespace' => 'default',
+                'workflowId' => 'abc',
+                'expected' => 'eyJ0IjoxLCJucyI6ImRlZmF1bHQiLCJ3aWQiOiJhYmMifQ',
+            ],
+            'special-chars-in-ns' => [
+                'namespace' => 'ns-with/special.chars',
+                'workflowId' => 'wid-1234',
+                'expected' => 'eyJ0IjoxLCJucyI6Im5zLXdpdGgvc3BlY2lhbC5jaGFycyIsIndpZCI6IndpZC0xMjM0In0',
+            ],
+            'both-empty' => [
+                'namespace' => '',
+                'workflowId' => '',
+                'expected' => 'eyJ0IjoxLCJucyI6IiIsIndpZCI6IiJ9',
+            ],
+        ];
+    }
+
+    #[DataProvider('goldenVectors')]
+    public function testEncodeMatchesGoReference(string $namespace, string $workflowId, string $expected): void
+    {
+        self::assertSame($expected, WorkflowRunOperationToken::generate($namespace, $workflowId));
+    }
+
+    public function testRoundtripWorkflowIdAndNamespace(): void
+    {
+        $token = WorkflowRunOperationToken::generate('ns-A', 'wf-42');
+        $decoded = WorkflowRunOperationToken::load($token);
+
+        self::assertSame('ns-A', $decoded->namespace);
+        self::assertSame('wf-42', $decoded->workflowId);
+    }
+
+    public function testLoadRejectsEmptyToken(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('token is empty');
+        WorkflowRunOperationToken::load('');
+    }
+
+    public function testLoadRejectsBadBase64(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('failed to decode token');
+        WorkflowRunOperationToken::load('!!!not-base64!!!');
+    }
+
+    public function testLoadRejectsNonJson(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('failed to unmarshal');
+        // base64 of "not-json"
+        WorkflowRunOperationToken::load('bm90LWpzb24');
+    }
+
+    public function testLoadRejectsWrongType(): void
+    {
+        // {"t":2,"ns":"x","wid":"y"} — t=2 is not workflow-run
+        $bad = \rtrim(\strtr(\base64_encode('{"t":2,"ns":"x","wid":"y"}'), '+/', '-_'), '=');
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('invalid workflow token type');
+        WorkflowRunOperationToken::load($bad);
+    }
+
+    public function testLoadRejectsMissingWorkflowId(): void
+    {
+        // {"t":1,"ns":"x"} — wid missing
+        $bad = \rtrim(\strtr(\base64_encode('{"t":1,"ns":"x"}'), '+/', '-_'), '=');
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('missing workflow ID');
+        WorkflowRunOperationToken::load($bad);
+    }
+
+    public function testLoadRejectsExplicitVersionField(): void
+    {
+        // {"v":2,"t":1,"ns":"x","wid":"y"} — v present and non-zero
+        $bad = \rtrim(\strtr(\base64_encode('{"v":2,"t":1,"ns":"x","wid":"y"}'), '+/', '-_'), '=');
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('unsupported version');
+        WorkflowRunOperationToken::load($bad);
+    }
+
+    public function testLoadAcceptsExplicitVersionZero(): void
+    {
+        // {"v":0,"t":1,"ns":"x","wid":"y"} — v=0 is the implicit default,
+        // accepted by the Go reference even when explicitly written out.
+        $ok = \rtrim(\strtr(\base64_encode('{"v":0,"t":1,"ns":"x","wid":"y"}'), '+/', '-_'), '=');
+
+        $decoded = WorkflowRunOperationToken::load($ok);
+
+        self::assertSame('x', $decoded->namespace);
+        self::assertSame('y', $decoded->workflowId);
+    }
+}
diff --git a/tests/Unit/Worker/NexusRegistrationGuardTestCase.php b/tests/Unit/Worker/NexusRegistrationGuardTestCase.php
new file mode 100644
index 000000000..181e1661b
--- /dev/null
+++ b/tests/Unit/Worker/NexusRegistrationGuardTestCase.php
@@ -0,0 +1,127 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Worker;
+
+use Temporal\Client\WorkflowOptions;
+use Temporal\Nexus\Attribute\AsyncOperation;
+use Temporal\Nexus\Attribute\Operation;
+use Temporal\Nexus\Attribute\Service;
+use Temporal\Nexus\Handler\OperationCancelDetails;
+use Temporal\Nexus\Handler\OperationContext;
+use Temporal\Nexus\Handler\OperationHandlerInterface;
+use Temporal\Nexus\Handler\OperationStartDetails;
+use Temporal\Nexus\Handler\OperationStartResult;
+use Temporal\Nexus\OperationInfo;
+use Temporal\Nexus\OperationState;
+use Temporal\Nexus\WorkflowHandle;
+use Temporal\Tests\Unit\AbstractUnit;
+use Temporal\WorkerFactory;
+
+#[Service]
+interface GuardSyncOnlyService
+{
+    #[Operation]
+    public function greet(string $name): string;
+}
+
+class GuardSyncOnlyServiceImpl implements GuardSyncOnlyService
+{
+    public function greet(string $name): string
+    {
+        return "Hello, {$name}!";
+    }
+}
+
+#[Service]
+interface GuardAsyncService
+{
+    #[AsyncOperation(output: 'string')]
+    public function runAsync(string $input): WorkflowHandle;
+}
+
+class GuardAsyncServiceImpl implements GuardAsyncService
+{
+    public function runAsync(string $input): WorkflowHandle
+    {
+        return WorkflowHandle::fromWorkflowMethod(
+            self::class,
+            WorkflowOptions::new()->withWorkflowId('guard'),
+        );
+    }
+}
+
+#[Service]
+interface GuardManualService
+{
+    #[AsyncOperation(output: 'string', input: 'string')]
+    public function manualOp(): GuardManualHandler;
+}
+
+final class GuardManualHandler implements OperationHandlerInterface
+{
+    public function start(
+        OperationContext $context,
+        OperationStartDetails $details,
+        mixed $param,
+    ): OperationStartResult {
+        return OperationStartResult::async(new OperationInfo('guard-token', OperationState::Running));
+    }
+
+    public function cancel(
+        OperationContext $context,
+        OperationCancelDetails $details,
+    ): void {}
+}
+
+class GuardManualServiceImpl implements GuardManualService
+{
+    public function manualOp(): GuardManualHandler
+    {
+        return new GuardManualHandler();
+    }
+}
+
+/**
+ * @group unit
+ * @group worker
+ * @group nexus
+ */
+final class NexusRegistrationGuardTestCase extends AbstractUnit
+{
+    public function testSyncOnlyServiceWithoutClientIsAllowed(): void
+    {
+        $worker = WorkerFactory::create()->newWorker();
+
+        $worker->registerNexusServiceImplementation(new GuardSyncOnlyServiceImpl());
+
+        self::assertCount(1, $worker->getNexusServices());
+    }
+
+    public function testAsyncServiceWithoutClientThrows(): void
+    {
+        $worker = WorkerFactory::create()->newWorker();
+
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessage('declares async operation "runAsync", which needs cluster access');
+
+        $worker->registerNexusServiceImplementation(new GuardAsyncServiceImpl());
+    }
+
+    public function testFactoryBackedAsyncServiceWithoutClientIsAllowed(): void
+    {
+        $worker = WorkerFactory::create()->newWorker();
+
+        $worker->registerNexusServiceImplementation(new GuardManualServiceImpl());
+
+        self::assertCount(1, $worker->getNexusServices());
+    }
+}
diff --git a/tests/Unit/Workflow/NexusOperationCancellationTypeTestCase.php b/tests/Unit/Workflow/NexusOperationCancellationTypeTestCase.php
new file mode 100644
index 000000000..a5ed0fdeb
--- /dev/null
+++ b/tests/Unit/Workflow/NexusOperationCancellationTypeTestCase.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Workflow;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use Temporal\Tests\Unit\AbstractUnit;
+use Temporal\Workflow\NexusOperationCancellationType;
+
+/**
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(NexusOperationCancellationType::class)]
+final class NexusOperationCancellationTypeTestCase extends AbstractUnit
+{
+    public function testEnumValuesMatchSdkGoIotaOrder(): void
+    {
+        // Wire-level integers must stay aligned with sdk-go's iota order;
+        // drift here is a wire-level break.
+        self::assertSame(0, NexusOperationCancellationType::Unspecified->value);
+        self::assertSame(1, NexusOperationCancellationType::Abandon->value);
+        self::assertSame(2, NexusOperationCancellationType::TryCancel->value);
+        self::assertSame(3, NexusOperationCancellationType::WaitRequested->value);
+        self::assertSame(4, NexusOperationCancellationType::WaitCompleted->value);
+    }
+}
diff --git a/tests/Unit/Workflow/NexusOperationHandleTestCase.php b/tests/Unit/Workflow/NexusOperationHandleTestCase.php
new file mode 100644
index 000000000..233e6f688
--- /dev/null
+++ b/tests/Unit/Workflow/NexusOperationHandleTestCase.php
@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Workflow;
+
+use React\Promise\Deferred;
+use PHPUnit\Framework\Attributes\CoversClass;
+use Temporal\Tests\Unit\AbstractUnit;
+use Temporal\Workflow\NexusOperationHandle;
+
+/**
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(NexusOperationHandle::class)]
+final class NexusOperationHandleTestCase extends AbstractUnit
+{
+    public function testGetResultReturnsTheWrappedPromise(): void
+    {
+        $deferred = new Deferred();
+        $handle = new NexusOperationHandle(
+            operationToken: null,
+            rawResult: $deferred->promise(),
+        );
+
+        $received = null;
+        $handle->getResult()->then(
+            function ($v) use (&$received): void {
+                $received = $v;
+            },
+        );
+
+        $deferred->resolve('hello');
+        self::assertSame('hello', $received);
+    }
+
+    public function testGetResultIsIdempotent(): void
+    {
+        $handle = new NexusOperationHandle(
+            operationToken: null,
+            rawResult: (new Deferred())->promise(),
+        );
+
+        self::assertSame($handle->getResult(), $handle->getResult());
+    }
+
+    public function testTokenAvailableBeforeResultResolves(): void
+    {
+        $deferred = new Deferred();
+        $handle = new NexusOperationHandle(
+            operationToken: 'observed-while-pending',
+            rawResult: $deferred->promise(),
+        );
+
+        self::assertSame('observed-while-pending', $handle->getOperationToken());
+
+        $resolved = false;
+        $handle->getResult()->then(static function () use (&$resolved): void {
+            $resolved = true;
+        });
+        self::assertFalse($resolved);
+    }
+
+    public function testGetOperationTokenReturnsNullForSyncOperation(): void
+    {
+        $handle = new NexusOperationHandle(
+            operationToken: null,
+            rawResult: (new Deferred())->promise(),
+        );
+
+        self::assertNull($handle->getOperationToken());
+    }
+
+    public function testGetOperationTokenReturnsTokenForAsyncOperation(): void
+    {
+        $handle = new NexusOperationHandle(
+            operationToken: 'op-token-xyz',
+            rawResult: (new Deferred())->promise(),
+        );
+
+        self::assertSame('op-token-xyz', $handle->getOperationToken());
+    }
+}
diff --git a/tests/Unit/Workflow/NexusOperationOptionsTestCase.php b/tests/Unit/Workflow/NexusOperationOptionsTestCase.php
new file mode 100644
index 000000000..2ee5305d8
--- /dev/null
+++ b/tests/Unit/Workflow/NexusOperationOptionsTestCase.php
@@ -0,0 +1,176 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Temporal\Tests\Unit\Workflow;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use Temporal\Nexus\Exception\InvalidArgumentException;
+use Temporal\Tests\Unit\DTO\AbstractDTOMarshalling;
+use Temporal\Workflow\NexusOperationCancellationType;
+use Temporal\Workflow\NexusOperationOptions;
+
+/**
+ * @group unit
+ * @group nexus
+ */
+#[CoversClass(NexusOperationOptions::class)]
+final class NexusOperationOptionsTestCase extends AbstractDTOMarshalling
+{
+    public function testNewHasEmptyDefaults(): void
+    {
+        $options = NexusOperationOptions::new();
+
+        self::assertSame('', $options->endpoint);
+        self::assertSame('', $options->service);
+        self::assertSame(0, $options->scheduleToCloseTimeout->s);
+    }
+
+    public function testWithEndpointSetsEndpoint(): void
+    {
+        $options = NexusOperationOptions::new()->withEndpoint('endpoint-1');
+
+        self::assertSame('endpoint-1', $options->endpoint);
+    }
+
+    public function testWithEndpointRejectsEmptyString(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Nexus Endpoint must not be empty');
+
+        NexusOperationOptions::new()->withEndpoint('');
+    }
+
+    public function testWithEndpointIsImmutable(): void
+    {
+        $original = NexusOperationOptions::new();
+        $updated = $original->withEndpoint('endpoint-2');
+
+        self::assertNotSame($original, $updated);
+        self::assertSame('', $original->endpoint, 'Original must stay pristine');
+        self::assertSame('endpoint-2', $updated->endpoint);
+    }
+
+    public function testWithServiceSetsService(): void
+    {
+        $options = NexusOperationOptions::new()->withService('MyService');
+
+        self::assertSame('MyService', $options->service);
+    }
+
+    public function testWithServiceRejectsEmptyString(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Service Name must not be empty');
+
+        NexusOperationOptions::new()->withService('');
+    }
+
+    public function testWithScheduleToCloseTimeoutAcceptsSeconds(): void
+    {
+        $options = NexusOperationOptions::new()->withScheduleToCloseTimeout(30);
+
+        self::assertSame(30, $options->scheduleToCloseTimeout->s);
+    }
+
+    public function testWithScheduleToStartTimeoutAcceptsSeconds(): void
+    {
+        $options = NexusOperationOptions::new()->withScheduleToStartTimeout(5);
+
+        self::assertSame(5, $options->scheduleToStartTimeout->s);
+    }
+
+    public function testWithScheduleToStartTimeoutIsImmutable(): void
+    {
+        $original = NexusOperationOptions::new();
+        $updated = $original->withScheduleToStartTimeout(5);
+
+        self::assertNotSame($original, $updated);
+        self::assertSame(0, $original->scheduleToStartTimeout->s, 'Original must stay pristine');
+        self::assertSame(5, $updated->scheduleToStartTimeout->s);
+    }
+
+    public function testWithStartToCloseTimeoutAcceptsSeconds(): void
+    {
+        $options = NexusOperationOptions::new()->withStartToCloseTimeout(10);
+
+        self::assertSame(10, $options->startToCloseTimeout->s);
+    }
+
+    public function testWithStartToCloseTimeoutIsImmutable(): void
+    {
+        $original = NexusOperationOptions::new();
+        $updated = $original->withStartToCloseTimeout(10);
+
+        self::assertNotSame($original, $updated);
+        self::assertSame(0, $original->startToCloseTimeout->s, 'Original must stay pristine');
+        self::assertSame(10, $updated->startToCloseTimeout->s);
+    }
+
+    public function testMarshalsNewTimeoutsUnderWireKeys(): void
+    {
+        $options = NexusOperationOptions::new()
+            ->withScheduleToStartTimeout(5)
+            ->withStartToCloseTimeout(10);
+
+        $marshalled = $this->marshal($options);
+
+        self::assertArrayHasKey('scheduleToStartTimeout', $marshalled);
+        self::assertArrayHasKey('startToCloseTimeout', $marshalled);
+        self::assertSame(5_000_000_000, $marshalled['scheduleToStartTimeout']);
+        self::assertSame(10_000_000_000, $marshalled['startToCloseTimeout']);
+    }
+
+    public function testCancellationTypeDefaultsToUnspecified(): void
+    {
+        $options = NexusOperationOptions::new();
+
+        self::assertSame(NexusOperationCancellationType::Unspecified, $options->cancellationType);
+    }
+
+    public function testWithCancellationTypeAcceptsEnum(): void
+    {
+        $options = NexusOperationOptions::new()
+            ->withCancellationType(NexusOperationCancellationType::TryCancel);
+
+        self::assertSame(NexusOperationCancellationType::TryCancel, $options->cancellationType);
+    }
+
+    public function testWithCancellationTypeAcceptsInt(): void
+    {
+        $options = NexusOperationOptions::new()
+            ->withCancellationType(NexusOperationCancellationType::WaitCompleted->value);
+
+        self::assertSame(NexusOperationCancellationType::WaitCompleted, $options->cancellationType);
+    }
+
+    public function testWithCancellationTypeIsImmutable(): void
+    {
+        $original = NexusOperationOptions::new();
+        $updated = $original->withCancellationType(NexusOperationCancellationType::Abandon);
+
+        self::assertNotSame($original, $updated);
+        self::assertSame(
+            NexusOperationCancellationType::Unspecified,
+            $original->cancellationType,
+            'Original must stay pristine',
+        );
+        self::assertSame(NexusOperationCancellationType::Abandon, $updated->cancellationType);
+    }
+
+    public function testWithEndpointRejectsReservedTemporalPrefix(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Nexus Endpoint "__temporal_endpoint" must not start with "__temporal_"');
+
+        NexusOperationOptions::new()->withEndpoint('__temporal_endpoint');
+    }
+
+    public function testWithServiceRejectsReservedTemporalPrefix(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Service Name "__temporal_service" must not start with "__temporal_"');
+
+        NexusOperationOptions::new()->withService('__temporal_service');
+    }
+}