From 0cbe104c6510d5c724fea26759015b930ac90583 Mon Sep 17 00:00:00 2001
From: Nick Anderson <nick@cmdln.org>
Date: Thu, 11 Jun 2026 12:54:16 -0500
Subject: [PATCH] Added timer_policy attribute to classes: promise reference

Documents the timer_policy attribute on classes: promises (CFE-4681),
which controls whether a persistent class restarts its timer when
rediscovered. The default is reset on master (3.28.0); the attribute is
also available on 3.24.5 and 3.27.2, where the default is absolute.

Ticket: CFE-4681
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../reference/promise-types/classes.markdown  | 47 +++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/content/reference/promise-types/classes.markdown b/content/reference/promise-types/classes.markdown
index f6f517e20..2b15ea42f 100644
--- a/content/reference/promise-types/classes.markdown
+++ b/content/reference/promise-types/classes.markdown
@@ -308,6 +308,53 @@ classes:
 
 **See also:** [`persistence` classes attribute][classes#persistence], [`persist_time` in classes body][Promise types#persist_time]
 
+### timer_policy
+
+**Description:** Determines whether a persistent class restarts its counter
+when rediscovered.
+
+When a [`persistence`][classes#persistence] timer is set, `timer_policy`
+controls what happens on later runs while the class is still defined (loaded
+from the persistent store):
+
+- `reset` re-evaluates the promise and restarts the timer, so the class keeps
+  persisting for as long as the policy keeps running and the expression stays
+  true.
+- `absolute` preserves the original expiry. While the class is already defined
+  the promise is skipped, so the class disappears once the original timer
+  elapses, regardless of how often the policy runs.
+
+This is the counterpart of `timer_policy` in the classes body, which has always
+defaulted to `reset`.
+
+**Type:** (menu option)
+
+**Allowed input range:** `absolute|reset`
+
+**Default value:** reset
+
+**Example:**
+
+```cf3
+bundle common setclasses
+{
+classes:
+
+  "cached_class"
+       expression => "any",
+      persistence => "120",
+     timer_policy => "reset";
+}
+```
+
+**History:**
+
+- Introduced in CFEngine 3.24.5, 3.27.2, 3.28.0.
+- The default changed from `reset` to `absolute` 3.28.0, preserving prior
+  default behavior in 3.24.5 and 3.27.2 and later patch releases in the series.
+
+**See also:** [`persistence` classes attribute][classes#persistence], [`timer_policy` in classes body][Promise types#timer_policy], [`persist_time` in classes body][Promise types#persist_time]
+
 ### not
 
 **Description:** Evaluate the negation of string expression in normal form