Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
aa00b77
Prepare the installed PHP command-key acceptance adapter
rmcdaniel Nov 13, 2026
c378e23
Verify command-key SDK supply before package loading
rmcdaniel Nov 13, 2026
fa63aa3
Bind the modern installed command-key cohort to exact supply and runt…
rmcdaniel Nov 13, 2026
242f155
Require exact Docker absence receipts and an empty private configuration
rmcdaniel Nov 13, 2026
4bcb415
Launch captured controller bytes through a digest-bound Git bootstrap
rmcdaniel Nov 13, 2026
a38a0fe
Prepare the complete data-only PHP include closure inventory
rmcdaniel Nov 13, 2026
e4f65ea
Recognize both exact Docker CLI missing-object forms
rmcdaniel Nov 13, 2026
55273aa
Confine command-key includes and isolate captured-ID cleanup
rmcdaniel Nov 13, 2026
3ec4733
Clarify inert closure assertions for static analysis
rmcdaniel Nov 13, 2026
1c5d562
Bind staged SDK leaves to approved archive authority
rmcdaniel Nov 13, 2026
bdbc8de
Bind containerd image indexes to exact platform manifests
rmcdaniel Nov 13, 2026
7078b55
Prepare synthetic consumer mount boundary controls
rmcdaniel Nov 13, 2026
90ee5d2
Carry literal fixture authority across privileged staging
rmcdaniel Nov 13, 2026
de6b5b7
Stop boundary entry on an inert control failure
rmcdaniel Nov 13, 2026
85861c8
Handle legacy tmpfs inspection in command-key runner
rmcdaniel Nov 13, 2026
c34e0b2
Prepare isolated cleanup control after fixture refusal
rmcdaniel Nov 13, 2026
3d1d831
Reconcile lost create IDs during independent fixture cleanup
rmcdaniel Nov 13, 2026
c7eb2ef
Merge main into agent/sdk-php/216-installed-consumer
rmcdaniel Nov 18, 2026
ff13276
Type ambiguous command keys and run the published command-key cohort …
rmcdaniel Nov 18, 2026
2bd5b05
Use the current bound PHP setup in the command-key workflow
rmcdaniel Nov 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,13 @@ jobs:
run: python -I scripts/ci/test-apt-no-retries.py
- name: Verify PHP container launcher boundaries
run: python -I -S -B tests/ci/test_php_container_launcher.py
- name: Verify command-key package and runtime provenance controls
run: |
python3 -I -S -B tests/ci/test_command_key_supply.py
python3 -I -S -B tests/ci/test_command_key_cohort.py
python3 -I -S -B tests/ci/test_command_key_containers.py
python3 -I -S -B tests/ci/test_command_key_include_closure.py
python3 -I -S -B tests/ci/test_command_key_mount_boundary.py

test:
name: PHP ${{ matrix.php }}
Expand Down
279 changes: 279 additions & 0 deletions .github/workflows/published-command-keys.yml

Large diffs are not rendered by default.

