The retired trigger families give up their table slots

Five slots and three handlers go: <BotShieldTrigger>, BotShieldTrigger,
<BotShieldFlagTrigger>, BotShieldFlagTrigger and
<BotShieldFeedbackTrigger>. bs_cmds[] goes from 96 directives to 91.

They existed to name the replacement, because Apache's own answer to an
unregistered section is "Invalid command, perhaps misspelled or defined
by a module not included", which sends a reader looking for a build or
LoadModule problem rather than a rename. Dropping them is a real trade
and not a tidy-up: the error gets worse.

What pays for it is that the audience is empty. This is the only
deployment, no config here has named those spellings since 2026-09-06,
and a table slot that exists for a reader who cannot exist is surface
with no consumer -- which is the same argument the families themselves
were retired on.

bs_flat_trigger_retired stays. It is generic over cmd->cmd->name and
still backs the one-line key=value form of BotShieldRule, a live
directive whose flat form is retired. A family that is gone entirely
and a live directive's old calling convention are different cases, and
only the first one loses its slot.

Both tests that covered these spellings assert configtest failure
rather than the message text, so they pass unchanged. Their docstrings
did argue for keeping the stubs, so those now say what the failure
looks like instead -- the refusal is the contract, the message was a
courtesy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: nkissebe

DESIGN.md

@@ -2226,14 +2226,24 @@ the linker on Apache symbols.
 
 ### Directive table
 
-`bs_cmds[]` registers 96 directives. Retired spellings fall into two
-groups, and which group a name is in decides what an old config sees.
-`BotShieldTrigger`, `BotShieldFlagTrigger` and
-`BotShieldFeedbackTrigger` still occupy table slots pointing at
-`bs_*_retired` handlers, so naming one fails with a message saying
-what to write instead. `BotShieldPathTrigger` has no such stub, so it
-fails with Apache's generic "Invalid command" and the operator gets no
-migration note.
+`bs_cmds[]` registers 91 directives. No retired *family* keeps a
+table slot any more: `BotShieldPathTrigger`, `BotShieldTrigger`,
+`BotShieldFlagTrigger` and `BotShieldFeedbackTrigger` all fail with
+Apache's generic "Invalid command, perhaps misspelled or defined by a
+module not included".
+
+The three trigger families held migration stubs until 2026-09-07, and
+dropping them was a deliberate trade rather than a tidy-up: the stub
+message named the replacement, and the generic error instead sends a
+reader looking for a build or LoadModule problem. What paid for it is
+that no config on this deployment -- the only one -- has named those
+spellings since 2026-09-06, so the audience for the message was empty
+while the slots were not.
+
+One retired spelling does keep a handler. `bs_flat_trigger_retired` is
+generic over `cmd->cmd->name` and still backs the one-line key=value
+form of `BotShieldRule`, which is a live directive whose flat form is
+retired -- a different case from a family that is gone entirely.
 The family groupings below summarize the surface — the canonical
 per-directive spec (handler, arg count, scope flags, help text) is
 the `bs_cmds[]` table at `src/botshield.c:213`.

src/botshield.c

@@ -143,60 +143,12 @@ int bs_bot_name_valid(const char *s)
  * carries the work; what differs between families is only which setter
  * receives the tokens it builds. */
 
-/* Registered rather than dropped so the error names the shape that
- * replaced it, instead of Apache's "Invalid command, perhaps
- * misspelled or defined by a module not included". */
-static const char *bs_open_trigger_retired(cmd_parms *cmd, void *dconf,
-                                          const char *arg)
-{
-    (void)dconf; (void)arg;
-    return apr_psprintf(cmd->pool,
-        "<BotShieldTrigger> is gone; write <BotShieldRule name> in the "
-        "same container. A rule declared inside <Location>, "
-        "<Directory> or <Files> needs no match key -- Apache has "
-        "already matched, and the container is the condition, which "
-        "is all this directive ever was.");
-}
-
-/* Registered rather than dropped so the error names the shape that
- * replaced it. */
-static const char *bs_open_flagtrigger_retired(cmd_parms *cmd,
-                                          void *dconf, const char *arg)
-{
-    (void)dconf; (void)arg;
-    return apr_psprintf(cmd->pool,
-        "<BotShieldFlagTrigger> is gone; write <BotShieldRule name> "
-        "with BotShieldFlagged <flag>. Its three actions are rule "
-        "actions: action=score is BotShieldScore, action=tier_floor "
-        "is BotShieldChallenge, action=block is BotShieldRespond. "
-        "`reset` has no equivalent -- rules settle by declaration "
-        "order.");
-}
-
 static const char *bs_open_feedback(cmd_parms *cmd, void *dconf,
                                           const char *arg)
 {
     return bs_section_trigger(cmd, dconf, arg, "BotShieldFeedback", bs_set_feedback);
 }
 
