Document PHP activity identity and idempotency guidance

docs/constraints/execution-guarantees.md

@@ -154,6 +154,17 @@ not claim authority, and does not make an external effect exactly once. Keep
 downstream idempotency, distinct keys for different effects and outcome
 reconciliation.
 
+PHP service-mode activities expose the read-only nullable
+`ActivityContext::activityExecutionId` from the received claim, with `workflowId`
+and `runId` for the owning workflow and run. Keep the logical execution ID
+across retries. Missing identity stays `null`; a task, attempt or session ID is
+not a fallback. The [PHP identity guide](../polyglot/php.md#activity-identity)
+links the SDK-owned service-key example and defines absent, session,
+historical prepared-local, inline-local and Server-free cases. These accessors
+are public metadata, not claim authority. External effects still need
+downstream idempotency, distinct keys for different effects and outcome
+reconciliation.
+
 ## What Developers Must Make Idempotent
 
 You do **not** need to make workflow replay itself idempotent. The framework

docs/polyglot/php.md

@@ -163,6 +163,14 @@ Keep signal processing idempotent for the business event. A stable request ID al
 
 See the [complete final-attempt and own-run signal examples](https://php.durable-workflow.com/build/workflows-activities/) in the PHP SDK guide.
 
+## Logical activity execution identity {#activity-identity}
+
+PHP SDK **3.10.0 or later** exposes the read-only nullable `ActivityContext::activityExecutionId` received with an activity claim. It identifies the logical activity across retries. `workflowId` and `runId` identify its owning workflow instance and run; `activityAttemptId` identifies an attempt. Do not substitute a task, attempt or session ID for a missing logical execution ID.
+
+The SDK preserves the received nonempty string exactly. Omitted, null, empty or non-string identity values produce `null`. Use an application-owned business key when it is unavailable. The [SDK-owned service-key example](https://php.durable-workflow.com/build/workflows-activities/#inspect-retry-budget-and-the-owning-workflow) shows that fallback; the [property reference](https://php.durable-workflow.com/api/classes/DurableWorkflow-Worker-ActivityContext.html#property_activityExecutionId) defines the public API. Scope keys to the application and effect, use distinct keys for distinct effects, and reconcile uncertain outcomes with the destination. Identity is public metadata, not claim authority or an exactly-once external-effects guarantee.
+
+Ordinary and cooperatively supervised remote callbacks read the actual claim field. Session callbacks expose it only when their claim includes it. Inline local and Server-free callbacks without Server admission have `null` execution identity, even when their parent workflow/run IDs are known. Historical prepared-local source forwards its validated admission ID; that source behavior does not establish native prepared-local support. These are source/dataflow boundaries, not installed retry observations for every execution mode.
+
 ## Activity heartbeats {#activity-heartbeats}
 
 For remote activities, call `ActivityContext::heartbeat($details)` during bounded work, well before the configured heartbeat timeout. The first window starts at runtime claim, not when PHP receives the task. Request latency, pauses and transport retries consume that window. Follow the [cadence guidance](../features/heartbeats.md#heartbeat-cadence-and-receipts).

i18n/de/docusaurus-plugin-content-docs/current/constraints/execution-guarantees.md

@@ -128,6 +128,8 @@ Server belegt nur die Identität bei gewöhnlichen Wiederholungen. Die ID ist
 nicht Exactly-once. Behalten Sie nachgelagerte Idempotenz, unterschiedliche
 Schlüssel für verschiedene Effekte und Ergebnisabgleich bei.
 
+PHP-Service-Activities liefern die schreibgeschützte nullable Eigenschaft `ActivityContext::activityExecutionId` aus dem empfangenen Claim sowie `workflowId` und `runId` des besitzenden Workflows und Laufs. Behalten Sie die logische Ausführungs-ID über Wiederholungen hinweg. Fehlende Identität bleibt `null`; eine Task-, Versuchs- oder Session-ID ist kein Fallback. Der [PHP-Identitätsleitfaden](../polyglot/php.md#activity-identity) verlinkt das Service-Key-Beispiel des SDKs und definiert fehlende, Session-, historische Prepared-local-, Inline-local- und Server-freie Fälle. Diese Zugriffswerte sind öffentliche Metadaten, keine Claim-Autorität. Externe Effekte benötigen weiterhin nachgelagerte Idempotenz, getrennte Schlüssel für verschiedene Effekte und Ergebnisabgleich.
+
 ## Was die Anwendung idempotent machen muss {#what-developers-must-make-idempotent}
 
 Workflow-Replay selbst müssen Sie nicht idempotent machen. Das Framework rekonstruiert den Zustand aus der festgeschriebenen Historie.

i18n/de/docusaurus-plugin-content-docs/current/polyglot/php.md

@@ -166,6 +166,14 @@ Verarbeiten Sie Signale für das Geschäftsereignis idempotent. Eine stabile Req
 
 Die [vollständigen Beispiele zum letzten Versuch und zum Signal an den eigenen Lauf](https://php.durable-workflow.com/build/workflows-activities/) stehen im PHP-SDK-Leitfaden.
 
+## Logische Activity-Ausführungsidentität {#activity-identity}
+
+PHP SDK **3.10.0 oder neuer** stellt die schreibgeschützte nullable Eigenschaft `ActivityContext::activityExecutionId` aus dem Activity-Claim bereit. Sie identifiziert die logische Activity über Wiederholungen hinweg. `workflowId` und `runId` bezeichnen die besitzende Workflow-Instanz und ihren Lauf; `activityAttemptId` bezeichnet einen Versuch. Ersetzen Sie eine fehlende logische Ausführungs-ID nicht durch eine Task-, Versuchs- oder Session-ID.
+
+Das SDK erhält die empfangene nichtleere Zeichenfolge exakt. Fehlende, null, leere oder nicht als String empfangene Identitätswerte ergeben `null`. Verwenden Sie dann einen anwendungseigenen Geschäftsschlüssel. Das [Service-Key-Beispiel des SDKs](https://php.durable-workflow.com/build/workflows-activities/#inspect-retry-budget-and-the-owning-workflow) zeigt diesen Fallback; die [Eigenschaftsreferenz](https://php.durable-workflow.com/api/classes/DurableWorkflow-Worker-ActivityContext.html#property_activityExecutionId) definiert die öffentliche API. Begrenzen Sie Schlüssel auf Anwendung und Effekt, verwenden Sie verschiedene Schlüssel für verschiedene Effekte und gleichen Sie ungewisse Ergebnisse mit dem Ziel ab. Identität ist öffentliche Metadateninformation, keine Claim-Autorität oder Garantie genau einmal ausgeführter externer Effekte.
+
+Gewöhnliche und kooperativ überwachte Remote-Callbacks lesen das tatsächliche Claim-Feld. Session-Callbacks liefern es nur, wenn ihr Claim es enthält. Inline-lokale und Server-freie Callbacks ohne Server-Zulassung haben `null` als Ausführungsidentität, auch bei bekannten Eltern-Workflow-/Run-IDs. Historischer Prepared-local-Quellcode reicht seine validierte Zulassungs-ID weiter; dieses Quellverhalten belegt keine native Prepared-local-Unterstützung. Dies sind Quell-/Datenflussgrenzen, keine installierten Retry-Beobachtungen für jeden Ausführungsmodus.
+
 ## Aktivitäts-Heartbeats {#activity-heartbeats}
 
 Rufen Sie bei entfernten Aktivitäten `ActivityContext::heartbeat($details)` während begrenzter Aktivitätsarbeit deutlich vor dem konfigurierten Heartbeat-Zeitlimit auf. Das erste Zeitfenster beginnt mit der Beanspruchung durch die Laufzeit, nicht beim Empfang der Aufgabe in PHP. Anfragelatenz, Pausen und Transportwiederholungen verbrauchen dieses Zeitfenster. Beachten Sie die [Taktempfehlungen](../features/heartbeats.md#heartbeat-cadence-and-receipts).

i18n/de/source-hashes.json

@@ -14,7 +14,7 @@
   "configuration/publishing-config.md": "c757acd749c0d2696a6e19484249c9298dd15970ce0cf2ae0e6d2dfd82c8b6d6",
   "constraints/activity-constraints.md": "5a953d0e95e750b6c02d1c72b72199fb3ff4687540cebc56aa3b216cf667bb05",
   "constraints/constraints-summary.md": "fb48d01502388fc3821eae3790f470ed29cec91545420450f96fc77b84e589f1",
-  "constraints/execution-guarantees.md": "9e53840c400b14186587714b32dd54dd780aaa68f2a132fc1e4e4d1f3eeadd0b",
+  "constraints/execution-guarantees.md": "c5c9dbb3be4a10d115f308bd5b591d56a2a91159228808918d5c0edcf4c88a72",
   "constraints/idempotent-vs-deterministic.md": "f7396f01a4111ce187e751b009c1efb96f5538e8a602006eed24f7b1d8f44adf",
   "constraints/overview.md": "fd6c842c6c22d6f0df37a52de15ca74b34664f5ecd78af0c08b1e0cdb9a2be1f",
   "constraints/structural-limits.md": "5c7b7f6c86c5ca547eb3f200400ceab3b589f32d83866914f44e3a5a7d81e964",
@@ -80,7 +80,7 @@
   "polyglot/invocable-carrier.md": "00bcf878b7bac1be90718b73f0a626a99cf0e111414ac0854c6491d159798c01",
   "polyglot/invocable-php-handler.md": "3b678eb1d69fe32dfcfdc05d36b33e49e01b79d7216bd784f6a61a6f1c3c3a13",
   "polyglot/namespace-auth-workers.md": "fee5e52a18637814f60aeb419f7ebc99ce4927089dfb748073697a8218bd47bb",
-  "polyglot/php.md": "7ea69bc61b6a1b8ff9acd141b504128fd6b83ca9522076fe9d971d24a1f70213",
+  "polyglot/php.md": "2c03a2b9f40167f3ce075677602840b259f0250e410e9780aecb08d41bcc27d9",
   "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989",
   "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959",
   "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c",

i18n/es/docusaurus-plugin-content-docs/current/constraints/execution-guarantees.md

@@ -157,6 +157,8 @@ metadato público, no autoridad del claim, y no hace que un efecto externo ocurr
 exactamente una vez. Mantenga la idempotencia del destino, claves distintas
 para efectos diferentes y reconciliación de resultados.
 
+Las actividades PHP en modo servicio exponen `ActivityContext::activityExecutionId`, de solo lectura y nullable, del claim recibido, junto con `workflowId` y `runId` del workflow y ejecución propietarios. Mantenga el ID de ejecución lógica entre reintentos. La identidad ausente permanece `null`; un ID de tarea, intento o sesión no es una alternativa. La [guía de identidad PHP](../polyglot/php.md#activity-identity) enlaza el ejemplo de clave de servicio del SDK y define los casos ausente, sesión, prepared-local histórico, inline-local y sin Server. Estos accesores son metadatos públicos, no autoridad del claim. Los efectos externos siguen necesitando idempotencia en el destino, claves diferentes para efectos diferentes y reconciliación de resultados.
+
 ## Qué debe ser idempotente en tu aplicación {#what-developers-must-make-idempotent}
 
 No necesitas hacer idempotente la reproducción del workflow. El framework se

i18n/es/docusaurus-plugin-content-docs/current/polyglot/php.md

@@ -164,6 +164,14 @@ Procese las señales de forma idempotente para el evento de negocio. Un ID de so
 
 Consulte los [ejemplos completos del último intento y de señales a la ejecución propia](https://php.durable-workflow.com/build/workflows-activities/) en la guía del SDK de PHP.
 
+## Identidad lógica de ejecución de actividad {#activity-identity}
+
+PHP SDK **3.10.0 o posterior** expone `ActivityContext::activityExecutionId`, de solo lectura y nullable, recibido con el claim de actividad. Identifica la actividad lógica entre reintentos. `workflowId` y `runId` identifican la instancia y ejecución del workflow propietario; `activityAttemptId` identifica un intento. No sustituya una identidad lógica ausente por un ID de tarea, intento o sesión.
+
+El SDK conserva exactamente la cadena no vacía recibida. Valores omitidos, null, vacíos o no textuales producen `null`. Use una clave de negocio propia de la aplicación cuando no esté disponible. El [ejemplo de clave de servicio del SDK](https://php.durable-workflow.com/build/workflows-activities/#inspect-retry-budget-and-the-owning-workflow) muestra esa alternativa; la [referencia de la propiedad](https://php.durable-workflow.com/api/classes/DurableWorkflow-Worker-ActivityContext.html#property_activityExecutionId) define la API pública. Delimite las claves por aplicación y efecto, use claves distintas para efectos distintos y reconcilie resultados inciertos con el destino. La identidad es metadato público, no autoridad del claim ni garantía de efectos externos exactamente una vez.
+
+Los callbacks remotos ordinarios y supervisados cooperativamente leen el campo real del claim. Los callbacks de sesión solo lo exponen cuando su claim lo incluye. Los callbacks locales inline y sin Server que carecen de admisión del Server tienen identidad de ejecución `null`, aunque conozcan los IDs del workflow/run padre. El código histórico prepared-local transmite su ID de admisión validado; ese comportamiento de código no acredita soporte prepared-local nativo. Son límites de código/flujo de datos, no observaciones instaladas de reintentos para todos los modos.
+
 ## Heartbeats de actividad {#activity-heartbeats}
 
 Para actividades remotas, llame a `ActivityContext::heartbeat($details)` durante trabajo de actividad acotado, con suficiente antelación al tiempo de espera de heartbeat. La primera ventana empieza al reclamar la actividad en el entorno de ejecución, no cuando PHP recibe la tarea. La latencia de las peticiones, las pausas y los reintentos de transporte consumen esa ventana. Siga las [recomendaciones de cadencia](../features/heartbeats.md#heartbeat-cadence-and-receipts).

i18n/es/source-hashes.json

@@ -14,7 +14,7 @@
   "configuration/publishing-config.md": "c757acd749c0d2696a6e19484249c9298dd15970ce0cf2ae0e6d2dfd82c8b6d6",
   "constraints/activity-constraints.md": "5a953d0e95e750b6c02d1c72b72199fb3ff4687540cebc56aa3b216cf667bb05",
   "constraints/constraints-summary.md": "fb48d01502388fc3821eae3790f470ed29cec91545420450f96fc77b84e589f1",
-  "constraints/execution-guarantees.md": "9e53840c400b14186587714b32dd54dd780aaa68f2a132fc1e4e4d1f3eeadd0b",
+  "constraints/execution-guarantees.md": "c5c9dbb3be4a10d115f308bd5b591d56a2a91159228808918d5c0edcf4c88a72",
   "constraints/idempotent-vs-deterministic.md": "f7396f01a4111ce187e751b009c1efb96f5538e8a602006eed24f7b1d8f44adf",
   "constraints/overview.md": "fd6c842c6c22d6f0df37a52de15ca74b34664f5ecd78af0c08b1e0cdb9a2be1f",
   "constraints/structural-limits.md": "5c7b7f6c86c5ca547eb3f200400ceab3b589f32d83866914f44e3a5a7d81e964",
@@ -80,7 +80,7 @@
   "polyglot/invocable-carrier.md": "00bcf878b7bac1be90718b73f0a626a99cf0e111414ac0854c6491d159798c01",
   "polyglot/invocable-php-handler.md": "3b678eb1d69fe32dfcfdc05d36b33e49e01b79d7216bd784f6a61a6f1c3c3a13",
   "polyglot/namespace-auth-workers.md": "fee5e52a18637814f60aeb419f7ebc99ce4927089dfb748073697a8218bd47bb",
-  "polyglot/php.md": "7ea69bc61b6a1b8ff9acd141b504128fd6b83ca9522076fe9d971d24a1f70213",
+  "polyglot/php.md": "2c03a2b9f40167f3ce075677602840b259f0250e410e9780aecb08d41bcc27d9",
   "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989",
   "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959",
   "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c",

i18n/fr/docusaurus-plugin-content-docs/current/constraints/execution-guarantees.md

@@ -128,6 +128,8 @@ une métadonnée publique, pas une autorité de claim, et ne garantit pas qu’u
 effet externe se produise exactement une fois. Conservez l’idempotence du destinataire, des
 clés distinctes pour des effets différents et la réconciliation des résultats.
 
+Les activités PHP en mode service exposent `ActivityContext::activityExecutionId`, nullable et en lecture seule, issu du claim reçu, avec `workflowId` et `runId` du workflow et de l’exécution propriétaires. Conservez l’ID logique d’exécution entre tentatives. L’identité absente reste `null` ; un ID de tâche, tentative ou session n’est pas un repli. Le [guide d’identité PHP](../polyglot/php.md#activity-identity) lie l’exemple de clé de service du SDK et définit les cas absent, session, prepared-local historique, inline-local et sans Server. Ces accesseurs sont des métadonnées publiques, pas une autorité de claim. Les effets externes nécessitent toujours idempotence à destination, clés distinctes pour des effets distincts et réconciliation des résultats.
+
 ## Effets que l’application doit rendre idempotents {#what-developers-must-make-idempotent}
 
 Vous n’avez pas besoin de rendre la relecture du workflow elle-même idempotente. Le framework gère la relecture en reconstruisant l’état depuis l’historique validé.

i18n/fr/docusaurus-plugin-content-docs/current/polyglot/php.md

@@ -169,6 +169,14 @@ Traitez les signaux de manière idempotente pour l’événement métier. Un ide
 
 Consultez les [exemples complets de dernière tentative et de signal à sa propre exécution](https://php.durable-workflow.com/build/workflows-activities/) dans le guide du SDK PHP.
 
+## Identité logique d’exécution d’activité {#activity-identity}
+
+PHP SDK **3.10.0 ou ultérieur** expose `ActivityContext::activityExecutionId`, nullable et en lecture seule, reçu avec le claim d’activité. Il identifie l’activité logique entre tentatives. `workflowId` et `runId` identifient l’instance et l’exécution du workflow propriétaire ; `activityAttemptId` identifie une tentative. Ne remplacez pas une identité logique absente par un ID de tâche, tentative ou session.
+
+Le SDK conserve exactement la chaîne non vide reçue. Une identité omise, null, vide ou qui n’est pas une chaîne produit `null`. Utilisez alors une clé métier appartenant à l’application. L’[exemple de clé de service du SDK](https://php.durable-workflow.com/build/workflows-activities/#inspect-retry-budget-and-the-owning-workflow) montre ce repli ; la [référence de la propriété](https://php.durable-workflow.com/api/classes/DurableWorkflow-Worker-ActivityContext.html#property_activityExecutionId) définit l’API publique. Délimitez les clés par application et effet, utilisez des clés distinctes pour des effets distincts et réconciliez les résultats incertains avec la destination. L’identité est une métadonnée publique, pas une autorité de claim ni une garantie d’effets externes exactement une fois.
+
+Les callbacks distants ordinaires et supervisés coopérativement lisent le champ réel du claim. Les callbacks de session ne l’exposent que si leur claim le contient. Les callbacks locaux inline et sans Server dépourvus d’admission Server ont une identité d’exécution `null`, même lorsque les IDs du workflow/run parent sont connus. Le code historique prepared-local transmet son ID d’admission validé ; ce comportement source n’établit pas un support prepared-local natif. Ce sont des limites de code/flux de données, pas des observations installées de nouvelles tentatives dans chaque mode.
+
 ## Heartbeats d’activité {#activity-heartbeats}
 
 Pour les activités distantes, appelez `ActivityContext::heartbeat($details)` pendant un travail d’activité borné, bien avant le délai de heartbeat configuré. La première fenêtre commence lorsque le moteur réclame l’activité, pas lorsque PHP reçoit la tâche. La latence des requêtes, les pauses et les nouvelles tentatives de transport consomment cette fenêtre. Suivez les [conseils de fréquence](../features/heartbeats.md#heartbeat-cadence-and-receipts).