From 0d5a1607104aec598fe62de2dc480cbd61cde2d0 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Tue, 14 Apr 2026 17:32:53 +0000 Subject: [PATCH] docs(spec): clarify RetryPolicyConfig canonical field names (max_retries, backoff_factor, max_backoff) Issue #9396 identified a naming mismatch between the specification and some implementation code. This commit adds a dedicated clarification block to the RetryPolicyConfig section of docs/specification.md. Canonical field names (authoritative for all new integrations): - max_retries (was: max_attempts in some implementations) - backoff_factor (was: base_delay in some implementations) - max_backoff (was: max_delay in some implementations) Backward-compatible aliases (max_attempts, base_delay, max_delay) may be retained by existing implementations as read-through synonyms but must not appear in new public API surfaces or documentation. When both a canonical name and its alias are present, the canonical name wins. Relates to #9396 --- docs/specification.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/specification.md b/docs/specification.md index e16c06ad1..e537f6d48 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -31715,6 +31715,24 @@ The following annotated YAML provides an easier-to-read overview of the same sch | `end` | A terminal node that ends graph execution. | | `message_router` | Routes messages to different nodes based on message content or metadata. | +**`RetryPolicyConfig` — Canonical Field Names** + +The `retry_policy` object accepted by graph-route nodes (and any other context that takes a retry configuration) is governed by `RetryPolicyConfig`. The table below lists the **canonical** field names that all new implementations and API contracts must use. + +> **Note (Issue #9396 — naming alignment):** A historical mismatch exists between the spec and some older implementation code. The canonical names defined here are authoritative. Implementations may additionally expose the aliases listed in the *Backward-compatible alias* column to avoid breaking existing callers, but those aliases are deprecated and must not be used in new integrations. + +| Canonical field | Type | Default | Backward-compatible alias | Description | +|-----------------|------|---------|--------------------------|-------------| +| `max_retries` | integer | `3` | `max_attempts` | Maximum number of retry attempts before the node is considered failed. Range: 0–100. | +| `backoff_factor` | float | `1.0` | `base_delay` | Base multiplier (in seconds) applied to each successive retry interval. With exponential backoff the delay after attempt *n* is `backoff_factor × 2ⁿ⁻¹`. | +| `max_backoff` | float | `60.0` | `max_delay` | Upper bound (in seconds) on the computed retry delay. Prevents unbounded wait times regardless of the backoff calculation. | + +**Usage rules:** + +1. **Canonical names are authoritative.** All spec definitions, schema validation, and new API contracts must reference `max_retries`, `backoff_factor`, and `max_backoff`. +2. **Aliases are for backward compatibility only.** Implementations that already expose `max_attempts`, `base_delay`, or `max_delay` may keep those aliases, but must treat them as read-through synonyms for the canonical fields. Aliases must not appear in new public API surfaces or documentation. +3. **Conflict resolution.** If both a canonical name and its alias are supplied in the same configuration object, the canonical name takes precedence and the alias value is ignored. + #### Examples **Example 1: Minimal Chat Actor (Simple)** -- 2.52.0