8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,14 @@ project follows [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added

- `SignalFailed::isRequestIdAmbiguous()` and `UpdateFailed::isRequestIdAmbiguous()`
detect the 409 `request_id_ambiguous` refusal native Server 3.9.2 and later
return when a command key matches an ambiguous legacy retained identity
(durable-workflow/.github#216). Nothing was written and no receipt was
selected, so the refusal is never resent automatically.

## [3.20.0] - 2026-11-18

### Added
Expand Down
10 changes: 10 additions & 0 deletions docs/sdk-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -401,6 +401,16 @@ command key on the workflow instance:
(`name`, `arguments` or `target_or_arguments`) and `retainedCommandId()`
names the original command. Don't retry it unchanged: send the original input
to recover the receipt, or use a new key for new input.
- A key retained before the Server recorded command intent (a legacy receipt)
reads back the original receipt with `retained: true` and
`intent_verified: false`. The Server can't prove the retry matches it, so it
neither admits a new command nor reports equality; check the receipt's
identities before treating it as your command.
- A key that matches an ambiguous legacy identity (a raw legacy key and a
hashed key, or keys differing only by case on a case-insensitive database) is
refused with 409 `request_id_ambiguous` and `isRequestIdAmbiguous()` is true.
Nothing is written and no receipt is selected; inspect the original command
before sending the input under a new key.

```php
use DurableWorkflow\Exception\SignalFailed;
Expand Down
14 changes: 14 additions & 0 deletions src/Exception/CarriesCommandRequestId.php
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,20 @@ public function isRequestIdConflict(): bool
return $this->status === 409 && $this->reason === 'request_id_conflict';
}

/**
* Whether the Server refused the key because it matches an ambiguous retained identity.
*
* A 409 `request_id_ambiguous` (`rejected_request_id_ambiguous`) means the key matches a
* legacy retained command that the Server cannot select safely, for example a raw legacy
* key and a hashed key, or keys that differ only by case on a case-insensitive database.
* Nothing was written and no receipt was selected. Don't retry this unchanged: inspect the
* original command before sending the input again under a new key.
*/
public function isRequestIdAmbiguous(): bool
{
return $this->status === 409 && $this->reason === 'request_id_ambiguous';
}

/**
* The parts of the refused command that differ from the retained one, for a
* `request_id_conflict`: `name`, `arguments` or `target_or_arguments`. Otherwise empty.
Expand Down
94 changes: 94 additions & 0 deletions tests/CommandRequestKeysTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,100 @@ public function testAnIdenticalRetryReturnsTheOriginalReceipt(): void
self::assertSame($bodies[2], $bodies[3]);
}

public function testAnAmbiguousLegacyKeyIsATypedRefusalSentOnce(): void
{
$requests = [];
$client = $this->answering(409, [
'workflow_id' => 'order-1',
'reason' => 'request_id_ambiguous',
'outcome' => 'rejected_request_id_ambiguous',
'command_status' => 'rejected',
'rejection_reason' => 'request_id_ambiguous',
'retained' => true,
'intent_verified' => false,
'retryable' => false,
'message' => 'The request_id matches an ambiguous retained command identity.',
], $requests);

foreach (['signal', 'update'] as $kind) {
try {
$kind === 'signal'
? $client->signalWorkflow('order-1', 'approve', ['Ada'], requestId: 'legacy-1')
: $client->updateWorkflowReceipt('order-1', 'approve', ['Ada'], 'accepted', requestId: 'legacy-1');
self::fail('An ambiguous key must be refused.');
} catch (SignalFailed|UpdateFailed $exception) {
self::assertInstanceOf($kind === 'signal' ? SignalFailed::class : UpdateFailed::class, $exception);
self::assertSame(409, $exception->status);
self::assertTrue($exception->isRequestIdAmbiguous());
self::assertFalse($exception->isRequestIdConflict());
self::assertSame('legacy-1', $exception->requestId());
self::assertSame([], $exception->conflict());
self::assertNull($exception->retainedCommandId());
self::assertSame('rejected_request_id_ambiguous', $exception->details()['outcome']);
self::assertFalse($exception->details()['intent_verified']);
}
}

self::assertCount(2, $requests);
}

public function testALegacyReceiptReadsBackUnverifiedWithoutAnError(): void
{
$requests = [];
$client = $this->answering(202, [
'workflow_id' => 'order-1',
'command_id' => 'cmd-legacy',
'run_id' => 'run-1',
'command_status' => 'accepted',
'outcome' => 'signal_received',
'retained' => true,
'intent_verified' => false,
], $requests);

$receipt = $client->signalWorkflow('order-1', 'approve', ['Grace'], requestId: 'legacy-1');
self::assertSame('cmd-legacy', $receipt['command_id']);
self::assertTrue($receipt['retained']);
self::assertFalse($receipt['intent_verified']);
self::assertSame('legacy-1', $receipt['request_id']);
self::assertCount(1, $requests);
}

public function testAGeneratedKeyIsSentOnceAndCarriedByTheFailure(): void
{
$requests = [];
$client = $this->answering(503, ['reason' => 'unavailable', 'message' => 'Try again.'], $requests);

try {
$client->signalWorkflow('order-1', 'approve', ['Ada']);
self::fail('A 503 must surface.');
} catch (SignalFailed $exception) {
$key = $exception->requestId();
self::assertIsString($key);
self::assertMatchesRegularExpression('/\Asdk-php-signal-[0-9a-f]{32}\z/', $key);
self::assertCount(1, $requests);
$body = json_decode((string) $requests[0]->getBody(), true, flags: JSON_THROW_ON_ERROR);
self::assertSame($key, $body['request_id']);
}
}

/**
* @param array<string, mixed> $response
* @param list<RequestInterface> $requests
*/
private function answering(int $status, array $response, array &$requests): Client
{
$http = new GuzzleClient(['handler' => static function (RequestInterface $request) use ($status, $response, &$requests) {
if ($request->getUri()->getPath() === '/api/cluster/info') {
return Create::promiseFor(new Response(200, [], json_encode(['capabilities' => ['command_request_keys' => true]], JSON_THROW_ON_ERROR)));
}
$requests[] = $request;

return Create::promiseFor(new Response($status, [], json_encode($response, JSON_THROW_ON_ERROR)));
}]);

return new Client('https://runtime.test', transport: new Psr18Transport($http), controlToken: 'fixture-client');
}

public function testAnOlderServerWithoutTheCapabilityIsUnchanged(): void
{
[$client, $requests] = $this->server(native: false);
Expand Down
Loading
Loading