-/* The old tag. Registered rather than simply dropped so the error
- * names the replacement -- an operator who hits this has a working
- * config in front of them, and Apache's own "Invalid command,
- * perhaps misspelled or defined by a module not included" sends them
- * looking for a build problem instead. */
-static const char *bs_open_feedbacktrigger_retired(cmd_parms *cmd,
-                                          void *dconf, const char *arg)
-{
-    (void)dconf; (void)arg;
-    return apr_psprintf(cmd->pool,
-        "<BotShieldFeedbackTrigger> is gone; write <BotShieldFeedback> "
-        "and move the event into the block: the tag name is a label "
-        "now, like a rule's, and BotShieldEvent <name> is the "
-        "condition. It was never a trigger -- it runs after the "
-        "response is built and matches a signed header, not a "
-        "request.");
-}
-
 
 static const char *bs_open_match(cmd_parms *cmd, void *dconf,
                                           const char *arg)
@@ -561,14 +513,6 @@ static const command_rec bs_cmds[] = {
                  "graceful-shutdown save runs). Range when non-zero: "
                  "30..86400. Requires mod_watchdog to be loaded; otherwise "
                  "degrades to shutdown-only with a NOTICE."),
-    AP_INIT_RAW_ARGS("<BotShieldTrigger", bs_open_trigger_retired,
-                 NULL, RSRC_CONF | ACCESS_CONF,
-                 "Removed. Write <BotShieldRule> in the same "
-                 "container."),
-    AP_INIT_RAW_ARGS("<BotShieldFlagTrigger",
-                 bs_open_flagtrigger_retired, NULL, RSRC_CONF,
-                 "Removed. Write <BotShieldRule> with "
-                 "BotShieldFlagged."),
     AP_INIT_RAW_ARGS("<BotShieldFeedback", bs_open_feedback, NULL, RSRC_CONF,
                  "Open a BotShieldFeedback block: what a signed "
                  "application event means. Takes a label; "
@@ -577,10 +521,6 @@ static const command_rec bs_cmds[] = {
                  "remember about the client. Runs on the response "
                  "path, so it cannot direct the response -- flags are "
                  "what the next request reads."),
-    AP_INIT_RAW_ARGS("<BotShieldFeedbackTrigger",
-                 bs_open_feedbacktrigger_retired, NULL, RSRC_CONF,
-                 "Removed. Write <BotShieldFeedback> with "
-                 "BotShieldEvent inside it."),
     AP_INIT_RAW_ARGS("<BotShieldRule", bs_open_rule, NULL,
                  RSRC_CONF | ACCESS_CONF,
                  "Open a BotShieldRule block. Takes the rule name; every "
@@ -594,13 +534,6 @@ static const command_rec bs_cmds[] = {
                  "</BotShieldMatch>. Conditions only -- actions belong "
                  "on the rules that name the set. Define a set above "
                  "the rules that use it."),
-    AP_INIT_TAKE_ARGV("BotShieldTrigger", bs_flat_trigger_retired, NULL,
-                 RSRC_CONF | ACCESS_CONF,
-                 "Removed. Write <BotShieldRule name> in the same "
-                 "Apache container: a rule declared inside "
-                 "<Location>, <Directory>, <Files> or <If> needs no "
-                 "match key, because Apache has already matched and "
-                 "the container is the condition."),
     /* E1 — Allow family */
     AP_INIT_TAKE_ARGV("BotShieldClassify", bs_set_classify, NULL,
                  RSRC_CONF,
@@ -847,12 +780,6 @@ static const command_rec bs_cmds[] = {
                  "(e.g., dev+prod for one logical app, or api+www "
                  "subdomains). Strings up to 128 chars; hashed to a "
                  "32-bit ns_id and stored in each SHM slot."),
-    AP_INIT_TAKE_ARGV("BotShieldFlagTrigger",
-                 bs_flat_trigger_retired, NULL, RSRC_CONF,
-                 "Removed. A rule matching BotShieldFlagged does what "
-                 "this did: BotShieldScore for action=score, "
-                 "BotShieldChallenge for action=tier_floor, "
-                 "BotShieldRespond for action=block."),
     /* E4 — cookie triggers */
     AP_INIT_TAKE1("BotShieldSessionCookieName",
                  bs_set_session_cookie_name, NULL, RSRC_CONF,

tests/pytests/test_app_feedback.py

@@ -548,11 +548,12 @@ def test_app_feedback_can_mark_the_address(config_override, log_slice):
 def test_the_retired_tag_is_refused(config_override):
     """<BotShieldFeedbackTrigger> is gone.
 
-    Registered rather than simply dropped, so the error names the
-    replacement. Apache's own answer to an unregistered section is
+    It held a migration stub naming the replacement until 2026-09-07,
+    when the slot was dropped; the failure is now Apache's generic
     "Invalid command, perhaps misspelled or defined by a module not
-    included", which sends an operator looking for a build problem
-    instead of a rename.
+    included". What this asserts either way is that the old spelling
+    does not quietly work -- the message is a courtesy, the refusal is
+    the contract.
     """
     with pytest.raises(Exception) as exc_info:
         with config_override(

tests/pytests/test_triggers.py

@@ -541,6 +541,11 @@ def test_removed_flagtrigger_family_is_refused(config_override):
     the family added over that was its own vocabulary for the same
     actions and a `reset` keyword for a merge order rules settle by
     declaration.
+
+    The migration stub that named the replacement was dropped
+    2026-09-07, so this now fails with Apache's generic "Invalid
+    command" rather than a rename note. The assertion is unchanged:
+    what matters is that the spelling is refused, not how politely.
     """
     with pytest.raises(Exception) as exc_info:
         with config_override(