From fe82cf59d26b38ca4150e2f8be0d293b93a85c55 Mon Sep 17 00:00:00 2001
From: Juan Pablo Tosso <jptosso@gmail.com>
Date: Fri, 17 Apr 2026 22:53:00 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20add=20ADRs=20for=20structural=20v3.x=20?=
 =?UTF-8?q?changes=20(2023-05=20=E2=86=92=202026-04)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduce docs/adr/ with 54 MADR-3.0 records covering every structural
PR merged between v3.0.0 (2023-05-31) and v3.7.0 (2026-04-06) plus two
unreleased post-v3.7.0 changes on main. Bugfixes, dependency bumps,
chore/doc/test-only PRs are excluded.

Categories: Feature (17), Parity (23), Perf (10), Refactor (4).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/adr/0000-template.md                     |  55 ++++++++
 docs/adr/0001-response-args-collection.md     |  69 ++++++++++
 docs/adr/0002-secargumentslimit-directive.md  |  90 ++++++++++++
 docs/adr/0003-https-audit-log-writer.md       | 103 ++++++++++++++
 docs/adr/0004-matchedrule-log-method.md       |  94 +++++++++++++
 docs/adr/0005-auditlogformatter-interface.md  |  89 ++++++++++++
 docs/adr/0006-regex-ahocorasick-memoize.md    |  99 ++++++++++++++
 docs/adr/0007-uppercase-transformation.md     |  63 +++++++++
 docs/adr/0008-transaction-context.md          | 101 ++++++++++++++
 docs/adr/0009-structured-logging.md           |  64 +++++++++
 docs/adr/0010-raw-body-processor.md           |  81 +++++++++++
 docs/adr/0011-expose-expected-directives.md   |  63 +++++++++
 docs/adr/0012-secruleupdatetargetbytag.md     |  87 ++++++++++++
 .../adr/0013-tinygo-formatter-registration.md |  67 +++++++++
 .../0014-base64decodeext-transformation.md    |  80 +++++++++++
 docs/adr/0015-case-sensitive-maps.md          |  78 +++++++++++
 docs/adr/0016-case-sensitive-args.md          | 115 ++++++++++++++++
 docs/adr/0017-multipart-strict-error.md       |  73 ++++++++++
 docs/adr/0018-ocsf-audit-log.md               | 111 +++++++++++++++
 docs/adr/0019-unsafe-stringdata-refactor.md   |  70 ++++++++++
 docs/adr/0020-secruleupdateactionbyid.md      |  73 ++++++++++
 docs/adr/0021-square-brackets-in-variables.md |  66 +++++++++
 docs/adr/0022-time-variables.md               | 118 ++++++++++++++++
 docs/adr/0023-base64encode-transformation.md  |  64 +++++++++
 docs/adr/0024-hexdecode-transformation.md     |  69 ++++++++++
 .../0025-selectors-on-names-collections.md    |  83 ++++++++++++
 docs/adr/0026-pmf-short-alias.md              |  60 ++++++++
 docs/adr/0027-ipmatchf-short-alias.md         |  64 +++++++++
 docs/adr/0028-syslog-audit-log-writer.md      |  77 +++++++++++
 docs/adr/0029-json-schema-improvements.md     |  95 +++++++++++++
 docs/adr/0030-secrequestbodyjsondepthlimit.md |  95 +++++++++++++
 docs/adr/0031-multipart-unexpected-eof.md     |  95 +++++++++++++
 docs/adr/0032-ctl-auditlogparts-plus-minus.md |  91 +++++++++++++
 docs/adr/0033-strmatch-operator.md            |  83 ++++++++++++
 docs/adr/0034-rule-observer-callback.md       |  96 +++++++++++++
 docs/adr/0035-wafwithrules-interface.md       | 113 ++++++++++++++++
 docs/adr/0036-remove-root-experimental-dep.md |  64 +++++++++
 .../0037-ctl-whole-collection-exclusion.md    |  72 ++++++++++
 docs/adr/0038-map-for-ruleremovebyid.md       |  71 ++++++++++
 docs/adr/0039-bulk-allocate-matchdata.md      |  64 +++++++++
 docs/adr/0040-crslang-antlr4-buildtag.md      |  61 +++++++++
 docs/adr/0041-ruleremovebyid-range-storage.md |  69 ++++++++++
 docs/adr/0042-regex-memoize-default-on.md     |  90 ++++++++++++
 docs/adr/0043-waf-close-per-owner-memoize.md  |  85 ++++++++++++
 docs/adr/0044-prefix-transformation-cache.md  |  64 +++++++++
 .../0045-findstringsubmatchindex-noalloc.md   |  65 +++++++++
 docs/adr/0046-secuploadkeepfiles-directive.md |  86 ++++++++++++
 .../adr/0047-regex-in-ctl-ruleremovetarget.md | 106 +++++++++++++++
 docs/adr/0048-ndjson-body-processor.md        |  81 +++++++++++
 docs/adr/0049-rx-literal-prefilter.md         |  92 +++++++++++++
 docs/adr/0050-secrxprefilter-directive.md     | 100 ++++++++++++++
 docs/adr/0051-audit-log-part-j.md             | 100 ++++++++++++++
 docs/adr/0052-ahocorasick-to-bitmap.md        |  96 +++++++++++++
 docs/adr/0053-pm-minlen-prefilter.md          |  82 +++++++++++
 docs/adr/0054-xml-unexpected-eof.md           |  61 +++++++++
 docs/adr/README.md                            | 128 ++++++++++++++++++
 56 files changed, 4631 insertions(+)
 create mode 100644 docs/adr/0000-template.md
 create mode 100644 docs/adr/0001-response-args-collection.md
 create mode 100644 docs/adr/0002-secargumentslimit-directive.md
 create mode 100644 docs/adr/0003-https-audit-log-writer.md
 create mode 100644 docs/adr/0004-matchedrule-log-method.md
 create mode 100644 docs/adr/0005-auditlogformatter-interface.md
 create mode 100644 docs/adr/0006-regex-ahocorasick-memoize.md
 create mode 100644 docs/adr/0007-uppercase-transformation.md
 create mode 100644 docs/adr/0008-transaction-context.md
 create mode 100644 docs/adr/0009-structured-logging.md
 create mode 100644 docs/adr/0010-raw-body-processor.md
 create mode 100644 docs/adr/0011-expose-expected-directives.md
 create mode 100644 docs/adr/0012-secruleupdatetargetbytag.md
 create mode 100644 docs/adr/0013-tinygo-formatter-registration.md
 create mode 100644 docs/adr/0014-base64decodeext-transformation.md
 create mode 100644 docs/adr/0015-case-sensitive-maps.md
 create mode 100644 docs/adr/0016-case-sensitive-args.md
 create mode 100644 docs/adr/0017-multipart-strict-error.md
 create mode 100644 docs/adr/0018-ocsf-audit-log.md
 create mode 100644 docs/adr/0019-unsafe-stringdata-refactor.md
 create mode 100644 docs/adr/0020-secruleupdateactionbyid.md
 create mode 100644 docs/adr/0021-square-brackets-in-variables.md
 create mode 100644 docs/adr/0022-time-variables.md
 create mode 100644 docs/adr/0023-base64encode-transformation.md
 create mode 100644 docs/adr/0024-hexdecode-transformation.md
 create mode 100644 docs/adr/0025-selectors-on-names-collections.md
 create mode 100644 docs/adr/0026-pmf-short-alias.md
 create mode 100644 docs/adr/0027-ipmatchf-short-alias.md
 create mode 100644 docs/adr/0028-syslog-audit-log-writer.md
 create mode 100644 docs/adr/0029-json-schema-improvements.md
 create mode 100644 docs/adr/0030-secrequestbodyjsondepthlimit.md
 create mode 100644 docs/adr/0031-multipart-unexpected-eof.md
 create mode 100644 docs/adr/0032-ctl-auditlogparts-plus-minus.md
 create mode 100644 docs/adr/0033-strmatch-operator.md
 create mode 100644 docs/adr/0034-rule-observer-callback.md
 create mode 100644 docs/adr/0035-wafwithrules-interface.md
 create mode 100644 docs/adr/0036-remove-root-experimental-dep.md
 create mode 100644 docs/adr/0037-ctl-whole-collection-exclusion.md
 create mode 100644 docs/adr/0038-map-for-ruleremovebyid.md
 create mode 100644 docs/adr/0039-bulk-allocate-matchdata.md
 create mode 100644 docs/adr/0040-crslang-antlr4-buildtag.md
 create mode 100644 docs/adr/0041-ruleremovebyid-range-storage.md
 create mode 100644 docs/adr/0042-regex-memoize-default-on.md
 create mode 100644 docs/adr/0043-waf-close-per-owner-memoize.md
 create mode 100644 docs/adr/0044-prefix-transformation-cache.md
 create mode 100644 docs/adr/0045-findstringsubmatchindex-noalloc.md
 create mode 100644 docs/adr/0046-secuploadkeepfiles-directive.md
 create mode 100644 docs/adr/0047-regex-in-ctl-ruleremovetarget.md
 create mode 100644 docs/adr/0048-ndjson-body-processor.md
 create mode 100644 docs/adr/0049-rx-literal-prefilter.md
 create mode 100644 docs/adr/0050-secrxprefilter-directive.md
 create mode 100644 docs/adr/0051-audit-log-part-j.md
 create mode 100644 docs/adr/0052-ahocorasick-to-bitmap.md
 create mode 100644 docs/adr/0053-pm-minlen-prefilter.md
 create mode 100644 docs/adr/0054-xml-unexpected-eof.md
 create mode 100644 docs/adr/README.md

diff --git a/docs/adr/0000-template.md b/docs/adr/0000-template.md
new file mode 100644
index 000000000..34612b3e0
--- /dev/null
+++ b/docs/adr/0000-template.md
@@ -0,0 +1,55 @@
+# ADR-NNNN: <short decision title>
+
+- **Status:** accepted
+- **Date:** YYYY-MM-DD (PR merge date)
+- **Version:** vX.Y.Z
+- **PR:** [#NNNN](https://github.com/corazawaf/coraza/pull/NNNN)
+- **Issue(s):** [#MMMM](https://github.com/corazawaf/coraza/issues/MMMM) — or "No linked issue"
+- **Deciders:** @author, @reviewer1, @reviewer2
+- **Category:** Feature | Parity | Perf | Refactor
+
+## Context and Problem
+
+Why the change was needed. Quote from the issue or PR body where possible.
+
+## Decision Drivers
+
+- driver 1
+- driver 2
+
+## Considered Options
+
+- option A
+- option B
+
+## Decision Outcome
+
+Chosen: **<option>**, because <reason grounded in PR discussion>.
+
+## Technical Discussion
+
+Summary of substantive thread. Every ADR must contain **either** at least one quoted
+comment with a direct permalink **or** the sentence "No substantive technical
+discussion recorded on the PR or issue thread." Do not fabricate discussion.
+
+Representative quote(s):
+
+> "<quote>" — @user ([comment](https://github.com/corazawaf/coraza/pull/NNNN#issuecomment-XXXXX))
+
+## Participants
+
+- @author — author
+- @reviewer1 — review
+- @reviewer2 — review comments
+- @commenter3 — issue thread
+
+## Consequences
+
+- **Positive:** …
+- **Negative / follow-up:** …
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/NNNN
+- Issue: https://github.com/corazawaf/coraza/issues/MMMM
+- Related ADRs: ADR-XXXX
diff --git a/docs/adr/0001-response-args-collection.md b/docs/adr/0001-response-args-collection.md
new file mode 100644
index 000000000..e59d80255
--- /dev/null
+++ b/docs/adr/0001-response-args-collection.md
@@ -0,0 +1,69 @@
+# ADR-0001: Enable RESPONSE_ARGS collection
+
+- **Status:** accepted
+- **Date:** 2023-06-12
+- **Version:** v3.0.1
+- **PR:** [#811](https://github.com/corazawaf/coraza/pull/811)
+- **Issue(s):** No linked issue
+- **Deciders:** @jptosso, @M4tteoP, @fzipi
+- **Category:** Parity (ModSecurity parity)
+
+## Context and Problem
+
+ModSecurity exposes a `RESPONSE_ARGS` collection so rules can inspect arguments
+parsed from the response body (for example JSON response fields). Coraza v3.0.0
+had the scaffolding but the collection was not wired up end-to-end — there was
+no way to write response-phase argument matching rules.
+
+## Decision Drivers
+
+- Parity with ModSecurity behaviour for rules that inspect response bodies.
+- Symmetry with the existing `ARGS_GET`/`ARGS_POST` request-phase infrastructure.
+
+## Considered Options
+
+- Build a brand-new response-argument pipeline.
+- Reuse the existing request-side body processors and simply enable the
+  response-arg collection on the transaction.
+
+## Decision Outcome
+
+Chosen: **reuse the existing body processors** to populate a response-arg
+collection. The PR is minimal, surfacing the feature rather than introducing a
+new subsystem.
+
+## Technical Discussion
+
+The PR itself ships without a written description. Review feedback focused on
+housekeeping rather than design, and follow-up work was explicitly deferred.
+
+> "Can we move this TODO to a proper issue so someone might implement it?"
+> — @fzipi ([review comment](https://github.com/corazawaf/coraza/pull/811#discussion_r1226569095))
+
+> "There is a work in progress around it: …" — @M4tteoP, pointing at the
+> in-progress response-arg discussion on OWASP Slack
+> ([review comment](https://github.com/corazawaf/coraza/pull/811#discussion_r1227294607))
+
+No substantive architectural debate took place on the PR thread itself; the
+design was discussed out-of-band (OWASP Slack) and the code change was merged
+with two approvals.
+
+## Participants
+
+- @jptosso — author
+- @M4tteoP — review, Slack discussion pointer
+- @fzipi — review
+
+## Consequences
+
+- **Positive:** Response-phase rules can now match on parsed body arguments,
+  closing a compatibility gap with ModSecurity.
+- **Negative / follow-up:** Response-body argument parsing uses the same
+  processors as requests, so any parser limitations (JSON depth, etc.) apply
+  symmetrically. Later limits such as `SecArgumentsLimit` (ADR-0002) were added
+  to keep this surface bounded.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/811
+- Related ADRs: ADR-0002 (SecArgumentsLimit directive)
diff --git a/docs/adr/0002-secargumentslimit-directive.md b/docs/adr/0002-secargumentslimit-directive.md
new file mode 100644
index 000000000..8e742deff
--- /dev/null
+++ b/docs/adr/0002-secargumentslimit-directive.md
@@ -0,0 +1,90 @@
+# ADR-0002: `SecArgumentsLimit` directive
+
+- **Status:** accepted
+- **Date:** 2023-06-14
+- **Version:** v3.0.2
+- **PR:** [#812](https://github.com/corazawaf/coraza/pull/812)
+- **Issue(s):** No linked issue
+- **Deciders:** @potats0, @jptosso, @jcchavezs, @fzipi, @M4tteoP, @anuraaga, @airween, @theseion
+- **Category:** Parity (ModSecurity parity)
+
+## Context and Problem
+
+Coraza accepted unbounded numbers of parsed arguments, leaving it open to
+parameter-pollution and resource-exhaustion attacks. ModSecurity documents a
+`SecArgumentsLimit` directive (default 1000) for this; Coraza had none.
+
+## Decision Drivers
+
+- ModSecurity parity — the directive already exists in the reference
+  implementation.
+- Hard bound on argument count to protect against DoS.
+- Keep the cost of enforcement close to the public entrypoint rather than
+  duplicating it in every body processor.
+
+## Considered Options
+
+- Enforce the limit inside every body processor (JSON, urlencoded, XML, …).
+- Enforce the limit only on the public `addArguments` helper that feeds the
+  `ARGS_GET`/`ARGS_POST` collections, and leave body-processor-internal writes
+  for a follow-up.
+- Implement a new bounded collection type that self-enforces the cap.
+
+## Decision Outcome
+
+Chosen: **enforce on the public helper that wraps `ARGS_GET` / `ARGS_POST`**,
+default 1000, documented as a known gap for body-processor writes. A helper
+function was introduced so the check is not duplicated across the three writer
+call sites.
+
+## Technical Discussion
+
+Extensive review (30+ inline comments). Three themes drove the final shape.
+
+**1. Scope of enforcement.** @jptosso flagged early that body processors bypass
+the helper and therefore the limit:
+
+> "Internally coraza doesn't consume this functions, as we directly write into
+> de collections, so even with this implementation we would still get unlimited
+> arguments from body processors. It will only apply for ArgsGet and ArgsPath.
+> My idea would be to create a new collection that implements Map, and add a
+> validation." — @jptosso ([comment](https://github.com/corazawaf/coraza/pull/812#issuecomment-1588401916))
+
+@jcchavezs accepted the narrower scope to unblock the merge:
+
+> "I believe we can accept this PR as it is now and tackle the lack of internal
+> validation in a next PR."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/812#issuecomment-1589536399))
+
+**2. Default value.** @jptosso asked for the missing default of 1000 per
+ModSecurity docs; the PR was updated to match.
+
+**3. API shape.** A `Len()` method was added to the collection. @jptosso noted
+idiomatic Go:
+
+> "`Len() int` is the standard for Length in golang"
+> — @jptosso ([review comment](https://github.com/corazawaf/coraza/pull/812#discussion_r1227428689))
+
+`Length` was renamed to `Len` accordingly, and a helper was extracted so the
+check is not duplicated across the three writer call sites.
+
+## Participants
+
+- @potats0 — author
+- @jptosso — review, drove scope clarification and API naming
+- @jcchavezs — review, approved narrower scope, asked for `0` validation
+- @fzipi — review, suggestion edits on `Len()` call sites
+- @M4tteoP, @anuraaga, @airween, @theseion — review
+
+## Consequences
+
+- **Positive:** Public argument intake is bounded by default; `ARGS_GET` and
+  `ARGS_POST` cannot grow unboundedly from attacker-supplied inputs.
+- **Negative / follow-up:** Body-processor-internal writes are still unbounded
+  until a bounded `Map` collection lands. This was explicitly deferred.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/812
+- ModSecurity reference: https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#secargumentslimit
+- Related ADRs: ADR-0001 (RESPONSE_ARGS collection)
diff --git a/docs/adr/0003-https-audit-log-writer.md b/docs/adr/0003-https-audit-log-writer.md
new file mode 100644
index 000000000..db610075c
--- /dev/null
+++ b/docs/adr/0003-https-audit-log-writer.md
@@ -0,0 +1,103 @@
+# ADR-0003: HTTPS audit log writer
+
+- **Status:** accepted
+- **Date:** 2023-07-11
+- **Version:** v3.0.3
+- **PR:** [#826](https://github.com/corazawaf/coraza/pull/826)
+- **Issue(s):** Discussion [#813](https://github.com/corazawaf/coraza/issues/813)
+- **Deciders:** @jptosso, @jcchavezs, @anuraaga
+- **Category:** Feature
+
+## Context and Problem
+
+Prior to v3.0.3 Coraza could write audit logs to disk but had no pluggable way
+to ship them over HTTP(S) to a remote collector. ModSecurity had a similar
+feature via MLOGC; modern deployments want TLS-capable remote audit streaming
+without MLOGC-era constraints.
+
+## Decision Drivers
+
+- Enable cloud-native audit shipping (TLS, HTTP-based SIEM ingestion).
+- Intentionally drop MLOGC compatibility — it is a v2-era protocol.
+- Honour the formatter's MIME type so remote collectors can decode correctly.
+
+## Considered Options
+
+- Batched remote writes (accumulate N records, flush on timer).
+- Per-record HTTP writes, no batching, accept the loss of efficiency for v3.
+- Ship a full pluggable exporter subsystem now.
+
+## Decision Outcome
+
+Chosen: **per-record HTTP writes now; defer batching to v4** because Coraza
+v3 has no `WAF.Close()` method, so buffered records cannot be safely flushed
+on shutdown.
+
+> "Unfortunatelly we can't do bathing as we can't close the exporter (WAF does
+> not support close method and hence when terminating the APP the batched
+> requests will be lost). I think it is a good idea to add a Close method now
+> but not to force people to use it and maybe the exporter can listen to
+> termination signal"
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/826#issuecomment-1607190436))
+
+MIME-type awareness was introduced alongside this PR via the formatter
+interface refactor in [ADR-0005](0005-auditlogformatter-interface.md).
+
+## Technical Discussion
+
+Substantive review focused on lifecycle, transport hygiene, and future-proofing.
+
+**Lifecycle / Close:** the missing `WAF.Close()` blocked batching and shaped
+the whole design. The v3 compromise was "send one request per audit record,
+revisit in v4". That revisit eventually landed in v3.5.0 as
+[ADR-0043](0043-waf-close-per-owner-memoize.md).
+
+**Transport hygiene.** @jcchavezs flagged two concrete HTTP-client issues:
+
+> "I think any 2xx should be accepted. Restricting to OK feels mistaken as 201
+> and 204 are also valid status codes."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/826#discussion_r1241901929))
+
+> "Please drain the body before closing it using something like
+> `io.Copy(io.Discard, res.Body)` to be able to reuse the connection."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/826#discussion_r1241902417))
+
+Both were applied.
+
+**Content type.** @jcchavezs noted the missing Content-Type plumbing, which
+led directly to the formatter-interface refactor:
+
+> "One thing missing here is the content type support. We could add it to
+> formatters (yet not to the interface) and do interface assertion ok init and
+> record the value to be added to the requests."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/826#issuecomment-1630021852))
+
+Out-of-band decision-making is called out explicitly on the PR:
+
+> "Decisions we made during meeting
+> https://owasp.slack.com/archives/C02BXH135AT/p1687955362171029"
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/826#issuecomment-1612492704))
+
+The Slack thread itself is not visible to outside readers.
+
+## Participants
+
+- @jptosso — author
+- @jcchavezs — review (lifecycle, transport, content-type)
+- @anuraaga — review
+
+## Consequences
+
+- **Positive:** First-party HTTPS audit forwarding; MIME-aware so JSON,
+  native, and OCSF formatters can share the writer.
+- **Negative / follow-up:** No batching, no retry, no backoff — a record per
+  HTTP request. Higher-level reliability is left to the operator (SIEM-side
+  buffering). Batching awaits `WAF.Close()` (shipped in v3.5.0 —
+  [ADR-0043](0043-waf-close-per-owner-memoize.md)).
+- Drops MLOGC compatibility by design.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/826
+- Related ADRs: ADR-0005 (AuditLogFormatter interface), ADR-0028 (syslog
+  audit writer), ADR-0043 (`WAF.Close()`)
diff --git a/docs/adr/0004-matchedrule-log-method.md b/docs/adr/0004-matchedrule-log-method.md
new file mode 100644
index 000000000..0dc62278b
--- /dev/null
+++ b/docs/adr/0004-matchedrule-log-method.md
@@ -0,0 +1,94 @@
+# ADR-0004: Expose `MatchedRule.Log()` via optional interface
+
+- **Status:** accepted
+- **Date:** 2023-07-25
+- **Version:** v3.0.3
+- **PR:** [#848](https://github.com/corazawaf/coraza/pull/848)
+- **Issue(s):** [#839](https://github.com/corazawaf/coraza/issues/839); supersedes PR [#840](https://github.com/corazawaf/coraza/pull/840)
+- **Deciders:** @M4tteoP, @jcchavezs, @anuraaga, @jptosso
+- **Category:** Feature
+
+## Context and Problem
+
+Consumers wanted to filter matched rules to only those the rule author
+intended to audit-log. Users were approximating this via `Rule().Severity()`,
+which is not the correct signal — audit-log eligibility depends on the rule's
+`log`/`nolog` actions, not its severity. Audit logs were also coming up empty
+for some rules marked `log` because the information was not reachable.
+
+## Decision Drivers
+
+- Fix the empty-audit-log bug for `log`-marked rules (root cause).
+- Give consumers a reliable way to filter matches for logging.
+- Avoid breaking the public `types.MatchedRule` interface in v3.
+
+## Considered Options
+
+- **A.** Add `Log() bool` to the public `types.MatchedRule` interface
+  (breaking for anyone implementing the interface).
+- **B.** Ship a separate `RuleLogger` interface and let callers do a type
+  assertion (non-breaking).
+- **C.** Do not expose the method publicly at all; let callers cast to the
+  internal struct.
+
+## Decision Outcome
+
+Chosen: **option B** for v3 — a `RuleLogger` assertion-style interface — with
+a note that a cleaner v4 will promote the method onto the main interface.
+
+> "one easy way to avoid the breaking change is to not to add `Log` method to
+> the interface and do the assertion here with a `RuleLogger` interface … with
+> a comment so breaking change can be added in v4."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/848#discussion_r1269792282))
+
+@anuraaga initially pushed toward option C:
+
+> "Can we just cast to the struct? We do that a few places I think"
+> — @anuraaga ([review](https://github.com/corazawaf/coraza/pull/848#discussion_r1271236131))
+
+…and later hardened the position on keeping the public surface small:
+
+> "Let's remove the whole change in this file, it looks like the best it can
+> do is provide confusion rather than clarity. If there's no public method,
+> there's no public method"
+> — @anuraaga ([review](https://github.com/corazawaf/coraza/pull/848#discussion_r1271236246))
+
+The outcome followed @jcchavezs's compromise: the assertion interface shipped,
+and the v4-aligned interface promotion is tracked separately.
+
+## Technical Discussion
+
+Discussion revolved almost entirely around API surface hygiene in v3.
+
+@jcchavezs also flagged the risk of the workaround interface leaking into the
+long-term API:
+
+> "I'd rather not to expose this interface. Doing so we will be increasing the
+> API surface and also this interface is just a workaround and very likely to
+> be removed in v4. Also, go interface implementation is implicit so anyone
+> can declare an interface and do the same assertion."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/848#discussion_r1270918803))
+
+Two supersession links are on the record: PR #840 was replaced by this one,
+and issue #839 was the user-reported symptom.
+
+## Participants
+
+- @M4tteoP — author
+- @jcchavezs — review (API surface, v4 plan)
+- @anuraaga — review (structural casting alternative)
+- @joshi-mohit — original reporter (quoted in PR body)
+
+## Consequences
+
+- **Positive:** Audit-log filtering works correctly; `log` action is respected;
+  no v3 API break.
+- **Negative / follow-up:** Two ways exist to inspect the logging intent (the
+  optional interface, the internal struct). v4 is expected to clean this up by
+  promoting the method to `types.MatchedRule`.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/848
+- Issue: https://github.com/corazawaf/coraza/issues/839
+- Superseded PR: https://github.com/corazawaf/coraza/pull/840
diff --git a/docs/adr/0005-auditlogformatter-interface.md b/docs/adr/0005-auditlogformatter-interface.md
new file mode 100644
index 000000000..f3c06264c
--- /dev/null
+++ b/docs/adr/0005-auditlogformatter-interface.md
@@ -0,0 +1,89 @@
+# ADR-0005: `AuditLogFormatter` becomes an interface
+
+- **Status:** accepted
+- **Date:** 2023-08-06
+- **Version:** v3.0.3
+- **PR:** [#850](https://github.com/corazawaf/coraza/pull/850)
+- **Issue(s):** No linked issue (follows PR [#826](https://github.com/corazawaf/coraza/pull/826))
+- **Deciders:** @jptosso, @anuraaga, @jcchavezs
+- **Category:** Refactor (breaking within experimental plugin surface)
+
+## Context and Problem
+
+The HTTPS audit log writer ([ADR-0003](0003-https-audit-log-writer.md))
+needed to set a `Content-Type` per formatter. The existing formatter API was a
+bare function type:
+
+```go
+type AuditLogFormatter func(plugintypes.AuditLog) ([]byte, error)
+```
+
+A function cannot carry a MIME type. The formatter needed to become
+self-describing.
+
+## Decision Drivers
+
+- The HTTPS writer must know the formatter's content type.
+- The formatter plugin API is still experimental, so a breaking shape change
+  is acceptable now — cheaper than later.
+- Keep plugin implementation effort minimal (two methods per formatter).
+
+## Considered Options
+
+- Keep the function type and ship a parallel lookup table for MIME types.
+- Replace the function type with an interface carrying `Format()` + `MIME()`.
+- Attach metadata via a wrapper struct that still embeds the function.
+
+## Decision Outcome
+
+Chosen: **replace the function type with an interface.** `anuraaga` proposed
+it directly; `jcchavezs` accepted in one line.
+
+> "I think content type should be on the formatter, not https writer. Since
+> it's still experimental API, we can change formatter, how about making it an
+> actual type with `Format()` and `ContentType()` methods?"
+> — @anuraaga ([review](https://github.com/corazawaf/coraza/pull/850#discussion_r1274245227))
+
+> "Brilliant. Let's do it."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/850#discussion_r1275034260))
+
+The PR renamed `ContentType()` to `MIME()` during iteration. All built-in
+formatters (`nativeFormatter`, `jsonFormatter`, `legacyJSONFormatter`, and the
+test formatter) implement the interface. Compile-time assertions were added.
+
+## Technical Discussion
+
+@jcchavezs argued against permissive matching on the writer side:
+
+> "Is HasPrefix accurate? Can't we do direct comparison equality?"
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/850#discussion_r1274124841))
+
+@jptosso defended prefix matching for parameterised content types:
+
+> "Im most cases yes, but at some point it would be right to use
+> `application/json;encoding=utf-8`, like the automatic mime detection does"
+> — @jptosso ([review](https://github.com/corazawaf/coraza/pull/850#discussion_r1274134624))
+
+Prefix matching on MIME was kept; strict equality would have misfired on
+parameterised content types.
+
+## Participants
+
+- @jptosso — author
+- @anuraaga — review (proposed the interface shape)
+- @jcchavezs — review (many formatter conformance suggestions)
+
+## Consequences
+
+- **Positive:** Formatters are self-describing for MIME type; new transport
+  writers (HTTPS now, syslog later — [ADR-0028](0028-syslog-audit-log-writer.md))
+  can decide framing from the formatter alone.
+- **Negative:** One-time breaking change for out-of-tree formatter plugins —
+  they must grow a `MIME()` method. Acceptable because the plugin API is
+  declared experimental.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/850
+- Related ADRs: ADR-0003 (HTTPS audit log writer), ADR-0028 (syslog audit
+  writer), ADR-0018 (OCSF audit log format)
diff --git a/docs/adr/0006-regex-ahocorasick-memoize.md b/docs/adr/0006-regex-ahocorasick-memoize.md
new file mode 100644
index 000000000..48719f583
--- /dev/null
+++ b/docs/adr/0006-regex-ahocorasick-memoize.md
@@ -0,0 +1,99 @@
+# ADR-0006: Memoize cache for regexes and Aho-Corasick tables
+
+- **Status:** accepted
+- **Date:** 2023-08-06
+- **Version:** v3.0.3 (opt-in, behind `coraza.memoize_builders` build tag)
+- **PR:** [#836](https://github.com/corazawaf/coraza/pull/836)
+- **Issue(s):** [coraza-caddy#76](https://github.com/corazawaf/coraza-caddy/issues/76)
+- **Deciders:** @jcchavezs, @anuraaga, @jptosso, @M4tteoP
+- **Category:** Perf
+
+## Context and Problem
+
+Every WAF instance compiled every regex and Aho-Corasick table afresh. When
+the same ruleset is mounted into many WAFs (the Caddy connector pattern
+reported in coraza-caddy#76), the same regular expressions get compiled
+hundreds of times, wasting CPU at boot and RSS forever after.
+
+## Decision Drivers
+
+- Dramatically reduce memory / compile-time in multi-WAF deployments.
+- Stay opt-in so embedders that instantiate one WAF per process see no
+  behaviour change.
+- Avoid adding a `Close()` method to the `WAF` interface in v3 — adding one
+  would be a break.
+
+## Considered Options
+
+- Per-WAF cache.
+- Process-global cache, opt-in via build tag, exposed via `experimental`.
+- Add `WAF.Close()` now and bind the cache to the WAF lifetime.
+
+## Decision Outcome
+
+Chosen: **process-global cache, opt-in via build tag, exposed via
+`experimental`**, because the cache is inherently global (many WAFs share one
+process) and adding `WAF.Close()` was considered too large an API move for v3.
+The global `Close()` helper lives in `experimental` so anyone worried about
+leaks can clear on reload.
+
+> "We should include a flush or reset function so we can delete everything
+> after a web server reload. That function must be exported. I would include
+> it in `experimental/coraza`"
+> — @jptosso ([comment](https://github.com/corazawaf/coraza/pull/836#issuecomment-1622448598))
+
+> "Waf close is not coming in v3 as we cannot break the api, we should just
+> export all helpers in experimental until we can merge them. But closing
+> cache is different, as this is global and no per-WAF"
+> — @jptosso ([comment](https://github.com/corazawaf/coraza/pull/836#issuecomment-1622462418))
+
+@anuraaga agreed per-WAF close would not help here:
+
+> "For this PR though, I don't see how a WAF close method would help though
+> since IIUC the cache is global, not per waf. Having a global method in
+> experimental for now seems ok."
+> — @anuraaga ([comment](https://github.com/corazawaf/coraza/pull/836#issuecomment-1622687655))
+
+## Technical Discussion
+
+@anuraaga pushed on the concurrency primitive:
+
+> "This is ok but this file looks like an obvious mutex guarded map, not sure
+> it's worth referencing anything. Anyways it looks like a `sync.Map` should
+> be much faster for this, it's docs specifically mention the write once read
+> many case of a cache"
+> — @anuraaga ([review](https://github.com/corazawaf/coraza/pull/836#discussion_r1253758317))
+
+Error-handling philosophy briefly debated — @jptosso objected to panics,
+@jcchavezs chose to match `MustCompile`:
+
+> "Agree, however this should be fixed in `main`, I am just reproducing the
+> `MustCompile` behaviour."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/836#discussion_r1269182547))
+
+The cache was shipped as opt-in (build tag) in v3.0.3, later became the default
+in v3.5.0 once per-WAF tracking was available
+([ADR-0042](0042-regex-memoize-default-on.md),
+[ADR-0043](0043-waf-close-per-owner-memoize.md)).
+
+## Participants
+
+- @jcchavezs — author
+- @anuraaga — review (sync.Map suggestion, lifecycle sanity check)
+- @jptosso — review (drove the "global + experimental reset" design)
+- @M4tteoP — review (docs/readme nit)
+
+## Consequences
+
+- **Positive:** Large multi-WAF deployments (Caddy, proxy-wasm ambient
+  authorities) drop boot-time compile cost dramatically.
+- **Negative / follow-up:** The global cache is process-lifetime — embedders
+  reloading rulesets in-place must call the experimental reset. A cleaner
+  per-WAF lifecycle awaits `WAF.Close()` (ADR-0043) and the default-on
+  decision (ADR-0042).
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/836
+- Related ADRs: ADR-0042 (memoize default on), ADR-0043 (`WAF.Close()`)
+- Upstream motivating issue: https://github.com/corazawaf/coraza-caddy/issues/76
diff --git a/docs/adr/0007-uppercase-transformation.md b/docs/adr/0007-uppercase-transformation.md
new file mode 100644
index 000000000..9bd41ea60
--- /dev/null
+++ b/docs/adr/0007-uppercase-transformation.md
@@ -0,0 +1,63 @@
+# ADR-0007: `uppercase` transformation
+
+- **Status:** accepted
+- **Date:** 2023-12-18
+- **Version:** v3.1.0
+- **PR:** [#935](https://github.com/corazawaf/coraza/pull/935)
+- **Issue(s):** No linked issue
+- **Deciders:** @blotus, @fzipi, @jptosso
+- **Category:** Parity (closes documented-but-missing transformation)
+
+## Context and Problem
+
+Coraza's public documentation listed an `uppercase` transformation, but the
+transformation was never actually implemented — rules relying on it silently
+did nothing. A documentation/implementation drift bug that is, strictly, also
+a tiny feature addition.
+
+## Decision Drivers
+
+- Close the documented-but-missing gap.
+- Mirror `lowercase`, which already existed, including its test data layout.
+
+## Considered Options
+
+- Leave the docs in place and drop `uppercase`.
+- Implement the transformation and align test layout with `lowercase`.
+
+## Decision Outcome
+
+Chosen: **implement to match the documented behaviour**. Test data added in
+the standard `internal/transformations/testdata/` JSON format per reviewer
+request.
+
+## Technical Discussion
+
+The review was terse. The only substantive request concerned test-suite
+consistency:
+
+> "LGTM, but to keep testing consistency, can you also add the tests to
+> `internal/transformations/testadata`?"
+> — @jptosso ([comment](https://github.com/corazawaf/coraza/pull/935#issuecomment-1849541214))
+
+> "Thanks for your contribution! LGTM. Unless @anuraaga has other opinions,
+> it's good to merge." — @fzipi
+> ([comment](https://github.com/corazawaf/coraza/pull/935#issuecomment-1847219766))
+
+No architectural debate.
+
+## Participants
+
+- @blotus — author
+- @fzipi — review / approval
+- @jptosso — review (test layout)
+
+## Consequences
+
+- **Positive:** The `uppercase` transformation now behaves as documented;
+  rulesets that used it start working as intended.
+- **Negative / follow-up:** None of note.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/935
diff --git a/docs/adr/0008-transaction-context.md b/docs/adr/0008-transaction-context.md
new file mode 100644
index 000000000..0c3af876a
--- /dev/null
+++ b/docs/adr/0008-transaction-context.md
@@ -0,0 +1,101 @@
+# ADR-0008: Attach `context.Context` to transactions
+
+- **Status:** accepted
+- **Date:** 2024-01-31
+- **Version:** v3.1.0
+- **PR:** [#963](https://github.com/corazawaf/coraza/pull/963)
+- **Issue(s):** [#919](https://github.com/corazawaf/coraza/issues/919)
+- **Deciders:** @jcchavezs, @anuraaga, @MrWako
+- **Category:** Feature
+
+## Context and Problem
+
+Embedders wanted to correlate Coraza log output with the upstream request
+context — for distributed tracing, log-injection, etc. Without access to
+`context.Context` from inside rule matches, there was no clean way to pass a
+trace ID through to the audit-log consumer.
+
+## Decision Drivers
+
+- Let consumers access a `context.Context` from a `MatchedRule` to correlate
+  WAF logs with surrounding request traces.
+- Avoid breaking the v3 `types.RuleMatch` interface in a minor release.
+- Stay consistent with the existing `WAF` config style.
+
+## Considered Options
+
+- Add `Context() context.Context` directly to the public `types.RuleMatch`
+  interface.
+- Expose a new `experimental.WAF` / `Contexter` optional interface and let
+  callers assert to it.
+- Introduce a new functional option vs a config-object method for transaction
+  construction.
+
+## Decision Outcome
+
+Chosen: **optional `Contexter` assertion + a new `NewTransactionWithContext`
+entrypoint** with a config-object style consistent with the rest of the WAF
+API.
+
+> "Not sure about it. I'd rather to expose experimental features over exposing
+> a new experimental API (composed of many features). Unfortunately the way
+> to expose experimental features is to create a new interface but that is
+> much simpler than saying 'the experimental WAF'"
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/963#discussion_r1467953170))
+
+@anuraaga asked to follow the config-object style already used by the WAF
+constructor — the final shape complies:
+
+> "We use a config object instead of functional options for waf maybe good to
+> be consistent with it."
+> — @anuraaga ([review](https://github.com/corazawaf/coraza/pull/963#discussion_r1467685179))
+
+> "I personally find two methods to be ok, lean towards consistency with the
+> waf config. If you're interested in changing that to options pattern as
+> well for a potential major then that'd be ok too"
+> — @anuraaga ([review](https://github.com/corazawaf/coraza/pull/963#discussion_r1470407485))
+
+## Technical Discussion
+
+User @MrWako validated the pattern end-to-end:
+
+> "I've just tested by pulling in master and adding the snippet above. Works
+> perfectly! Really good to be able to easily correlate the WAF logs with the
+> request traffic through the system"
+> — @MrWako ([comment](https://github.com/corazawaf/coraza/pull/963#issuecomment-1920910404))
+
+@jcchavezs documented the escape hatch for embedders:
+
+> "```go
+> type Contexter interface { Context() context.Context }
+> …
+> if ctxer, ok := mr.(Contexter); ok { ctx = ctxer.Context() }
+> ```"
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/963#issuecomment-1920789693))
+
+…and telegraphed the v4 plan:
+
+> "for this we will introduce a new method in the `types.RuleMatch` interface
+> which is a breaking change but I can guarantee *nobody* has an own
+> implementation of that so user facing it isn't a breaking change. So for v4
+> expect to remove the type casting as it will just work."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/963#issuecomment-1920919931))
+
+## Participants
+
+- @jcchavezs — author, drove the experimental-interface plan
+- @anuraaga — review (config-object consistency, seal-internal suggestion)
+- @MrWako — issue reporter + downstream validator
+
+## Consequences
+
+- **Positive:** Matched rules can expose the request `context.Context` for
+  log/trace correlation without any v3 interface break.
+- **Negative / follow-up:** Two construction entrypoints
+  (`NewTransaction`, `NewTransactionWithContext`) coexist; v4 is expected to
+  fold the context into the canonical interface and drop the assertion.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/963
+- Issue: https://github.com/corazawaf/coraza/issues/919
diff --git a/docs/adr/0009-structured-logging.md b/docs/adr/0009-structured-logging.md
new file mode 100644
index 000000000..c00fc661b
--- /dev/null
+++ b/docs/adr/0009-structured-logging.md
@@ -0,0 +1,64 @@
+# ADR-0009: Structured `debuglog` facade
+
+- **Status:** accepted
+- **Date:** 2024-02-01
+- **Version:** v3.1.0
+- **PR:** [#971](https://github.com/corazawaf/coraza/pull/971)
+- **Issue(s):** No linked issue
+- **Deciders:** @jcchavezs, @anuraaga, @fzipi
+- **Category:** Refactor
+
+## Context and Problem
+
+Coraza's internal logging was an ad-hoc mix of formatted strings that made
+transaction logs hard to reason about. The author posted [a gist of a
+representative transaction log](https://gist.github.com/jcchavezs/ef0846bf457d2d6ab8b24bfce83860ce)
+as evidence that the output was not actionable for operators or for future
+structured-ingestion (SIEM/OTel-style).
+
+## Decision Drivers
+
+- Provide structured, attribute-style logging so downstream consumers can
+  parse or filter reliably.
+- Do not change the public logging interface consumers already wire up;
+  improve the call sites and internal facade.
+
+## Considered Options
+
+- Adopt `slog` outright and deprecate `debuglog`.
+- Keep `debuglog` as the public interface, rework call sites to emit
+  structured fields through it.
+
+## Decision Outcome
+
+Chosen: **keep `debuglog` as the public interface, rework call sites** so
+existing log-sink integrations (zerolog, zap, slog, …) continue to work
+while the content of the logs becomes structured and more consistent.
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR or issue thread. The
+change was merged with review approval and a Codecov report; no architectural
+debate was held publicly on this PR. The motivating evidence — a real-world
+log sample — is captured in the PR body as a linked gist, which stands in for
+the "why".
+
+## Participants
+
+- @jcchavezs — author
+- @anuraaga — review (approval only on this PR)
+- @fzipi — review (approval only on this PR)
+
+## Consequences
+
+- **Positive:** Logs have consistent structure; embedders can bind
+  attributes to their own log backend; future work to route to `slog`
+  becomes tractable.
+- **Negative / follow-up:** The facade is still hand-rolled rather than
+  `slog`. A future major (v4) may align with `log/slog` now that the Go
+  stdlib has it.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/971
+- Linked gist (evidence): https://gist.github.com/jcchavezs/ef0846bf457d2d6ab8b24bfce83860ce
diff --git a/docs/adr/0010-raw-body-processor.md b/docs/adr/0010-raw-body-processor.md
new file mode 100644
index 000000000..4083aa1b1
--- /dev/null
+++ b/docs/adr/0010-raw-body-processor.md
@@ -0,0 +1,81 @@
+# ADR-0010: `raw` request body processor
+
+- **Status:** accepted
+- **Date:** 2024-02-06
+- **Version:** v3.1.0
+- **PR:** [#983](https://github.com/corazawaf/coraza/pull/983)
+- **Issue(s):** Discussion [#938](https://github.com/corazawaf/coraza/issues/938)
+- **Deciders:** @blotus, @jcchavezs, @anuraaga
+- **Category:** Feature
+
+## Context and Problem
+
+The existing body processors (URLENCODED, MULTIPART, XML, JSON) all attempt to
+parse the body. For content types without a dedicated parser — or for rules
+that simply want to inspect bytes — Coraza had no way to skip parsing while
+still retaining the raw body for `REQUEST_BODY` rules.
+
+## Decision Drivers
+
+- Let rule authors opt *out* of structured parsing for specific content types
+  (e.g. `application/octet-stream`, vendor-proprietary payloads).
+- Provide a fallback processor that can be wired in via
+  `ctl:requestBodyProcessor=RAW`.
+- Minimise allocations — the processor is on the request hot path.
+
+## Considered Options
+
+- Make "no processor" implicit when no match is found.
+- Ship an explicit `RAW` processor that copies the body into a
+  `REQBODY_PROCESSOR=RAW`-marked transaction.
+
+## Decision Outcome
+
+Chosen: **explicit `RAW` processor**, switchable via
+`ctl:requestBodyProcessor=RAW`. The PR body shows the canonical CRS-style
+configuration that catches "anything not handled":
+
+```
+SecRule REQBODY_PROCESSOR "!@rx (?:URLENCODED|MULTIPART|XML|JSON)"
+  "id:105,phase:1,pass,nolog,noauditlog,ctl:requestBodyProcessor=RAW"
+```
+
+## Technical Discussion
+
+Discussion focused on allocation hygiene and interface cleanup. @anuraaga
+suggested a `strings.Builder` + `io.Copy` path for lower allocation pressure:
+
+> "`var buf strings.Builder; if _, err := io.Copy(&buf, reader); err != nil { … }`
+> — Generally can't be sure of eliding heap allocations but worth trying"
+> — @anuraaga ([review](https://github.com/corazawaf/coraza/pull/983#discussion_r1479118293))
+
+@jcchavezs pushed for `b.Len()` over a manual length tracker and unused
+parameter cleanup:
+
+> "Shall we use `b.Len` here? https://pkg.go.dev/strings#Builder.Len"
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/983#discussion_r1478399917))
+
+> "nit: you can remove the param names as they aren't used."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/983#discussion_r1478401110))
+
+Both were applied.
+
+## Participants
+
+- @blotus — author
+- @jcchavezs — review (API cleanup, `Len()`)
+- @anuraaga — review (allocation pattern)
+
+## Consequences
+
+- **Positive:** Rule authors can inspect unparsed bodies for any content
+  type; CRS-style fallback configuration becomes expressible.
+- **Negative / follow-up:** RAW bodies go through memory — large-body
+  protections (`SecRequestBodyLimit`) become the only guardrail.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/983
+- Motivating discussion: https://github.com/corazawaf/coraza/issues/938
+- Related ADRs: ADR-0030 (`SecRequestBodyJsonDepthLimit`), ADR-0048 (NDJSON
+  body processor)
diff --git a/docs/adr/0011-expose-expected-directives.md b/docs/adr/0011-expose-expected-directives.md
new file mode 100644
index 000000000..ed7541b03
--- /dev/null
+++ b/docs/adr/0011-expose-expected-directives.md
@@ -0,0 +1,63 @@
+# ADR-0011: Expose expected directives for e2e testing
+
+- **Status:** accepted
+- **Date:** 2024-03-08
+- **Version:** v3.2.0
+- **PR:** [#1012](https://github.com/corazawaf/coraza/pull/1012)
+- **Issue(s):** [#1006](https://github.com/corazawaf/coraza/issues/1006)
+- **Deciders:** @fionera, @M4tteoP
+- **Category:** Feature
+
+## Context and Problem
+
+Downstream connectors (proxy-wasm, Caddy, nginx, …) need a way to run
+end-to-end correctness tests against Coraza. To do that, they need to know
+which directives their e2e harness is expected to load. Previously, this
+value was implicit — each connector hard-coded its own copy of the expected
+directive set, drifting over time.
+
+## Decision Drivers
+
+- Single source of truth for the e2e directive set, so connectors can import
+  it instead of copying.
+- Keep the API narrow: this is a testing facility, not a production API.
+
+## Considered Options
+
+- Document the required directives in prose and let connectors duplicate.
+- Export a `Directives` constant from a dedicated `http/e2e` package for
+  connectors to import.
+
+## Decision Outcome
+
+Chosen: **export `Directives` from `http/e2e`** and link to it from doc
+comments.
+
+## Technical Discussion
+
+Review was limited to wording refinements — no architectural debate.
+
+> "I would be a bit more verbose considering that loading these directives is
+> a very needed step to run e2e and we need to make [sure] they actually take
+> a look at the file we are pointing them"
+> — @M4tteoP ([review](https://github.com/corazawaf/coraza/pull/1012#discussion_r1513149551))
+
+The final comment points readers directly at the source of truth:
+`http/e2e/e2e.go`'s `Directives` constant.
+
+## Participants
+
+- @fionera — author
+- @M4tteoP — review (comment wording)
+
+## Consequences
+
+- **Positive:** Connector e2e suites import `Directives` instead of
+  maintaining parallel copies; drift is removed.
+- **Negative / follow-up:** Adds a small `http/e2e` surface to the public
+  import path.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1012
+- Issue: https://github.com/corazawaf/coraza/issues/1006
diff --git a/docs/adr/0012-secruleupdatetargetbytag.md b/docs/adr/0012-secruleupdatetargetbytag.md
new file mode 100644
index 000000000..262791644
--- /dev/null
+++ b/docs/adr/0012-secruleupdatetargetbytag.md
@@ -0,0 +1,87 @@
+# ADR-0012: `SecRuleUpdateTargetByTag` + ID ranges for `SecRuleUpdateTargetByID`
+
+- **Status:** accepted
+- **Date:** 2024-03-28
+- **Version:** v3.2.0
+- **PR:** [#1020](https://github.com/corazawaf/coraza/pull/1020)
+- **Issue(s):** [#1018](https://github.com/corazawaf/coraza/issues/1018)
+- **Deciders:** @M4tteoP, @jcchavezs, @anuraaga
+- **Category:** Parity (ModSecurity / CRS parity)
+
+## Context and Problem
+
+CRS's false-positive-tuning workflow relies on `SecRuleUpdateTargetByTag`
+(update targets on every rule carrying a tag) and on `SecRuleUpdateTargetByID`
+with numeric ranges (e.g. `1000-2000`). Coraza shipped with the ById variant
+but not the ByTag one, and ById could not take ranges — blocking idiomatic
+CRS configuration.
+
+## Decision Drivers
+
+- Close an explicit CRS-compatibility gap flagged by the community.
+- Reuse existing list-walking code rather than introduce a new lookup
+  structure — the operation happens at bootstrap only.
+- Maintain pattern-parity with existing `ruleRemoveById` range handling.
+
+## Considered Options
+
+- Linear walk over the rule list, as existing code does.
+- Binary search over a sorted ID index.
+
+## Decision Outcome
+
+Chosen: **linear walk, matching the existing `rulegroup.go` pattern**. The
+operation fires once at boot so the O(n·m) cost is acceptable; a future
+binary search was explicitly deferred.
+
+> "Since this is happens on bootstrap, probably not worth to explore the
+> binary search ATM. I am happy to merge this."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1020#issuecomment-2022085264))
+
+@M4tteoP pointed at the existing precedent to justify the shape:
+
+> "This is something we are also already doing for other ID ranges: …
+> [`rulegroup.go#L83`](https://github.com/corazawaf/coraza/blob/d6a6959df1a3f0b481929fee62ea058c0a811e6b/internal/corazawaf/rulegroup.go#L83)
+> Just to address also that one if we come up with a better solution"
+> — @M4tteoP ([comment](https://github.com/corazawaf/coraza/pull/1020#issuecomment-2021610897))
+
+## Technical Discussion
+
+Code-level review asked for refactor extraction + defensive parsing:
+
+> "I'd extract this into a function and then reuse it in the else block
+> `start == end`"
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1020#discussion_r1531101959))
+
+> "What if start < 0?"
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1020#discussion_r1531103184))
+
+@M4tteoP added an explicit range-bound check with a better error message and
+tests:
+
+> "It was implicitly already handled because `idx` ends up being `0` and
+> failing Atoi. Still, I added an explicit check to provide a better error
+> message and tests."
+> — @M4tteoP ([review](https://github.com/corazawaf/coraza/pull/1020#discussion_r1537372801))
+
+## Participants
+
+- @M4tteoP — author
+- @jcchavezs — review (extraction, bounds, bootstrap-scope argument)
+- @anuraaga — review
+
+## Consequences
+
+- **Positive:** CRS tuning flows (tag-based exclusions, ID-range exclusions)
+  now work in Coraza without post-processing.
+- **Negative / follow-up:** Bootstrap cost grows linearly with ruleset size
+  and number of `SecRuleUpdateTarget*` directives; at CRS scale (~1000 rules)
+  this is not a bottleneck. Range compile-time work was later optimised in
+  ADR-0041.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1020
+- Issue: https://github.com/corazawaf/coraza/issues/1018
+- Related ADRs: ADR-0041 (`ruleRemoveById` range storage), ADR-0038
+  (`map` for `ruleRemoveByID`)
diff --git a/docs/adr/0013-tinygo-formatter-registration.md b/docs/adr/0013-tinygo-formatter-registration.md
new file mode 100644
index 000000000..9b39620b0
--- /dev/null
+++ b/docs/adr/0013-tinygo-formatter-registration.md
@@ -0,0 +1,67 @@
+# ADR-0013: Register audit-log formatters for TinyGo builds
+
+- **Status:** accepted
+- **Date:** 2024-04-02
+- **Version:** v3.2.0
+- **PR:** [#1027](https://github.com/corazawaf/coraza/pull/1027)
+- **Issue(s):** Follows [coraza-proxy-wasm#263](https://github.com/corazawaf/coraza-proxy-wasm/pull/263)
+- **Deciders:** @M4tteoP, @jcchavezs
+- **Category:** Parity (TinyGo / WebAssembly build target)
+
+## Context and Problem
+
+The `init_tinygo.go` file had an explicit `TODO` at
+[L22](https://github.com/corazawaf/coraza/blob/0af085cac97602ac22cb58d3a1c7308f241affb6/internal/auditlog/init_tinygo.go#L22)
+saying formatters weren't registered for TinyGo. The proxy-wasm connector
+needed JSON audit logging under TinyGo, so the skipped registration was
+blocking downstream work.
+
+## Decision Drivers
+
+- Support proxy-wasm's need for JSON audit logs without forking the build.
+- Keep build-tag gating so TinyGo-unfriendly dependencies don't leak into the
+  WASM build.
+
+## Considered Options
+
+- Register all formatters unconditionally (breaks TinyGo compile).
+- Add TinyGo-specific copies named `jsonFormatterTinyGo` etc.
+- Use build tags to select which formatter file compiles into which target,
+  keeping the type names consistent.
+
+## Decision Outcome
+
+Chosen: **build-tag selection without renaming types**. The `Tiny` suffix was
+explicitly dropped in review.
+
+> "nit: do we need the Tiny suffix given that we have the build tags. Same
+> for the wasm formatter."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1027#discussion_r1540206047))
+
+> "Yep, not really needed, removed, thanks"
+> — @M4tteoP ([review](https://github.com/corazawaf/coraza/pull/1027#discussion_r1540212934))
+
+## Technical Discussion
+
+One follow-on style call for `serial` naming consistency, deferred to the
+downstream PR:
+
+> "I would not call it wasmSerial but redeclare serial here for tinygo only"
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1027#discussion_r1542832255))
+
+## Participants
+
+- @M4tteoP — author
+- @jcchavezs — review (naming, merge sign-off)
+
+## Consequences
+
+- **Positive:** proxy-wasm (and any other TinyGo-targeting connector) can use
+  JSON audit logging without carrying a patched fork.
+- **Negative / follow-up:** Build-tag matrix grows; TinyGo-specific failures
+  must be covered by the `tinygo.yml` CI workflow going forward.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1027
+- Downstream PR: https://github.com/corazawaf/coraza-proxy-wasm/pull/263
diff --git a/docs/adr/0014-base64decodeext-transformation.md b/docs/adr/0014-base64decodeext-transformation.md
new file mode 100644
index 000000000..4b18de8e8
--- /dev/null
+++ b/docs/adr/0014-base64decodeext-transformation.md
@@ -0,0 +1,80 @@
+# ADR-0014: `base64DecodeExt` transformation
+
+- **Status:** accepted
+- **Date:** 2024-04-24
+- **Version:** v3.2.0
+- **PR:** [#1046](https://github.com/corazawaf/coraza/pull/1046)
+- **Issue(s):** No linked issue
+- **Deciders:** @soujanyanmbri, @jptosso, @jcchavezs, @fzipi
+- **Category:** Parity (ModSecurity parity)
+
+## Context and Problem
+
+PHP-hosted applications accept base64-encoded payloads containing characters
+(notably `.` and space) outside the standard alphabet. Attackers exploit this
+leniency to sneak past WAF decoders. ModSecurity ships a `base64DecodeExt`
+transformation specifically for this case; Coraza did not.
+
+## Decision Drivers
+
+- ModSecurity compatibility — rulesets written for ModSecurity expect this
+  transformation to exist.
+- Specifically defeat base64 evasion variants targeting PHP applications.
+
+## Considered Options
+
+- Extend the existing `base64Decode` with a boolean flag (more booleans on
+  the hot path).
+- Keep `base64Decode` simple and add `base64DecodeExt` as a separate entry.
+- Put one implementation behind a build tag, switch the default after
+  benchmarking.
+
+## Decision Outcome
+
+Chosen: **separate transformation**, matching ModSecurity's surface. The
+build-tag-after-benchmark suggestion was declined because this is a parity
+feature, not a performance question.
+
+> "I would propose a couple of things here: 1. Not pass more booleans but
+> instead add a build tag for this and if the benchmarks are in favour of
+> this new implementation use that by default. 2. Show the benchmark results
+> in the description of the PR assesing why is this better than the existing
+> one."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1046#issuecomment-2071606901))
+
+> "We don't need another reason, it's for compatibility. We just forgot to
+> implement this in the past."
+> — @jptosso ([comment](https://github.com/corazawaf/coraza/pull/1046#issuecomment-2071629112))
+
+## Technical Discussion
+
+@soujanyanmbri summarised the motivation clearly:
+
+> "This is to maintain consistency with modsec with base64DecodeExt operator.
+> base64DecodeExt is mostly to take care of base64decode evasions while the
+> payloads are used in PHP machines (Since, PHP accepts . or ' ' in
+> base64encoded payloads while decoding)"
+> — @soujanyanmbri ([comment](https://github.com/corazawaf/coraza/pull/1046#issuecomment-2069986120))
+
+Test coverage reused the existing JSON-data harness
+(`internal/transformations/testdata/base64DecodeExt.json`).
+
+## Participants
+
+- @soujanyanmbri — author
+- @jptosso — review (parity argument)
+- @jcchavezs — review (proposed build-tag alternative, then accepted)
+- @fzipi — review
+
+## Consequences
+
+- **Positive:** ModSecurity rulesets that rely on `base64DecodeExt` work
+  unchanged against Coraza.
+- **Negative / follow-up:** Two decoders now coexist; authors must know
+  which variant to pick.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1046
+- ModSecurity reference:
+  https://github.com/owasp-modsecurity/ModSecurity/wiki/Reference-Manual-(v2.x)#base64decodeext
diff --git a/docs/adr/0015-case-sensitive-maps.md b/docs/adr/0015-case-sensitive-maps.md
new file mode 100644
index 000000000..cec07f83a
--- /dev/null
+++ b/docs/adr/0015-case-sensitive-maps.md
@@ -0,0 +1,78 @@
+# ADR-0015: Case-sensitive map types
+
+- **Status:** accepted
+- **Date:** 2024-05-01
+- **Version:** v3.2.0
+- **PR:** [#1055](https://github.com/corazawaf/coraza/pull/1055)
+- **Issue(s):** No linked issue (foundation for [#1042](https://github.com/corazawaf/coraza/issues/1042))
+- **Deciders:** @fzipi, @M4tteoP, @jcchavezs, @jptosso
+- **Category:** Feature (foundation API)
+
+## Context and Problem
+
+All Coraza map-backed collections normalised keys to lowercase. That is the
+wrong default for most HTTP semantics — argument names, JSON keys, and XML
+element names are case-sensitive per RFC. Making the whole engine
+case-sensitive in a minor release would silently break rules that assumed the
+old lowercasing.
+
+## Decision Drivers
+
+- Move toward RFC-correct case-sensitivity without a hard v3 break.
+- Keep the existing case-insensitive maps working for backwards
+  compatibility.
+- Make the case-sensitive type available so follow-up work
+  ([ADR-0016](0016-case-sensitive-args.md)) can enable it per-collection.
+
+## Considered Options
+
+- Flip all maps to case-sensitive now (breaking change in v3.x).
+- Add a parallel `NamedCollection` / map type with case-sensitive keys; keep
+  the case-insensitive one as the default.
+- Defer all changes until v4.
+
+## Decision Outcome
+
+Chosen: **add parallel case-sensitive map type as a new type alongside the
+existing one.** The switch-the-default change is deferred to v4.
+
+> "LGTM, what is the plan here? Merge this in Coraza 3.x and then hold #1042
+> (The breaking change) as part of v4 milestones"
+> — @M4tteoP (implied by author confirmation in PR thread; captured in
+> [case-sensitive args follow-up](https://github.com/corazawaf/coraza/pull/1059))
+
+> "I'll be pushing smaller changes until we figure it out. I don't think this
+> will break the api for a major release though."
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1055#issuecomment-2088587799))
+
+## Technical Discussion
+
+Minor style / docs nits only. @jptosso referenced RFC 2616 on header-field
+combining rules, confirming which fields legitimately keep multi-value
+behaviour:
+
+> "RFC 2616 — Multiple message-header fields with the same field-name MAY be
+> present in a message if and only if the entire field-value for that header
+> field is defined as a comma-separated list …"
+> — @jptosso ([review](https://github.com/corazawaf/coraza/pull/1055#discussion_r1582694847))
+
+No architectural debate on the shape of the new type itself.
+
+## Participants
+
+- @fzipi — author
+- @M4tteoP — review (v4 plan)
+- @jcchavezs — review (doc nit)
+- @jptosso — review (RFC reference)
+
+## Consequences
+
+- **Positive:** A case-sensitive map type exists and can be adopted per
+  collection (see ADR-0016).
+- **Negative / follow-up:** Two map types coexist; the full switch to
+  case-sensitive by default is a v4 task.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1055
+- Related ADRs: ADR-0016 (case-sensitive args)
diff --git a/docs/adr/0016-case-sensitive-args.md b/docs/adr/0016-case-sensitive-args.md
new file mode 100644
index 000000000..2eed2d087
--- /dev/null
+++ b/docs/adr/0016-case-sensitive-args.md
@@ -0,0 +1,115 @@
+# ADR-0016: Case-sensitive args support
+
+- **Status:** accepted
+- **Date:** 2024-05-28
+- **Version:** v3.2.0 (behind `coraza.rule.case_sensitive_args_keys` build tag)
+- **PR:** [#1059](https://github.com/corazawaf/coraza/pull/1059)
+- **Issue(s):** No linked issue
+- **Deciders:** @fzipi, @M4tteoP, @jcchavezs, @jptosso, @anuraaga
+- **Category:** Parity (RFC / ModSecurity parity)
+
+## Context and Problem
+
+HTTP argument names are case-sensitive per RFC. Coraza's default
+case-insensitive args behaviour silently merged `foo=1` with `Foo=2` in the
+same collection, which is semantically wrong and, for some protections, can
+mask attacks.
+
+## Decision Drivers
+
+- RFC compliance for argument matching.
+- Avoid breaking rules that relied on the prior case-insensitive behaviour.
+- Interop with the CRS test suite.
+
+## Considered Options
+
+- Flip behaviour in v3.x (breaking).
+- Expose an engine flag (build tag) that opts into case-sensitive args.
+- Let each collection declare its own case-sensitivity via an interface
+  (design preferred by the author, but blocked on existing collection
+  surface).
+
+## Decision Outcome
+
+Chosen: **opt-in via a build tag (`coraza.rule.case_sensitive_args_keys`).**
+The "collection declares its own case-sensitivity" design is captured as a
+known limitation in the PR body:
+
+> "I don't like too much that it is the rule that tells if the collection is
+> case sensitive. Ideally, we should be able to ask the collection (by
+> calling `collection.IsCaseSensitive()` or similar) so that responsibility
+> is delegated properly. But didn't knew how to do it first hand."
+> — @fzipi (PR body)
+
+## Technical Discussion
+
+Long, substantive back-and-forth on whether this is a breaking change.
+
+**M4tteoP flagged the compatibility risk:**
+
+> "Isn't this a breaking change in the behavior of the engine? Up to now
+> users might have written rules in lowercase that would not work anymore
+> once this PR gets merged. Are we okay with this change in a minor release?"
+> — @M4tteoP ([review](https://github.com/corazawaf/coraza/pull/1059#discussion_r1591311146))
+
+**fzipi argued the fix is RFC-correct:**
+
+> "IMHO yes, because this is the common behavior in other engines."
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1059#discussion_r1592452961))
+
+**jcchavezs pushed for build-tag gating to avoid silent breakage:**
+
+> "Maybe we could leverage a build tag for this and introduce the BC in 4.0?"
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1059#discussion_r1592519944))
+
+…and characterised the semantics precisely:
+
+> "rules that use to work won't work anymore and with no notice. That is the
+> definition of breaking change (yes, we are breaking something that was
+> broken)."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1059#discussion_r1595884046))
+
+**anuraaga echoed Go's compatibility posture:**
+
+> "With go's promise of compatibility, it's common to auto-update on minors
+> and expect no change. Just for reference, the recent blog about … For this
+> PR it's still better to add a config option to opt-in to the correct
+> behavior and change that in a major version release to prevent rule
+> breakage."
+> — @anuraaga ([review](https://github.com/corazawaf/coraza/pull/1059#discussion_r1594816563))
+
+**M4tteoP demonstrated a concrete breakage:**
+
+> "With ARGS not case-sensitive, we might have in place a rule like:
+> `SecRule ARGS_GET:var3 \"@rx …\"` … Enabling case sensitivity, it would
+> suddenly just check `ARGS_GET:var3`."
+> — @M4tteoP ([review](https://github.com/corazawaf/coraza/pull/1059#discussion_r1602256989))
+
+The build-tag path won. @fzipi asked for help wiring it:
+
+> "Can someone then, with more knownledge than me, add that magnificent
+> build tag and we can get over this?"
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1059#discussion_r1596029956))
+
+@jcchavezs pointed at the wiring PR (#1065).
+
+## Participants
+
+- @fzipi — author
+- @M4tteoP — review (breakage examples, README update)
+- @jcchavezs — review (drove build-tag gating, BC semantics)
+- @anuraaga — review (Go compat posture, CRS-test suggestion)
+- @jptosso — review
+
+## Consequences
+
+- **Positive:** RFC-correct case-sensitive args is available for embedders
+  that want it today; a clean v4 migration path exists.
+- **Negative / follow-up:** Two behaviours coexist; CRS-test coverage for
+  case sensitivity remained a known gap at merge.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1059
+- Follow-up wiring: https://github.com/corazawaf/coraza/pull/1065
+- Related ADRs: ADR-0015 (case-sensitive maps)
diff --git a/docs/adr/0017-multipart-strict-error.md b/docs/adr/0017-multipart-strict-error.md
new file mode 100644
index 000000000..0771aba65
--- /dev/null
+++ b/docs/adr/0017-multipart-strict-error.md
@@ -0,0 +1,73 @@
+# ADR-0017: Set `MULTIPART_STRICT_ERROR` on multipart parse failure
+
+- **Status:** accepted
+- **Date:** 2024-07-18
+- **Version:** v3.3.0
+- **PR:** [#1098](https://github.com/corazawaf/coraza/pull/1098)
+- **Issue(s):** No linked issue
+- **Deciders:** @fzipi, @M4tteoP
+- **Category:** Parity (ModSecurity variable parity + recommended-config alignment)
+
+## Context and Problem
+
+`coraza.conf-recommended` referenced `MULTIPART_STRICT_ERROR` to detect
+multipart evasions, but Coraza never actually set it — the variable was dead,
+so any rule using it was silently inert. Coraza's multipart parser also does
+not implement every ModSecurity sub-variable, so a single "something went
+wrong" signal was needed as a replacement.
+
+## Decision Drivers
+
+- The recommended config must actually work out of the box.
+- Provide a single global failure signal when the parser cannot fully trust
+  a multipart body, regardless of which sub-variable fired in ModSecurity.
+
+## Considered Options
+
+- Implement every ModSecurity multipart sub-variable (large effort).
+- Set a single `MULTIPART_STRICT_ERROR=1` on any parse failure; rewrite the
+  recommended config rules to use it.
+
+## Decision Outcome
+
+Chosen: **single global failure signal + rewrite recommended rules**.
+@M4tteoP pushed for the recommended config to show only variables Coraza
+actually supports, so operators are not misled:
+
+> "I would also make the rule output more aligned to Coraza removing all
+> these variables that can confuse a user without the context of where this
+> rule is coming from."
+> — @M4tteoP ([comment](https://github.com/corazawaf/coraza/pull/1098#issuecomment-2236872455))
+
+> "We are also recommending this rule: `SecRule MULTIPART_UNMATCHED_BOUNDARY
+> \"@eq 1\" …` But that variable is never set, so that rule cannot be
+> triggered by any means."
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1098#issuecomment-2236896425))
+
+> "Updated the coraza.conf-recommended to a more realistic one."
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1098#issuecomment-2237381208))
+
+## Technical Discussion
+
+Follow-up for an engine-level regression test was captured for a future PR:
+
+> "Eventually for a follow-up PR, would be great to also have an engine test
+> (under `testing/engine`) that triggers this rule, for an e2e-like test of
+> the feature"
+> — @M4tteoP ([review](https://github.com/corazawaf/coraza/pull/1098#discussion_r1683405673))
+
+## Participants
+
+- @fzipi — author
+- @M4tteoP — review (pushed for recommended-config realism)
+
+## Consequences
+
+- **Positive:** Multipart evasion detection in the recommended config
+  actually works; operators get a truthful config out of the box.
+- **Negative / follow-up:** ModSecurity sub-variables remain unimplemented;
+  the single signal is coarse by design.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1098
diff --git a/docs/adr/0018-ocsf-audit-log.md b/docs/adr/0018-ocsf-audit-log.md
new file mode 100644
index 000000000..63d7b3856
--- /dev/null
+++ b/docs/adr/0018-ocsf-audit-log.md
@@ -0,0 +1,111 @@
+# ADR-0018: OCSF (v1.2.0) audit log format
+
+- **Status:** accepted
+- **Date:** 2024-09-17
+- **Version:** v3.3.0
+- **PR:** [#1089](https://github.com/corazawaf/coraza/pull/1089)
+- **Issue(s):** No linked issue (adopts OCSF schema)
+- **Deciders:** @durg78, @jcchavezs, @fzipi, @M4tteoP, @jptosso
+- **Category:** Feature
+
+## Context and Problem
+
+Modern SIEM tooling converges on OCSF (Open Cybersecurity Schema Framework).
+Coraza shipped with a native text format and a JSON format, neither of which
+maps cleanly into OCSF-aligned pipelines. Downstream consumers had to rebuild
+the OCSF record themselves.
+
+## Decision Drivers
+
+- Fit cleanly into OCSF-based observability stacks (SIEMs, XDRs).
+- Reuse an upstream schema library (`github.com/valllabh/ocsf-schema-golang`)
+  rather than hand-roll field mappings.
+- Keep the native/JSON formats as the default — OCSF is opt-in.
+
+## Considered Options
+
+- Add an OCSF wrapper around the existing JSON formatter.
+- Adopt OCSF v1.2.0 directly as a new formatter plugin.
+- Defer until OCSF adoption stabilises.
+
+## Decision Outcome
+
+Chosen: **OCSF v1.2.0 as a new formatter plugin**, opt-in. Native and JSON
+formatters stay the defaults.
+
+> "I think this is great. Being a existing format honestly feels this is
+> better than our JSON format or the modsec one which I am not 100% sure fits
+> in modern tooling. My only request here is that we should avoid changing
+> the transaction to support a format. Audit log formats are pluggable and
+> we should be able to either do everything with what we have or extend what
+> we have to support new use cases but that does not include changing the
+> internal API."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1089#issuecomment-2189072268))
+
+> "I don't think we want to recommend this by default as this feels like a
+> breaking change."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1089#discussion_r1652872889))
+
+> "Audit log is pluggable hence users might define their own, I don't think
+> we can support a strict type for this."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1089#discussion_r1652879947))
+
+> "Agreed. We should keep the native as default for now."
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1089#discussion_r1652910194))
+
+## Technical Discussion
+
+Two cross-cutting issues surfaced during review.
+
+**1. Go version bump.** OCSF dependency forced Go 1.22, and
+`reflect.StringHeader` got deprecated in 1.21 along the way:
+
+> "reflect.StringHeader was deprecated in go 1.21, this was causing the lint
+> check to fail. I wasn't sure how best to handle that other than adding an
+> exception for now."
+> — @durg78 ([review](https://github.com/corazawaf/coraza/pull/1089#discussion_r1652986174))
+
+> "We can also use inline linter nochecks"
+> — @jptosso ([review](https://github.com/corazawaf/coraza/pull/1089#discussion_r1653127458))
+
+The real fix landed separately as PR #1162 — see
+[ADR-0019](0019-unsafe-stringdata-refactor.md).
+
+**2. Respect the plugin boundary.** @jcchavezs specifically rejected any
+change to the internal `Transaction` type to accommodate OCSF-specific
+fields:
+
+> "I doubt the internal transaction has to know about all these fields. I
+> wonder if this could happen in the internal/auditlog#Transaction type."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1089#discussion_r1652885811))
+
+The implementation was restructured to stay within the formatter package.
+
+**3. Rebase + TinyGo.** @M4tteoP asked for a rebase to pick up TinyGo
+updates (PR #1148). After the rebase:
+
+> "Checks are passing now! 🎉"
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1089#issuecomment-2342227609))
+
+## Participants
+
+- @durg78 — author
+- @jcchavezs — review (drove plugin-boundary discipline, Go-version policy)
+- @fzipi — review (merge sign-off, default-format guidance)
+- @M4tteoP — review (TinyGo rebase)
+- @jptosso — review (linter-exception suggestion)
+
+## Consequences
+
+- **Positive:** Modern SIEM ingestion without downstream re-mapping; a clean
+  validation that the formatter plugin boundary holds for non-trivial
+  schemas.
+- **Negative / follow-up:** Coraza's Go minimum version moved forward;
+  `reflect.StringHeader` deprecation surfaced (fixed in ADR-0019).
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1089
+- OCSF schema lib: https://github.com/valllabh/ocsf-schema-golang
+- Related ADRs: ADR-0005 (formatter interface), ADR-0019 (unsafe.StringData),
+  ADR-0028 (syslog writer)
diff --git a/docs/adr/0019-unsafe-stringdata-refactor.md b/docs/adr/0019-unsafe-stringdata-refactor.md
new file mode 100644
index 000000000..b588a55e7
--- /dev/null
+++ b/docs/adr/0019-unsafe-stringdata-refactor.md
@@ -0,0 +1,70 @@
+# ADR-0019: `reflect.StringHeader` → `unsafe.StringData`
+
+- **Status:** accepted
+- **Date:** 2024-10-04
+- **Version:** v3.3.0
+- **PR:** [#1162](https://github.com/corazawaf/coraza/pull/1162)
+- **Issue(s):** [#1147](https://github.com/corazawaf/coraza/issues/1147)
+- **Deciders:** @Juneezee, @jcchavezs, @fzipi
+- **Category:** Refactor
+
+## Context and Problem
+
+`internal/corazawaf/rule.go` used `reflect.StringHeader` for zero-copy
+string/byte reinterpretation. Go 1.20 introduced `unsafe.StringData`, and
+`reflect.StringHeader` was officially deprecated in Go 1.21. The lint
+exception carried over from the OCSF Go-version bump
+([ADR-0018](0018-ocsf-audit-log.md)) was a temporary band-aid.
+
+## Decision Drivers
+
+- Correctness: `reflect.StringHeader` is deprecated and its Godoc explicitly
+  warns about GC-unsafe pointer handling.
+- Remove the lint-exception debt left behind in PR #1089.
+- Keep performance identical — the replacement is the GC-safe pointer
+  accessor.
+
+## Considered Options
+
+- Keep the `StringHeader` pattern with a permanent lint exception.
+- Port to `unsafe.StringData` as the upstream proposal suggests.
+
+## Decision Outcome
+
+Chosen: **port to `unsafe.StringData`.** The PR body cites the Godoc warnings
+directly:
+
+> "The Godoc of `reflect.StringHeader` states: 'the Data field is not
+> sufficient to guarantee the data it references will not be garbage
+> collected, so programs must keep a separate, correctly typed pointer to
+> the underlying data.' … The replacement `unsafe.StringData` is a more
+> correct way to get the pointer to the string data. The original proposal
+> can be seen in golang/go#53003."
+> — @Juneezee (PR body)
+
+## Technical Discussion
+
+No substantive architectural debate on the thread. One-line approval from
+the reviewer:
+
+> "The change looks very reasonable to me."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1162#issuecomment-2389453051))
+
+## Participants
+
+- @Juneezee — author
+- @jcchavezs — review (approval)
+- @fzipi — review
+
+## Consequences
+
+- **Positive:** Removes a deprecated API usage; GC-safe string/byte
+  reinterpretation; lint exception deleted.
+- **Negative:** None.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1162
+- Issue: https://github.com/corazawaf/coraza/issues/1147
+- Upstream proposal: https://github.com/golang/go/issues/53003
+- Related ADRs: ADR-0018 (OCSF audit log)
diff --git a/docs/adr/0020-secruleupdateactionbyid.md b/docs/adr/0020-secruleupdateactionbyid.md
new file mode 100644
index 000000000..5ebda372b
--- /dev/null
+++ b/docs/adr/0020-secruleupdateactionbyid.md
@@ -0,0 +1,73 @@
+# ADR-0020: `SecRuleUpdateActionById` directive
+
+- **Status:** accepted
+- **Date:** 2024-10-31
+- **Version:** v3.3.0
+- **PR:** [#1071](https://github.com/corazawaf/coraza/pull/1071)
+- **Issue(s):** [#929](https://github.com/corazawaf/coraza/issues/929)
+- **Deciders:** @fzipi, @jcchavezs
+- **Category:** Parity (ModSecurity / CRS parity)
+
+## Context and Problem
+
+Operators using CRS needed a way to mutate a rule's action list by ID without
+reloading or editing upstream rule files. ModSecurity ships
+`SecRuleUpdateActionById` for exactly this; Coraza had the target-mutating
+directives but not the action-mutating one.
+
+## Decision Drivers
+
+- CRS tuning parity.
+- Minimal surface growth — mirror the shape of the existing
+  `SecRuleUpdateTargetById` implementation.
+
+## Considered Options
+
+- Extend existing `SecRuleUpdateTargetById` to also cover actions.
+- Ship a distinct `SecRuleUpdateActionById` directive.
+
+## Decision Outcome
+
+Chosen: **distinct directive, mirroring ModSecurity**. This keeps the CRS
+migration path straightforward.
+
+## Technical Discussion
+
+Two minor style requests were the entire review:
+
+> "nit: use `idsOrRangesLen` to avoid generic variable names"
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1071#discussion_r1823795090))
+
+> "nit: flip the conditional to avoid indentation."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1071#discussion_r1823800325))
+
+The author had earlier flagged a separate blocker — tests were failing on an
+unrelated bug that was fixed in PR #1183:
+
+> "After finding why my tests didn't worked (#1183), now this is ready to
+> go."
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1071#issuecomment-2448645235))
+
+No architectural debate took place — the directive's shape followed the
+existing pattern and was uncontroversial.
+
+## Participants
+
+- @fzipi — author
+- @jcchavezs — review (nits)
+
+## Consequences
+
+- **Positive:** Operators can tune CRS rule actions in-place (e.g. turn a
+  `deny` into `pass` for a specific rule) without re-generating ruleset
+  files.
+- **Negative / follow-up:** A later fix (PR #1471) was needed to ensure the
+  directive correctly replaces disruptive actions rather than appending.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1071
+- Issue: https://github.com/corazawaf/coraza/issues/929
+- Test-blocker: https://github.com/corazawaf/coraza/pull/1183
+- Follow-up: https://github.com/corazawaf/coraza/pull/1471
+- Related ADRs: ADR-0012 (`SecRuleUpdateTargetByTag`)
diff --git a/docs/adr/0021-square-brackets-in-variables.md b/docs/adr/0021-square-brackets-in-variables.md
new file mode 100644
index 000000000..02d50d409
--- /dev/null
+++ b/docs/adr/0021-square-brackets-in-variables.md
@@ -0,0 +1,66 @@
+# ADR-0021: Square brackets in macro-expanded variable names
+
+- **Status:** accepted
+- **Date:** 2024-11-21
+- **Version:** v3.3.0
+- **PR:** [#1226](https://github.com/corazawaf/coraza/pull/1226)
+- **Issue(s):** No linked issue
+- **Deciders:** @geoolekom, @M4tteoP, @jcchavezs
+- **Category:** Parity (framework parameter conventions)
+
+## Context and Problem
+
+PHP and jQuery conventions produce parameter names containing square
+brackets (`ARGS.fields[]`, `fields[name]`). Coraza's macro-expansion parser
+rejected these names, breaking macros like
+`%{ARGS.db-reset-tables[]}` in rule messages and forcing users to rewrite
+otherwise-standard rules.
+
+## Decision Drivers
+
+- Compatibility with web-framework parameter conventions.
+- No behaviour change for variable lookups that already worked — only the
+  macro-expansion parser needed widening.
+
+## Considered Options
+
+- Teach every rule-parsing entrypoint to accept brackets.
+- Widen only the macro-expansion parser, which is where the breakage was.
+
+## Decision Outcome
+
+Chosen: **widen only the macro-expansion parser**, matching the narrow scope
+of the observed bug.
+
+## Technical Discussion
+
+The review's substantive thread was about scoping the change correctly.
+
+> "I just wish to double-check the scope of the PR, because the description
+> seems not fully aligned with the code. I tested the following rules, and
+> they actually worked as expected. `SecRule ARGS:key[] …` … What does this
+> PR fixes?"
+> — @M4tteoP ([comment](https://github.com/corazawaf/coraza/pull/1226#issuecomment-2491006691))
+
+> "oh, yes. Indeed, I meant the variables in macro. I missed a `msg` part in
+> my example, my bad."
+> — @geoolekom ([comment](https://github.com/corazawaf/coraza/pull/1226#issuecomment-2491029430))
+
+> "Ok, great, thanks for confirming it!"
+> — @M4tteoP ([comment](https://github.com/corazawaf/coraza/pull/1226#issuecomment-2491685710))
+
+## Participants
+
+- @geoolekom — author
+- @M4tteoP — review (scope clarification)
+- @jcchavezs — review
+
+## Consequences
+
+- **Positive:** CRS and downstream rulesets with PHP/jQuery-style parameter
+  names can use macros referencing them without workarounds.
+- **Negative / follow-up:** None — the change is additive in the parser.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1226
diff --git a/docs/adr/0022-time-variables.md b/docs/adr/0022-time-variables.md
new file mode 100644
index 000000000..9b295c8ad
--- /dev/null
+++ b/docs/adr/0022-time-variables.md
@@ -0,0 +1,118 @@
+# ADR-0022: `TIME_*` variables support
+
+- **Status:** accepted
+- **Date:** 2024-12-09
+- **Version:** v3.3.0
+- **PR:** [#1223](https://github.com/corazawaf/coraza/pull/1223)
+- **Issue(s):** [#1220](https://github.com/corazawaf/coraza/issues/1220)
+- **Deciders:** @geoolekom, @jcchavezs, @M4tteoP, @fzipi, @jptosso
+- **Category:** Parity (ModSecurity parity)
+
+## Context and Problem
+
+ModSecurity exposes `TIME`, `TIME_DAY`, `TIME_EPOCH`, `TIME_HOUR`,
+`TIME_MIN`, `TIME_MON`, `TIME_SEC`, `TIME_WDAY`, `TIME_YEAR`. Popular
+rulesets (Imunify360 was cited) use them heavily for time-window rules and
+for enriching `msg` / `logdata`. Coraza had none.
+
+## Decision Drivers
+
+- ModSecurity compatibility.
+- Support real-world ruleset patterns like "measure duration between two
+  phases" (Imunify360's filescan rules).
+- Pick a single, sensible TIME_MON range (ModSecurity itself is
+  inconsistent: v2 uses 1-12, v3 uses 0-11).
+
+## Considered Options
+
+- Do not implement — push time handling into the embedder's logger.
+- Implement eagerly at transaction-creation time.
+- Implement lazily (fill on first access).
+- Implement eagerly with a precomputed `int → string` lookup table.
+
+## Decision Outcome
+
+Chosen: **eager population at transaction creation, with small perf
+optimisations** (follow-up #1242). Lazy collections were prototyped but did
+not pay off enough to justify the new concept.
+
+> "We merged this PR as it was and with a couple of performance improvements
+> in #1242 because lazy collections wasn't bringing enough improvements for
+> this particular use case that it did not feel right to land such a concept
+> for low benefit."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1223#issuecomment-2568873506))
+
+For `TIME_MON` the PR standardised on **1–12** to align with the
+ModSecurity v2→v3 reconciliation in owasp-modsecurity/ModSecurity#3306.
+
+> "There is already an open PR … that aligns v3 to use `1-12` range. So I
+> believe that we have pretty much agreed that `1-12` range is the one we
+> should stick with. Let's go with it"
+> — @M4tteoP ([review](https://github.com/corazawaf/coraza/pull/1223#discussion_r1853923001))
+
+## Technical Discussion
+
+**Initial resistance from @jcchavezs:**
+
+> "I am not fully convinced on the need of this. I believe the case you
+> point out is more like a logger concern as we are only interpolating the
+> variable to display the timestamp. **Interpolating a variable isn't cheap**,
+> nor it is allocating all the variables we allocated and converted by
+> default from int to string."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1223#issuecomment-2483103482))
+
+…countered with real-world rule examples (Imunify360 filescan duration
+rules), which moved the decision:
+
+> "Thanks @geoolekom! I think most of the points raised here make sense.
+> Let me do a couple of experiments as what I have in mind is that this a
+> good opportunity for trying lazy collections."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1223#issuecomment-2488002382))
+
+**TinyGo / Wasm consideration.** @jcchavezs noted Wasm environments can't
+cheaply call `time.Now()`, so lazy filling was attractive. The PoC lived at
+https://github.com/geoolekom/coraza/pull/1 ; it did not outperform the simple
+eager path enough to ship.
+
+**Perf optimisation.** @jcchavezs suggested a lookup table over `strconv.Itoa`:
+
+> "I was advocating for having a map in memory e.g. `var hourConversion
+> map[int]string = map[int]string{1: \"1\", 2: \"2\", ...}` instead of doing
+> the `strconv.Itoa`."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1223#discussion_r1846662447))
+
+Landed in follow-up #1242.
+
+**Alternative shape considered.** @fzipi asked whether lazy/per-access
+population would be simpler end-to-end:
+
+> "Isn't better to just remove this call and generate the value for each
+> variable at access time instead? Kind of being more an *init* than *set*."
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1223#discussion_r1868568426))
+
+## Participants
+
+- @geoolekom — author (provided the real-world rule examples that carried
+  the decision)
+- @jcchavezs — review (lazy-collection PoC, perf guidance)
+- @M4tteoP — review (drove the `TIME_MON` 1-12 decision)
+- @fzipi — review (shape alternatives)
+- @jptosso — review
+
+## Consequences
+
+- **Positive:** Time-aware rules (scan-duration logic, rate/hour correlation,
+  `msg`/`logdata` enrichment) work in Coraza; CRS and Imunify360 rules that
+  rely on `TIME_*` become usable.
+- **Negative / follow-up:** `time.Now()` is called for every transaction;
+  Wasm-scale deployments pay a cost. Lazy collections explored and declined.
+  Further perf tuning shipped in #1242.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1223
+- Issue: https://github.com/corazawaf/coraza/issues/1220
+- Follow-up perf PR: https://github.com/corazawaf/coraza/pull/1242
+- Lazy-collection PoC: https://github.com/geoolekom/coraza/pull/1
+- ModSecurity TIME_MON alignment: https://github.com/owasp-modsecurity/ModSecurity/issues/3305,
+  https://github.com/owasp-modsecurity/ModSecurity/pull/3306
diff --git a/docs/adr/0023-base64encode-transformation.md b/docs/adr/0023-base64encode-transformation.md
new file mode 100644
index 000000000..e890aac31
--- /dev/null
+++ b/docs/adr/0023-base64encode-transformation.md
@@ -0,0 +1,64 @@
+# ADR-0023: `base64Encode` transformation
+
+- **Status:** accepted
+- **Date:** 2024-12-29
+- **Version:** v3.3.0
+- **PR:** [#1257](https://github.com/corazawaf/coraza/pull/1257)
+- **Issue(s):** [#1252](https://github.com/corazawaf/coraza/issues/1252)
+- **Deciders:** @tty2, @fzipi
+- **Category:** Parity (ModSecurity parity)
+
+## Context and Problem
+
+ModSecurity's `base64Encode` transformation was missing from Coraza. Rulesets
+that use it to encode payloads for logging or indirect comparison did not
+work as written.
+
+## Decision Drivers
+
+- ModSecurity compatibility.
+- Minimal new code — `encoding/base64` stdlib suffices.
+- Test parity with other one-liner transformations (use existing
+  `testdata/base64encode.json`).
+
+## Considered Options
+
+- Hand-roll the encoding loop (no reason to).
+- Wrap `base64.StdEncoding.EncodeToString`.
+
+## Decision Outcome
+
+Chosen: **stdlib wrapper**, following the pattern used by other one-liner
+transformations in `internal/transformations`.
+
+## Technical Discussion
+
+Review was light — a couple of misunderstandings around where the tests
+lived, and a copyright-line suggestion:
+
+> "Ah, good catch! They are already there! Don't need to add them 😄"
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1257#issuecomment-2554359814))
+
+> "```suggestion
+> // Copyright 2024 Juan Pablo Tosso and the OWASP Coraza contributors
+> ```"
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1257#discussion_r1892349843))
+
+No architectural discussion — the transformation is a one-liner around
+`encoding/base64`.
+
+## Participants
+
+- @tty2 — author
+- @fzipi — review
+
+## Consequences
+
+- **Positive:** Rulesets that `t:base64Encode` their payloads now work.
+- **Negative:** None.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1257
+- Issue: https://github.com/corazawaf/coraza/issues/1252
+- ModSecurity reference: https://github.com/owasp-modsecurity/ModSecurity/wiki/Reference-Manual-(v3.x)#base64Encode
diff --git a/docs/adr/0024-hexdecode-transformation.md b/docs/adr/0024-hexdecode-transformation.md
new file mode 100644
index 000000000..3f84bea3b
--- /dev/null
+++ b/docs/adr/0024-hexdecode-transformation.md
@@ -0,0 +1,69 @@
+# ADR-0024: `hexDecode` transformation
+
+- **Status:** accepted
+- **Date:** 2025-01-24
+- **Version:** v3.3.2
+- **PR:** [#1275](https://github.com/corazawaf/coraza/pull/1275)
+- **Issue(s):** [#1253](https://github.com/corazawaf/coraza/issues/1253)
+- **Deciders:** @tty2, @fzipi, @jptosso
+- **Category:** Parity (ModSecurity parity)
+
+## Context and Problem
+
+ModSecurity exposes a `hexDecode` transformation (reverse of hex/base-16
+encoding). Coraza had `hexEncode` but not its counterpart, which left a small
+parity gap.
+
+## Decision Drivers
+
+- ModSecurity parity.
+- Behaviour on malformed input — follow the existing "best-effort" precedent
+  set by other transformations.
+
+## Considered Options
+
+- Strict parse: reject on any non-hex character.
+- Best-effort: trim odd trailing nibbles, decode what's valid.
+
+## Decision Outcome
+
+Chosen: **best-effort decode**, following the existing pattern used by sibling
+transformations. This was a question explicitly raised and resolved in review.
+
+> "This PR is mostly based on assumptions cause I didn't get any reply here
+> [#1253]. The main assumption is that coraza wants to go 'best effort
+> approach'. This assumption is based on the tests … Relying on tests we
+> need to remove the last symbol."
+> — @tty2 ([review](https://github.com/corazawaf/coraza/pull/1275#discussion_r1905517040))
+
+## Technical Discussion
+
+The substantive discussion was about how to interpret an odd-length input
+(technically malformed per hex/base-16 encoding):
+
+> "What does this mean? Can you provide pointers? 'hex' enconding, in the
+> RFC you are mentioning, is just Base16 where each byte is represented as
+> two four bits. So, AFAIU, we are only removing the _last_ input to make an
+> effort to fix a broken input, right? Could the problem be the first
+> instead?"
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1275#discussion_r1905465117))
+
+The decision was to follow the precedent set by other transformations'
+existing test expectations (best-effort, trim trailing).
+
+## Participants
+
+- @tty2 — author
+- @fzipi — review (behaviour on malformed input)
+- @jptosso — review
+
+## Consequences
+
+- **Positive:** `t:hexDecode` works for ModSecurity-migrated rulesets.
+- **Negative:** The "best-effort" choice on malformed input matches existing
+  coraza behaviour but is not strictly RFC-correct. Documented inline.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1275
+- Issue: https://github.com/corazawaf/coraza/issues/1253
diff --git a/docs/adr/0025-selectors-on-names-collections.md b/docs/adr/0025-selectors-on-names-collections.md
new file mode 100644
index 000000000..1deb2fe5a
--- /dev/null
+++ b/docs/adr/0025-selectors-on-names-collections.md
@@ -0,0 +1,83 @@
+# ADR-0025: Selectors on `*_NAMES` collections
+
+- **Status:** accepted
+- **Date:** 2025-05-30
+- **Version:** v3.4.0
+- **PR:** [#1143](https://github.com/corazawaf/coraza/pull/1143)
+- **Issue(s):** No linked issue (docs-referenced crash)
+- **Deciders:** @blotus, @LaurenceJJones, @fzipi, @jcchavezs, @jptosso
+- **Category:** Parity (ModSecurity parity + remove runtime `panic`s)
+
+## Context and Problem
+
+The canonical selector-on-names rule
+`SecRule &REQUEST_COOKIES_NAMES:JSESSIONID "@eq 0" "id:45"`
+is supported by ModSecurity and appears in Coraza's own docs, but in Coraza
+it triggered an explicit `panic`. The fix extends the engine in three
+coordinated ways so (a) this rule works, (b) the error is caught at parse
+time, and (c) the engine never `panic`s at runtime.
+
+## Decision Drivers
+
+- Make docs-example rules actually work.
+- Coraza is embedded — `panic` is not a graceful failure mode.
+- Catch invalid selectors at parse time, before traffic flows.
+
+## Considered Options
+
+- Leave the `panic`, document the limitation.
+- Hard-code which collections are selectable.
+- Tag selectability in metadata comments on the variable definition and
+  derive `CanBeSelected` from that.
+
+## Decision Outcome
+
+Chosen: **metadata-comment-driven selectability + `NamedCollectionNames`
+implements `collection.Keyed` + runtime `panic`s replaced by parser errors
+or error logs**. The author acknowledged the comment-as-metadata trick is
+not ideal:
+
+> "I don't know if I'm really happy with embedding information in comments,
+> but it was the least intrusive way I found to handle this."
+> — @blotus (PR body)
+
+The complexity concern was surfaced by @jptosso for a future refactor:
+
+> "Interesting, thank you very much for your contribution. Im a bit worried
+> about how the complexity of variables is growing. Maybe not for this PR,
+> but we need to improve generation of code, even for this 'selectable'
+> feature"
+> — @jptosso ([comment](https://github.com/corazawaf/coraza/pull/1143#issuecomment-2329129961))
+
+## Technical Discussion
+
+Three areas changed together:
+
+- **Parser check.** `CanBeSelected` is consulted during rule parsing so
+  un-selectable collections fail fast rather than at runtime.
+- **`NamedCollectionNames` implements `Keyed`.** `Get`, `FindString`,
+  `FindRegex` all return the same value for key and value because
+  `*_NAMES` collections return names, not values.
+- **No more `panic`.** Four `panic` sites were replaced with parse-time
+  errors or error-log calls; the remaining defensive logs only trigger
+  if a collection is marked selectable but does not implement `Keyed`.
+
+## Participants
+
+- @blotus — author
+- @LaurenceJJones — review
+- @fzipi — review
+- @jcchavezs — review
+- @jptosso — review (flagged complexity growth)
+
+## Consequences
+
+- **Positive:** Docs-example rules run; configuration errors surface at
+  parse time; Coraza no longer crashes a host process from inside the WAF.
+- **Negative / follow-up:** Variable metadata is carried as comments (a
+  minor maintenance hazard); full code-gen of the variables table is
+  captured as a follow-up concern.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1143
diff --git a/docs/adr/0026-pmf-short-alias.md b/docs/adr/0026-pmf-short-alias.md
new file mode 100644
index 000000000..0deb3f449
--- /dev/null
+++ b/docs/adr/0026-pmf-short-alias.md
@@ -0,0 +1,60 @@
+# ADR-0026: `@pmf` short alias for `@pmFromFile`
+
+- **Status:** accepted
+- **Date:** 2025-05-12
+- **Version:** v3.4.0
+- **PR:** [#1356](https://github.com/corazawaf/coraza/pull/1356)
+- **Issue(s):** [#1283](https://github.com/corazawaf/coraza/issues/1283)
+- **Deciders:** @dmefs, @M4tteoP, @fzipi, @jcchavezs
+- **Category:** Parity (ModSecurity parity — operator alias)
+
+## Context and Problem
+
+ModSecurity documents `@pmf` as the short-form alias of `@pmFromFile`.
+Rulesets relying on that alias did not work in Coraza. This ADR captures
+the straightforward addition of the alias registration.
+
+## Decision Drivers
+
+- ModSecurity parity.
+- Zero behaviour cost — operator aliases register the same implementation
+  under two names.
+
+## Considered Options
+
+- Register the alias.
+- Leave rule authors to rename `@pmf` → `@pmFromFile` in their configs.
+
+## Decision Outcome
+
+Chosen: **register the alias.**
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR or issue thread. The
+author introduced themselves:
+
+> "This is my first PR. I'm happy to make contribution!🥳"
+> — @dmefs ([comment](https://github.com/corazawaf/coraza/pull/1356#issuecomment-2875425220))
+
+…and no code-level review comments were posted. The PR merged after
+approvals.
+
+## Participants
+
+- @dmefs — author
+- @M4tteoP — review
+- @fzipi — review
+- @jcchavezs — review
+
+## Consequences
+
+- **Positive:** `@pmf` works verbatim in Coraza; ModSecurity rulesets carry
+  over cleanly.
+- **Negative:** None.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1356
+- Issue: https://github.com/corazawaf/coraza/issues/1283
+- Related ADRs: ADR-0027 (`@ipMatchF` short alias)
diff --git a/docs/adr/0027-ipmatchf-short-alias.md b/docs/adr/0027-ipmatchf-short-alias.md
new file mode 100644
index 000000000..0ec5fba2a
--- /dev/null
+++ b/docs/adr/0027-ipmatchf-short-alias.md
@@ -0,0 +1,64 @@
+# ADR-0027: `@ipMatchF` short alias for `@ipMatchFromFile`
+
+- **Status:** accepted
+- **Date:** 2025-05-13
+- **Version:** v3.4.0
+- **PR:** [#1357](https://github.com/corazawaf/coraza/pull/1357)
+- **Issue(s):** No linked issue
+- **Deciders:** @dmefs, @M4tteoP, @fzipi, @jcchavezs
+- **Category:** Parity (ModSecurity parity — operator alias)
+
+## Context and Problem
+
+ModSecurity supports `@ipMatchF` as a short-form alias for
+`@ipMatchFromFile`. Like [ADR-0026](0026-pmf-short-alias.md), Coraza was
+missing the alias registration.
+
+## Decision Drivers
+
+- ModSecurity parity.
+- Keep test coverage symmetric: add tests for both the new alias and its
+  canonical form.
+
+## Considered Options
+
+- Register the alias.
+- Leave rule authors to rename.
+
+## Decision Outcome
+
+Chosen: **register the alias, add tests for both forms** per review
+feedback.
+
+## Technical Discussion
+
+Minor reviewer request for test symmetry:
+
+> "I see that you are adding a couple of rules to be tested with
+> `@ipMatchF`. Could you also add the same lines for `@ipMatchFromFile`?
+> Just like we have now the same matching for `@pmFromFile` and `@pmf`"
+> — @M4tteoP ([review](https://github.com/corazawaf/coraza/pull/1357#discussion_r2086599002))
+
+> "Thanks for pointing that out. I'll add the rules for @ipMatchFromFile as
+> well."
+> — @dmefs ([review](https://github.com/corazawaf/coraza/pull/1357#discussion_r2087011488))
+
+No architectural debate.
+
+## Participants
+
+- @dmefs — author
+- @M4tteoP — review (test symmetry)
+- @fzipi — review
+- @jcchavezs — review
+
+## Consequences
+
+- **Positive:** `@ipMatchF` works; operator coverage matches ModSecurity's
+  alias table.
+- **Negative:** None.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1357
+- Related ADRs: ADR-0026 (`@pmf` short alias)
diff --git a/docs/adr/0028-syslog-audit-log-writer.md b/docs/adr/0028-syslog-audit-log-writer.md
new file mode 100644
index 000000000..b9c29f306
--- /dev/null
+++ b/docs/adr/0028-syslog-audit-log-writer.md
@@ -0,0 +1,77 @@
+# ADR-0028: Syslog audit log writer
+
+- **Status:** accepted
+- **Date:** 2025-07-21
+- **Version:** v3.4.0
+- **PR:** [#1383](https://github.com/corazawaf/coraza/pull/1383)
+- **Issue(s):** No linked issue
+- **Deciders:** @Serjick, @jcchavezs
+- **Category:** Feature
+
+## Context and Problem
+
+Coraza had HTTPS audit forwarding ([ADR-0003](0003-https-audit-log-writer.md))
+and file-based writers, but many environments route through syslog —
+rsyslog, journald, or a remote aggregator. Shipping without syslog was a
+gap for traditional infra.
+
+## Decision Drivers
+
+- No new dependencies — the Go stdlib `log/syslog` suffices.
+- Fit the existing `plugintypes.AuditLogWriter` shape so no formatter
+  changes are needed.
+- Reasonable defaults: facility `local0`, `LOG_INFO` for normal audit
+  entries, `LOG_ERR` for interrupted transactions.
+- Flexible destination string so operators can target any network/raddr
+  supported by `log/syslog`.
+
+## Considered Options
+
+- Third-party syslog client with structured-data support.
+- `log/syslog` stdlib.
+
+## Decision Outcome
+
+Chosen: **stdlib `log/syslog`**, with directive integration:
+
+- `SecAuditLogType syslog`
+- `SecAuditLog network://raddr` (e.g. `udp://127.0.0.1:514`,
+  `unixgram:///var/run/syslog`); empty lets `log/syslog` choose.
+
+Two explicit platform limitations are called out in the PR body:
+
+> "Not available for tinygo because of not verified `log/syslog` support.
+> Not available for windows and plan9 operating systems because of
+> `log/syslog` limitations."
+> — @Serjick (PR body)
+
+## Technical Discussion
+
+No substantive technical debate took place on the PR thread. Review
+activity was limited to a coverage-bump round:
+
+> "I've taken steps to increase test coverage of `syslog_writer.go`, please
+> rerun pipeline."
+> — @Serjick ([comment](https://github.com/corazawaf/coraza/pull/1383#issuecomment-3077277446))
+
+The author had clearly thought through the mapping of severity and
+destination; reviewers approved on that basis with no architectural
+counter-proposal.
+
+## Participants
+
+- @Serjick — author
+- @jcchavezs — review
+
+## Consequences
+
+- **Positive:** Coraza slots into traditional syslog-based logging pipelines
+  without an external collector; interrupted transactions get higher
+  severity automatically.
+- **Negative:** Windows, Plan 9 and TinyGo builds cannot use the writer.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1383
+- Related ADRs: ADR-0003 (HTTPS audit log writer), ADR-0005 (formatter
+  interface)
diff --git a/docs/adr/0029-json-schema-improvements.md b/docs/adr/0029-json-schema-improvements.md
new file mode 100644
index 000000000..c26cb100e
--- /dev/null
+++ b/docs/adr/0029-json-schema-improvements.md
@@ -0,0 +1,95 @@
+# ADR-0029: JSON schema audit log improvements
+
+- **Status:** accepted
+- **Date:** 2025-08-11
+- **Version:** v3.4.0
+- **PR:** [#1384](https://github.com/corazawaf/coraza/pull/1384) (rework of [#1343](https://github.com/corazawaf/coraza/pull/1343))
+- **Issue(s):** No linked issue
+- **Deciders:** @jcchavezs, @M4tteoP, @airween, @fzipi, @cognitivegears
+- **Category:** Feature
+
+## Context and Problem
+
+The original JSON-schema work ([#1343](https://github.com/corazawaf/coraza/pull/1343))
+added JSON-schema-validation scaffolding to Coraza's audit logging layer, but
+left open questions: what's the right SecLang directive, and does Coraza need
+to distinguish XML vs. JSON external-entity handling explicitly? This PR
+picked up the rework and shipped the improvements.
+
+## Decision Drivers
+
+- Keep naming sensible for non-XML (JSON) contexts.
+- Stay compatible with the future ModSecurity direction for JSON-schema
+  validation.
+- Preserve the audit log contract — additional recorded variables must not
+  break existing consumers.
+
+## Considered Options
+
+- Reuse `SecXmlExternalEntity` as an umbrella directive for schema-enable
+  toggles.
+- Introduce `SecJsonExternalEntity` mirroring the XML directive name.
+- Introduce `@validateSchema` operator that works on both JSON and XML
+  targets, plus a matching directive.
+
+## Decision Outcome
+
+Chosen: **merge the rework and settle naming in a follow-up thread.** The
+operator name and directive ambiguity are acknowledged as unresolved at
+merge time.
+
+> "I will merge this and we can settle the extra flag in another thread."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1384#issuecomment-3096079652))
+
+## Technical Discussion
+
+**Naming collaboration with upstream ModSecurity.** @airween volunteered the
+intended ModSecurity direction:
+
+> "if you want to follow the XMl's validation method, then I suggest to use
+> this keyword. There is a plan to add this feature (JSON schema validation)
+> to ModSecurity, and I think it will be used there."
+> — @airween ([comment](https://github.com/corazawaf/coraza/pull/1384#issuecomment-3065045886))
+
+@jcchavezs asked for the name clarification:
+
+> "You mean to use `SecJsonExternalEntity` or `SecXmlExternalEntity`?"
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1384#issuecomment-3066672310))
+
+**Unified operator proposal.** @M4tteoP sketched a shared operator shape:
+
+> "```
+> SecXmlExternalEntity On
+> SecRule XML \"@validateSchema /path/to/xml.xsd\"
+> ```
+> So, in the context of JSON it could become:
+> ```
+> SecJsonExternalEntity On
+> SecRule JSON \"@validateSchema /path/to/schema.json\"
+> ```
+> The operator `@validateSchema` can be flexible enough to deal with both
+> json and XML based on the variable or/and the extension of the provided
+> schema."
+> — @M4tteoP ([comment](https://github.com/corazawaf/coraza/pull/1384#issuecomment-3067129756))
+
+## Participants
+
+- @jcchavezs — author of rework
+- @M4tteoP — review (proposed unified operator)
+- @airween — review (ModSecurity-roadmap input)
+- @fzipi — review
+- @cognitivegears — original work in #1343
+
+## Consequences
+
+- **Positive:** JSON-schema-related audit improvements ship in v3.4.0,
+  closing the long-running #1343 workstream.
+- **Negative / follow-up:** Naming (`SecJsonExternalEntity` vs reused XML
+  directive) remains to be settled; `@validateSchema` unified-operator
+  proposal is captured for follow-up.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1384
+- Original: https://github.com/corazawaf/coraza/pull/1343
+- ModSecurity XML reference: https://github.com/owasp-modsecurity/ModSecurity/wiki/Reference-Manual-(v3.x)#SecXmlExternalEntity
diff --git a/docs/adr/0030-secrequestbodyjsondepthlimit.md b/docs/adr/0030-secrequestbodyjsondepthlimit.md
new file mode 100644
index 000000000..fa4b48688
--- /dev/null
+++ b/docs/adr/0030-secrequestbodyjsondepthlimit.md
@@ -0,0 +1,95 @@
+# ADR-0030: `SecRequestBodyJsonDepthLimit` directive
+
+- **Status:** accepted
+- **Date:** 2026-03-06
+- **Version:** v3.4.0
+- **PR:** [#1110](https://github.com/corazawaf/coraza/pull/1110)
+- **Issue(s):** No linked issue
+- **Deciders:** @fzipi, @jcchavezs
+- **Category:** Feature
+
+## Context and Problem
+
+Deeply nested JSON request bodies can exhaust the parser or the WAF host's
+stack — a known DoS class that has burned ModSecurity in the past. Coraza
+had no configurable ceiling, and the JSON body processor also entered
+parsing without validating the input first.
+
+## Decision Drivers
+
+- Bound JSON recursion to prevent DoS via deeply nested objects.
+- Validate JSON before handing it to the arg-extraction step so invalid
+  bodies do not partially populate collections.
+- Pick a conservative default (1024) that accommodates real schemas.
+
+## Considered Options
+
+- Validate + depth-limit unconditionally (extra CPU per request).
+- Parse-and-bail (best effort, cheaper), risk of mid-parse collection
+  pollution.
+- Pre-validate with `gjson.Valid` then parse with the lazy `gjson.Parse`.
+
+## Decision Outcome
+
+Chosen: **pre-validate with `gjson.Valid`, then parse**, and introduce
+`SecRequestBodyJsonDepthLimit` (default 1024). The author benchmarked the
+overhead explicitly and found it acceptable (~33% of the full JSON pipeline
+in the worst case), citing the upstream library's own recommendation:
+
+> "It is not very expensive. Of course, it is _more_ expensive than not
+> doing vlaidation (adds roughly 33% more time in my benchmarks). The
+> upstream library says that '_If you are consuming JSON from an
+> unpredictable source then you may want to validate prior to using
+> GJSON._' I agree, for the case of a WAF. Or we can forget about
+> validation, and see if someone can bypass us. 🤷 If we do, we should
+> document clearly this decision."
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1110#discussion_r1685809270))
+
+@jcchavezs challenged the expense and the unbounded config:
+
+> "do we really need to do this? the first impression is this is very
+> expensive, the second one is when we use a low body limit this will
+> always be invalid isn't/"
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1110#discussion_r1685791244))
+
+> "I think it should never be -1 and always force a limit."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1110#discussion_r1685791885))
+
+The final shape: bounded by default, operator can raise the limit but not
+disable it, and the author ran full benchmarks to back the cost claim:
+
+> "## Benchmark: `gjson.Valid` pre-validation overhead … Measured the cost
+> of `gjson.Valid()` in the full `readJSON` pipeline …"
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1110#issuecomment-3904707166))
+
+## Technical Discussion
+
+The "should there be a hard ceiling on the directive" question was also
+captured:
+
+> "should there be any hard limit?"
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1110#discussion_r2809954992))
+
+> "Do you mean theoretically? Or practically?"
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1110#discussion_r2809956756))
+
+The final implementation ships a default (1024) and leaves the ceiling
+operator-tunable, on the reasoning that 1024 already dwarfs any realistic
+schema.
+
+## Participants
+
+- @fzipi — author (benchmarks + defense of pre-validation)
+- @jcchavezs — review (cost, default, hard-ceiling pushback)
+
+## Consequences
+
+- **Positive:** DoS-class attack via deeply nested JSON is neutralised by
+  default; invalid JSON is rejected before collection pollution.
+- **Negative / follow-up:** Extra ~33% cost on the JSON body path —
+  accepted for a WAF under untrusted input.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1110
+- gjson upstream: https://github.com/tidwall/gjson#validate-json
diff --git a/docs/adr/0031-multipart-unexpected-eof.md b/docs/adr/0031-multipart-unexpected-eof.md
new file mode 100644
index 000000000..3835960dc
--- /dev/null
+++ b/docs/adr/0031-multipart-unexpected-eof.md
@@ -0,0 +1,95 @@
+# ADR-0031: Ignore unexpected EOF in MIME multipart body processor
+
+- **Status:** accepted
+- **Date:** 2026-03-06
+- **Version:** v3.4.0
+- **PR:** [#1453](https://github.com/corazawaf/coraza/pull/1453)
+- **Issue(s):** No linked issue
+- **Deciders:** @hnakamur, @fzipi, @jcchavezs, @Copilot (PR reviewer bot)
+- **Category:** Parity (ProcessPartial semantics)
+
+## Context and Problem
+
+When `SecRequestBodyLimitAction` is `ProcessPartial`, Coraza stops reading
+the body at the limit, which yields an `io.ErrUnexpectedEOF` to the
+multipart parser. The parser treated that as fatal, losing the parts it had
+already decoded and leaving the transaction with empty `ARGS_POST` /
+`FILES` collections.
+
+## Decision Drivers
+
+- Honour `ProcessPartial`'s contract: keep what was parsed before the cut.
+- Keep the collections populated with whatever made it in (files, form
+  fields) so rules can fire on partial data.
+- No behaviour change when the body is complete.
+
+## Considered Options
+
+- Propagate the EOF and drop partial data (status quo).
+- Treat `io.ErrUnexpectedEOF` as a clean termination and preserve partials.
+
+## Decision Outcome
+
+Chosen: **treat unexpected EOF as clean termination** in the multipart
+processor, preserving both files and form-field parts collected so far.
+`filesCombinedSizeCol` is updated before the early return so size-based
+rules see truthful values.
+
+## Technical Discussion
+
+Most substantive review came from the Copilot PR reviewer. Three issues
+were flagged and fixed:
+
+**1. Form-field data needs to be asserted in tests.**
+> "The test cases don't verify that form field data … is correctly processed
+> before the incomplete file part. Consider adding assertions to check that
+> v.ArgsPost() contains the expected 'text' field value to ensure that
+> partial processing works correctly for both files and form fields."
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1453#discussion_r2651017385))
+
+**2. `filesCombinedSizeCol` was being skipped on the break path.**
+> "After encountering an unexpected EOF and breaking out of the loop, the
+> function should still update `filesCombinedSizeCol` before returning.
+> Currently, the break at line 96 skips the `filesCombinedSizeCol` update at
+> line 108, which could result in an incorrect combined file size when
+> partial processing occurs."
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1453#discussion_r2651845715))
+
+> "Fixed."
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1453#discussion_r2895132899))
+
+**3. Need a form-field-truncation case.**
+> "All test cases focus on incomplete file parts, but there's no test case
+> for an incomplete regular form field."
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1453#discussion_r2651017397))
+
+> "Added."
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1453#discussion_r2895122169))
+
+@jcchavezs wired up a Copilot-driven follow-up PR for the changes:
+
+> "@copilot open a new pull request to apply changes based on the comments
+> in …"
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1453#issuecomment-4008409641))
+
+## Participants
+
+- @hnakamur — author
+- @fzipi — review (applied fixes)
+- @jcchavezs — review (Copilot orchestration)
+- @Copilot (PR reviewer bot) — review
+
+## Consequences
+
+- **Positive:** `ProcessPartial` actually yields partial data for multipart
+  requests; truncation does not wipe the transaction.
+- **Negative / follow-up:** The `io.ErrUnexpectedEOF` case is now silently
+  benign in the multipart path; genuine parse corruption may be harder to
+  distinguish from legitimate truncation. The existing
+  `MULTIPART_STRICT_ERROR` (see [ADR-0017](0017-multipart-strict-error.md))
+  still triggers on actual parse faults.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1453
+- Related ADRs: ADR-0017 (`MULTIPART_STRICT_ERROR`)
diff --git a/docs/adr/0032-ctl-auditlogparts-plus-minus.md b/docs/adr/0032-ctl-auditlogparts-plus-minus.md
new file mode 100644
index 000000000..f9d6ed29b
--- /dev/null
+++ b/docs/adr/0032-ctl-auditlogparts-plus-minus.md
@@ -0,0 +1,91 @@
+# ADR-0032: `ctl:auditLogParts` `+`/`-` modification syntax
+
+- **Status:** accepted
+- **Date:** 2026-01-13
+- **Version:** v3.4.0
+- **PR:** [#1467](https://github.com/corazawaf/coraza/pull/1467)
+- **Issue(s):** No linked issue (ModSecurity compatibility)
+- **Deciders:** @fzipi, @jcchavezs, @Copilot (reviewer)
+- **Category:** Parity (ModSecurity parity — `ctl` grammar extension)
+
+## Context and Problem
+
+ModSecurity's `ctl:auditLogParts=+X` and `ctl:auditLogParts=-X` lets a rule
+*add* or *remove* specific audit-log parts on the fly without listing every
+part again. Coraza only accepted absolute replacement (`ctl:auditLogParts=ABCDEFZ`),
+which forces rule authors to know every current part.
+
+## Decision Drivers
+
+- ModSecurity parity for a commonly-used `ctl` form.
+- Preserve audit-log part ordering when modifying.
+- Fail fast on malformed modifications (`++`, `--`).
+
+## Considered Options
+
+- Map-based de-duplication for parts.
+- Slice + `slices.Contains` for ordered iteration.
+- Accept both `+`/`-` and absolute forms in one function.
+
+## Decision Outcome
+
+Chosen: **one function `ApplyAuditLogParts` handling both forms**, backed
+by an ordered slice of valid parts (not a map) because part ordering
+matters for the audit log layout.
+
+> "either we use ordered in all or we use validHere because otherwise we
+> are reordering the parts."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1467#discussion_r2680503702))
+
+> "let's get rid of this and use `slice.Contains` with orderedAuditLogParts.
+> While map is supposed to be O(1) for small sets, iteration performs
+> better so I'd rather to that."
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1467#discussion_r2688076857))
+
+Malformed inputs are rejected by the existing `validOpts` check:
+
+> "None, as this is checked by `validOpts`. It will be rejected with
+> `invalid audit log parts +`."
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1467#discussion_r2681944724))
+
+## Technical Discussion
+
+**`map` vs `slice` debate.** @jcchavezs initially proposed
+`map[AuditLogPart]struct{}` for set semantics; reverted to
+`slices.Contains` for ordering + better small-N performance.
+
+**Pathological modifications.** @jcchavezs explicitly asked about `++`:
+
+> "What if moditication is `++` or `--`?"
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1467#discussion_r2680505932))
+
+…answered by @fzipi above: rejected with a clear error.
+
+**Copilot-reviewer hot-path concern** (deferred):
+
+> "The orderedParts slice is recreated on every call to
+> `ApplyAuditLogParts`. Consider moving this to a package-level variable
+> to avoid repeated allocations, especially since this is in a critical
+> path"
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1467#discussion_r2678672834))
+
+Reviewers merged on the trade-off between readability and micro-alloc cost;
+a package-level variable is an easy follow-up if profiling surfaces it.
+
+## Participants
+
+- @fzipi — author
+- @jcchavezs — review (drove slice-vs-map decision)
+- @Copilot — PR reviewer bot (hot-path concern)
+
+## Consequences
+
+- **Positive:** ModSecurity-style additive/subtractive audit-log-part
+  tuning works in Coraza; rules no longer need to restate every part.
+- **Negative / follow-up:** `orderedParts` slice re-allocated per call;
+  small, but worth profiling if noticed on the hot path.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1467
+- Follow-up (Copilot-driven): https://github.com/corazawaf/coraza/pull/1468
diff --git a/docs/adr/0033-strmatch-operator.md b/docs/adr/0033-strmatch-operator.md
new file mode 100644
index 000000000..0679ec506
--- /dev/null
+++ b/docs/adr/0033-strmatch-operator.md
@@ -0,0 +1,83 @@
+# ADR-0033: `@strmatch` operator
+
+- **Status:** accepted
+- **Date:** 2026-01-15
+- **Version:** v3.4.0
+- **PR:** [#1473](https://github.com/corazawaf/coraza/pull/1473)
+- **Issue(s):** [#1350](https://github.com/corazawaf/coraza/issues/1350)
+- **Deciders:** @fzipi, @jcchavezs, @Copilot (reviewer)
+- **Category:** Parity (ModSecurity parity — operator)
+
+## Context and Problem
+
+ModSecurity's `@strmatch` is a substring-search operator — cheaper than
+`@rx` for literal substring checks. Coraza had no equivalent, forcing rule
+authors to use `@rx` (regex engine) even for trivial "contains" tests.
+
+## Decision Drivers
+
+- ModSecurity parity.
+- Offer a cheaper path than `@rx` for literal substring checks.
+- Reuse Go's `strings.Contains` (well-optimised hybrid substring search).
+
+## Considered Options
+
+- Naive byte-by-byte matcher.
+- Wrap `strings.Contains`.
+- Ship hand-rolled BMH or Rabin-Karp implementations.
+
+## Decision Outcome
+
+Chosen: **wrap `strings.Contains`.** Benchmark-comparison implementations
+(BMH, naive) that were part of the initial PR were removed from the final
+merge:
+
+> "The benchmark file includes two complete string search algorithm
+> implementations (BMH and naive search) that are only used for
+> performance comparison and are not part of the actual operator. This
+> adds unnecessary code complexity and maintenance burden to the
+> repository."
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1473#discussion_r2694162335))
+
+> "Benchmark removed."
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1473#discussion_r2695378627))
+
+The initial doc comment incorrectly claimed `strings.Contains` is Rabin-Karp
+and used SIMD; Copilot pointed out both were inaccurate:
+
+> "The documentation states that `strings.Contains` implements the
+> Rabin-Karp algorithm, but this is inaccurate. Go's standard library uses
+> a hybrid approach that includes Boyer-Moore for longer patterns and
+> optimized byte search for shorter patterns."
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1473#discussion_r2694162310))
+
+The doc comment was updated to remove the claims.
+
+## Technical Discussion
+
+**Empty-string handling.** @jcchavezs asked whether the operator handles
+empty input; @fzipi confirmed `NewMacro` guards it upstream:
+
+> "does this check if data is empty?"
+> — @jcchavezs ([review](https://github.com/corazawaf/coraza/pull/1473#discussion_r2695698112))
+
+> "Yes, NewMacro checks for empty strings."
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1473#discussion_r2695754879))
+
+## Participants
+
+- @fzipi — author
+- @jcchavezs — review (empty-data check)
+- @Copilot — PR reviewer bot (drove doc-accuracy + dead-code removal)
+
+## Consequences
+
+- **Positive:** Rule authors get a cheap literal-substring operator; cuts
+  regex overhead on the many CRS rules that do substring matching.
+- **Negative:** None beyond maintaining a thin wrapper over a stdlib
+  function.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1473
+- Issue: https://github.com/corazawaf/coraza/issues/1350
diff --git a/docs/adr/0034-rule-observer-callback.md b/docs/adr/0034-rule-observer-callback.md
new file mode 100644
index 000000000..8532c352d
--- /dev/null
+++ b/docs/adr/0034-rule-observer-callback.md
@@ -0,0 +1,96 @@
+# ADR-0034: Optional rule observer callback on `WAFConfig`
+
+- **Status:** accepted
+- **Date:** 2026-02-24
+- **Version:** v3.4.0
+- **PR:** [#1478](https://github.com/corazawaf/coraza/pull/1478)
+- **Issue(s):** No linked issue
+- **Deciders:** @heaven, @fzipi, @jcchavezs
+- **Category:** Feature (plugin surface)
+
+## Context and Problem
+
+UIs and ops tooling around Coraza wanted a way to introspect the exact
+rules loaded by a running WAF (for display, metrics, audit). Previously
+they had to maintain a parallel copy of the ruleset — a drift hazard.
+
+## Decision Drivers
+
+- Expose the loaded ruleset to the embedder without breaking the existing
+  `WAF`/`Transaction` interfaces.
+- Zero cost when unused.
+- Stage the API through `experimental` so future shape changes aren't
+  blocked by semver.
+
+## Considered Options
+
+- Add `WithRuleObserver` directly on `WAFConfig` (non-experimental).
+- Add the type-level method + an `experimental.WAFConfigWithRuleObserver`
+  helper that does the type assertion.
+- Expose rules via a pull API (`RulesCount()` etc.) — tackled separately in
+  [ADR-0035](0035-wafwithrules-interface.md).
+
+## Decision Outcome
+
+Chosen: **type-level method + `experimental` helper**, mirroring the
+existing `WithErrorCallback` pattern. @fzipi initially preferred putting
+the whole thing under `experimental`:
+
+> "I like this idea. But maybe moving it to the `experimental` package
+> first?"
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1478#issuecomment-3770237942))
+
+@jcchavezs articulated the final shape and the v4-safety rationale:
+
+> "I like the idea too but I was thinking we should move this to
+> experimental. We could 1. Do not add the method in the interface but the
+> type only 2. create a function in `experimental` called
+> `WAFConfigWithRuleObserver` which does the interface assertion and calles
+> the type method."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1478#issuecomment-3787116970))
+
+> "To avoid future breaking changes, we usually land new features that are
+> still in development under the experimental package so we won't break
+> anyone if we decide to change it later."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1478#issuecomment-3814374587))
+
+## Technical Discussion
+
+**Circular-import hurdle.** @heaven hit an unexpected cyclic import:
+
+> "Because the core `coraza` package already depends on `experimental`, the
+> experimental helper cannot reference the `WAFConfig` directly without
+> creating a cyclic import. So I had to use reflection to preserve the
+> immutable builder semantics."
+> — @heaven ([comment](https://github.com/corazawaf/coraza/pull/1478#issuecomment-3828189778))
+
+The cyclic-import finding motivated the separate refactor in
+[ADR-0036](0036-remove-root-experimental-dep.md) that removed the root →
+`experimental` direction.
+
+**Immutability preservation.** @heaven opted for the minimum-footprint
+path, mimicking the existing `WithErrorCallback`:
+
+> "My goal was to make the footprint as small as possible, though, so I
+> tried the opposite – to avoid new types and other exports."
+> — @heaven ([comment](https://github.com/corazawaf/coraza/pull/1478#issuecomment-3798817597))
+
+## Participants
+
+- @heaven — author
+- @fzipi — review (experimental-package proposal)
+- @jcchavezs — review (shape: type + experimental assertion helper)
+
+## Consequences
+
+- **Positive:** UIs can observe the loaded ruleset directly; no parallel
+  dataset to keep in sync.
+- **Negative / follow-up:** Reflection in the experimental helper is a
+  temporary wart — cleaned up by the package-dependency flip in
+  [ADR-0036](0036-remove-root-experimental-dep.md).
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1478
+- Related ADRs: ADR-0035 (`WAFWithRules` / `RulesCount()`), ADR-0036
+  (remove root→experimental dep)
diff --git a/docs/adr/0035-wafwithrules-interface.md b/docs/adr/0035-wafwithrules-interface.md
new file mode 100644
index 000000000..33e05615e
--- /dev/null
+++ b/docs/adr/0035-wafwithrules-interface.md
@@ -0,0 +1,113 @@
+# ADR-0035: `WAFWithRules` experimental interface — `RulesCount()` / `MergeRules()`
+
+- **Status:** accepted
+- **Date:** 2026-02-27
+- **Version:** v3.4.0
+- **PR:** [#1492](https://github.com/corazawaf/coraza/pull/1492)
+- **Issue(s):** Dependency of [libcoraza#50](https://github.com/corazawaf/libcoraza/pull/50)
+- **Deciders:** @ppomes, @fzipi, @M4tteoP, @Copilot (reviewer)
+- **Category:** Feature (API)
+
+## Context and Problem
+
+Connectors (nginx, Apache) needed a way to:
+
+1. Report how many rules a WAF instance has loaded — for caching, logging,
+   and load-verification checks.
+2. Inherit/merge rules across config scopes (http → server → location in
+   nginx terms).
+
+Neither capability was exposed before this PR.
+
+## Decision Drivers
+
+- Provide an experimental interface (`WAFWithRules`) that connectors can
+  type-assert to, keeping the main `WAF` interface small.
+- Define merge semantics: duplicate IDs skipped, ID=0 rules (`SecMarker`,
+  un-ID'd `SecAction`) always merged because they legitimately repeat.
+- Allow concurrent-safety guarantees to remain with the initialization
+  phase only.
+
+## Considered Options
+
+- Promote `RulesCount()` / `MergeRules()` onto `WAF` (breaks semver).
+- Ship as a separate `WAFWithRules` experimental interface.
+
+## Decision Outcome
+
+Chosen: **separate `experimental.WAFWithRules` interface**. ID=0 merge
+semantics explicitly documented.
+
+## Technical Discussion
+
+The Copilot reviewer drove five substantive structural changes:
+
+**1. O(n·m) merge complexity.**
+> "`RuleGroup.Merge` performs `FindByID` for each rule being merged, making
+> merges O(n*m). In nginx config inheritance, this could be invoked per
+> location and become noticeably expensive with large rulesets (e.g., CRS).
+> Consider building a set/map of existing IDs once … and doing O(1)
+> lookups while iterating the source rules."
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1492#discussion_r2835610053))
+
+**2. Nil-safety on `Merge`.**
+> "`RuleGroup.Merge` will panic if called with `other == nil`. Since the
+> method returns an `error`, it would be safer to treat a nil source as a
+> no-op"
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1492#discussion_r2835610061))
+
+**3. Thread-safety documentation.**
+> "`MergeRules` mutates the WAF's rule set, but both the public `WAF` type
+> and internal WAF docs state instances are 'concurrent safe' … Please
+> document the required usage constraints (e.g., must be called during
+> initialization before any transactions are created / not safe
+> concurrently with transaction processing)"
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1492#discussion_r2835610080))
+
+**4. Brittle concrete-type switch.**
+> "`MergeRules` only accepts `other` when it is exactly the unexported
+> concrete type `wafWrapper` (value). This makes the
+> `experimental.WAFWithRules` interface hard to use with
+> decorators/wrappers and is also brittle … Consider using a type switch
+> that supports both `wafWrapper` and `*wafWrapper`"
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1492#discussion_r2835610087))
+
+**5. ID=0 semantics.**
+> "`WAFWithRules` docs say 'Rules already present (by ID) are skipped', but
+> the underlying implementation (via `RuleGroup.Merge`) always merges rules
+> with ID 0 (e.g., `SecMarker`) even if the destination already has ID 0
+> rules. Please either document this ID=0 exception here, or change the
+> merge logic"
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1492#discussion_r2835610077))
+
+@ppomes extended tests to cover `SecAction` without explicit `id:`:
+
+> "Added tests at both levels: `TestRuleGroupMergeSecAction` … and
+> `TestMergeRulesSecAction` … verifies both SecAction rules are merged and
+> never deduplicated"
+> — @ppomes ([review](https://github.com/corazawaf/coraza/pull/1492#discussion_r2835771992))
+
+@fzipi flagged the ID=0 semantic during review ("wait, my bad: `SecMarker`
+has ID=0, not `SecAction`"), showing the nuance the Copilot reviewer's
+concern was pointing at.
+
+## Participants
+
+- @ppomes — author (downstream libcoraza driving the need)
+- @fzipi — review (SecAction / SecMarker ID-0 semantics)
+- @M4tteoP — review
+- @Copilot — reviewer bot (drove 5 structural improvements)
+
+## Consequences
+
+- **Positive:** Connectors can query rule counts and merge rulesets across
+  configuration scopes without maintaining their own bookkeeping.
+- **Negative / follow-up:** Merge is not safe concurrent with transaction
+  processing — documented. The brittle type-switch / lack of decorator
+  support were improved during review but remain an area to watch.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1492
+- libcoraza dependency: https://github.com/corazawaf/libcoraza/pull/50
+- Related ADRs: ADR-0034 (rule observer callback)
diff --git a/docs/adr/0036-remove-root-experimental-dep.md b/docs/adr/0036-remove-root-experimental-dep.md
new file mode 100644
index 000000000..ba2a0aa8b
--- /dev/null
+++ b/docs/adr/0036-remove-root-experimental-dep.md
@@ -0,0 +1,64 @@
+# ADR-0036: Remove root package dependency on `experimental`
+
+- **Status:** accepted
+- **Date:** 2026-02-24
+- **Version:** v3.4.0
+- **PR:** [#1494](https://github.com/corazawaf/coraza/pull/1494)
+- **Issue(s):** No linked issue (surfaced by [#1478](https://github.com/corazawaf/coraza/pull/1478))
+- **Deciders:** @fzipi
+- **Category:** Refactor
+
+## Context and Problem
+
+The root `github.com/corazawaf/coraza/v3` package imported
+`experimental`, which made it impossible for the `experimental` package to
+import back into the root — the kind of thing that blocks clean
+assertion-helper patterns. The cycle bit the rule-observer work
+([ADR-0034](0034-rule-observer-callback.md)), where @heaven had to fall
+back to reflection.
+
+## Decision Drivers
+
+- Let `experimental` reference root-package types so assertion helpers
+  (e.g. `WAFConfigWithRuleObserver`) can be implemented without reflection.
+- `experimental` should depend on stable; stable should not depend on
+  experimental.
+
+## Considered Options
+
+- Keep the status quo, continue using reflection-based workarounds.
+- Invert the direction: root no longer imports `experimental`; `experimental`
+  imports root.
+
+## Decision Outcome
+
+Chosen: **invert the direction.** This is the preparatory refactor that
+unblocks clean helpers (#1478) and future additions.
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR thread — the
+refactor is mechanical and reviewers approved it as a plumbing fix. The
+*why* is documented explicitly in the follow-up PR:
+
+> "Because the core `coraza` package already depends on `experimental`, the
+> experimental helper cannot reference the `WAFConfig` directly without
+> creating a cyclic import. … Of course, the best long-term solution would
+> be to remove the dependency from the core `coraza` to `experimental`."
+> — @heaven, ahead of this refactor, in
+> [PR #1478 comment](https://github.com/corazawaf/coraza/pull/1478#issuecomment-3828189778)
+
+## Participants
+
+- @fzipi — author
+
+## Consequences
+
+- **Positive:** `experimental` helpers can use root types directly;
+  reflection-based workarounds become unnecessary.
+- **Negative:** None.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1494
+- Related ADRs: ADR-0034 (rule observer callback — motivating use case)
diff --git a/docs/adr/0037-ctl-whole-collection-exclusion.md b/docs/adr/0037-ctl-whole-collection-exclusion.md
new file mode 100644
index 000000000..4a711c190
--- /dev/null
+++ b/docs/adr/0037-ctl-whole-collection-exclusion.md
@@ -0,0 +1,72 @@
+# ADR-0037: `ctl:ruleRemoveTargetById` whole-collection exclusion
+
+- **Status:** accepted
+- **Date:** 2026-03-05
+- **Version:** v3.4.0
+- **PR:** [#1495](https://github.com/corazawaf/coraza/pull/1495)
+- **Issue(s):** No linked issue
+- **Deciders:** @app/copilot-swe-agent (author), @fzipi (review)
+- **Category:** Parity (closes ModSecurity-compatible exclusion gap)
+
+## Context and Problem
+
+`ctl:ruleRemoveTargetById=RULE_ID;COLLECTION` (no `:key` suffix) had no
+effect — only the keyed form `COLLECTION:key` worked. This meant an operator
+could not say "exclude the entire `ARGS` collection from rule 941390" — a
+common CRS tuning pattern.
+
+Root cause (from the PR body):
+
+> "In `GetField()`, exception matching evaluated:
+> `(ex.KeyRx != nil && ex.KeyRx.MatchString(lkey)) || strings.ToLower(ex.KeyStr) == lkey`
+> When no key is specified, `ex.KeyStr == \"\"` and `ex.KeyRx == nil`. The
+> second condition only matched parameters with an empty name, so all real
+> parameters passed through unfiltered."
+> — PR body
+
+## Decision Drivers
+
+- Match ModSecurity's whole-collection exclusion semantics.
+- Minimal surface change — one additional wildcard branch in the match
+  expression.
+
+## Considered Options
+
+- Treat empty-key exceptions as wildcards in the existing match expression.
+- Introduce a separate code path for whole-collection exclusion.
+
+## Decision Outcome
+
+Chosen: **extend the match expression with an empty-key wildcard branch:**
+
+```go
+(ex.KeyRx != nil && ex.KeyRx.MatchString(lkey)) ||
+  strings.ToLower(ex.KeyStr) == lkey ||
+  (ex.KeyStr == "" && ex.KeyRx == nil)
+```
+
+Tests added at both unit (`TestNoMatchEvaluateBecauseOfWholeCollectionException`)
+and integration (`testing/engine/ctl.go`) levels.
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR thread. The Copilot
+SWE agent authored the change in response to a human-filed bug; reviewers
+approved the one-line fix on the strength of the root-cause analysis in the
+PR body.
+
+## Participants
+
+- @app/copilot-swe-agent — author
+- @fzipi — review
+
+## Consequences
+
+- **Positive:** Whole-collection exclusions work; CRS tuning idiom
+  `ctl:ruleRemoveTargetById=941390;ARGS` now has effect.
+- **Negative:** None — purely additive behaviour.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1495
+- Related ADRs: ADR-0047 (regex keys in `ctl:ruleRemoveTarget*`)
diff --git a/docs/adr/0038-map-for-ruleremovebyid.md b/docs/adr/0038-map-for-ruleremovebyid.md
new file mode 100644
index 000000000..ffd17bb0b
--- /dev/null
+++ b/docs/adr/0038-map-for-ruleremovebyid.md
@@ -0,0 +1,71 @@
+# ADR-0038: `map[int]struct{}` for per-transaction `ruleRemoveByID` lookup
+
+- **Status:** accepted
+- **Date:** 2026-03-06
+- **Version:** v3.4.0
+- **PR:** [#1524](https://github.com/corazawaf/coraza/pull/1524)
+- **Issue(s):** No linked issue
+- **Deciders:** @jptosso, @fzipi
+- **Category:** Perf
+
+## Context and Problem
+
+Every rule evaluation consulted a per-transaction `[]int` of excluded rule
+IDs (populated by `ctl:ruleRemoveById`). In CRS workloads with many exclusion
+directives, the linear scan is hit once per rule per phase.
+
+## Decision Drivers
+
+- O(1) lookup for rule-exclusion checks on a hot path.
+- Lazy allocation so the zero-exclusion case stays allocation-free.
+- No external API change.
+
+## Considered Options
+
+- Sorted slice + binary search.
+- `map[int]struct{}` with lazy init.
+- Bitset / roaring bitmap.
+
+## Decision Outcome
+
+Chosen: **`map[int]struct{}` with lazy init**. Benchmarked on the actual
+hot path (`BenchmarkRuleEvalWithRemovedRules`):
+
+```
+main ([]int linear scan):  135.0 ns/op
+branch (map O(1) lookup):  114.5 ns/op   (~15% faster)
+```
+
+Scales with the number of removed IDs — the improvement grows with real CRS
+exclusion loads.
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR or issue thread
+beyond approvals. The rationale and measurement live in the PR body:
+
+> "`BenchmarkRuleEvalWithRemovedRules` — 1 rule loaded, 100 rule IDs
+> removed via `RemoveRuleByID`, benchmarks `Eval(PhaseRequestHeaders)` …
+> ~15% faster with 100 removed rule IDs. The improvement scales with the
+> number of removed rules and the number of rules evaluated — in CRS
+> workloads with many `ctl:ruleRemoveById` directives and hundreds of
+> rules, each rule evaluation benefits from the O(1) lookup."
+> — @jptosso, [PR body](https://github.com/corazawaf/coraza/pull/1524)
+
+## Participants
+
+- @jptosso — author
+- @fzipi — review
+- @Copilot — PR reviewer bot
+
+## Consequences
+
+- **Positive:** Rule-evaluation hot path drops ~15% for exclusion-heavy
+  configs; no cost when no rules are excluded.
+- **Negative / follow-up:** Paired with [ADR-0041](0041-ruleremovebyid-range-storage.md)
+  (range storage) to also avoid map bloat when ranges are used.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1524
+- Related ADRs: ADR-0041 (`ruleRemoveById` range storage)
diff --git a/docs/adr/0039-bulk-allocate-matchdata.md b/docs/adr/0039-bulk-allocate-matchdata.md
new file mode 100644
index 000000000..e44aa870c
--- /dev/null
+++ b/docs/adr/0039-bulk-allocate-matchdata.md
@@ -0,0 +1,64 @@
+# ADR-0039: Bulk-allocate `MatchData` in collection `Find*` methods
+
+- **Status:** accepted
+- **Date:** 2026-03-11
+- **Version:** v3.4.0
+- **PR:** [#1530](https://github.com/corazawaf/coraza/pull/1530)
+- **Issue(s):** No linked issue
+- **Deciders:** @jptosso, @fzipi
+- **Category:** Perf
+
+## Context and Problem
+
+`Map.FindRegex`, `Map.FindString`, `Map.FindAll` and the `NamedCollectionNames`
+counterparts allocated one `MatchData` per result via `&corazarules.MatchData{}`
+literals. At N results that is N+1 heap allocations. These methods run
+per-request, so the allocator pressure compounds.
+
+## Decision Drivers
+
+- Reduce heap allocations on the rule-evaluation hot path.
+- Preserve public semantics — returned slices are independently owned.
+- Avoid a double regex pass in `FindRegex`.
+
+## Considered Options
+
+- Pre-allocate a contiguous `[]MatchData` buffer and return pointers into it.
+- `sync.Pool` of `MatchData` slices.
+- Leave as-is, rely on escape analysis.
+
+## Decision Outcome
+
+Chosen: **pre-allocated contiguous buffer, pointers into the buffer.**
+
+Benchmark from the PR body:
+
+```
+FindAll    608 → 405 ns/op  (-33%)  26 → 2 allocs (-92%)
+FindRegex 1008 → 965 ns/op  (-4%)   15 → 6 allocs (-60%)
+FindString 495 → 221 ns/op  (-55%)  26 → 2 allocs (-92%)
+```
+
+`FindRegex` was also rewritten to single-pass collection (no regex
+re-evaluation).
+
+## Technical Discussion
+
+No substantive technical discussion recorded beyond the benchmark data. The
+change is localised, covered by `TestFindAllBulkAllocIndependence` and
+siblings to prove results remain independent after the pool redesign.
+
+## Participants
+
+- @jptosso — author
+- @fzipi — review
+
+## Consequences
+
+- **Positive:** Heavy allocation drop on hot-path collection finds; up to
+  55% faster for `FindString`.
+- **Negative / follow-up:** None flagged in review.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1530
diff --git a/docs/adr/0040-crslang-antlr4-buildtag.md b/docs/adr/0040-crslang-antlr4-buildtag.md
new file mode 100644
index 000000000..c53616a19
--- /dev/null
+++ b/docs/adr/0040-crslang-antlr4-buildtag.md
@@ -0,0 +1,61 @@
+# ADR-0040: Gate `crslang` ANTLR4 parser behind a build tag
+
+- **Status:** accepted
+- **Date:** 2026-03-08
+- **Version:** v3.4.0
+- **PR:** [#1536](https://github.com/corazawaf/coraza/pull/1536)
+- **Issue(s):** No linked issue
+- **Deciders:** @app/copilot-swe-agent (author)
+- **Category:** Feature (new experimental parser) + Refactor (binary-size hygiene)
+
+## Context and Problem
+
+The experimental ANTLR4-based SecLang parser (`experimental/seclang/parser_v2.go`)
+pulled in heavy dependencies (`antlr4-go`, `crslang`, `seclang_parser`)
+unconditionally, bloating every default Coraza build even though only a
+handful of developers need the new parser.
+
+## Decision Drivers
+
+- Keep default binary size small — most users don't need the ANTLR4 parser.
+- Still allow opt-in testing and development of the experimental parser.
+- Zero default-behaviour change.
+
+## Considered Options
+
+- Leave dependencies compiled in.
+- Split to a separate module / repository.
+- Gate behind a build tag so the code compiles only when explicitly opted
+  in.
+
+## Decision Outcome
+
+Chosen: **build-tag gate** — `//go:build coraza.experimental.crslang_parser`
+on `parser_v2.go` and its test file. Default builds skip the package
+entirely:
+
+```
+go build -tags=coraza.experimental.crslang_parser ./...
+go test -tags=coraza.experimental.crslang_parser ./experimental/seclang/...
+```
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR thread. The Copilot
+SWE agent authored the refactor; reviewers approved on the strength of the
+binary-size motivation captured in the PR body.
+
+## Participants
+
+- @app/copilot-swe-agent — author
+
+## Consequences
+
+- **Positive:** Default Coraza builds no longer drag in ANTLR4; experimental
+  parser work continues under the tag.
+- **Negative / follow-up:** One more build-tag combination the CI matrix
+  must cover for the experimental parser specifically.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1536
diff --git a/docs/adr/0041-ruleremovebyid-range-storage.md b/docs/adr/0041-ruleremovebyid-range-storage.md
new file mode 100644
index 000000000..092104cd8
--- /dev/null
+++ b/docs/adr/0041-ruleremovebyid-range-storage.md
@@ -0,0 +1,69 @@
+# ADR-0041: `ruleRemoveById` range storage (no expansion)
+
+- **Status:** accepted
+- **Date:** 2026-03-09
+- **Version:** v3.4.0
+- **PR:** [#1538](https://github.com/corazawaf/coraza/pull/1538)
+- **Issue(s):** No linked issue
+- **Deciders:** @app/copilot-swe-agent (author)
+- **Category:** Perf
+
+## Context and Problem
+
+`rangeToInts` iterated every WAF rule and inserted each matching ID into
+the per-transaction removal map one at a time. For broad CRS exclusion
+ranges like `1000-9999`, this churned thousands of allocations per request
+even though the effective filter was just two numbers.
+
+## Decision Drivers
+
+- Avoid thousands of per-request allocations for common CRS ranges.
+- Keep the rule-evaluation skip check cheap.
+- Cover both `ctl:ruleRemoveById` and `ctl:ruleRemoveTargetById` range
+  forms.
+
+## Considered Options
+
+- Expand ranges into the map (status quo, O(range size) allocations).
+- Store ranges separately as `[2]int`; evaluate with a short `len(ranges)`
+  loop.
+- Bitset indexed by rule ID (overkill for a handful of ranges).
+
+## Decision Outcome
+
+Chosen: **store ranges as `[2]int` entries on the transaction; rule-eval
+loop checks both the ID map and the range slice.**
+
+New helpers:
+
+- `parseRange("start-end") → (start, end int)`
+- `parseIDOrRange(...)` — handles single IDs and ranges
+- `Transaction.RemoveRuleByIDRange(start, end)`
+- `Transaction.GetRuleRemoveByIDRanges()` accessor
+- `RuleGroup.rules` eval consults `ruleRemoveByIDRanges` in addition to the
+  ID map.
+
+Pool reuse resets the range slice alongside other per-transaction state.
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR thread. The Copilot
+SWE agent delivered the change in response to a human-filed issue tracked
+in the original prompt block of the PR body.
+
+## Participants
+
+- @app/copilot-swe-agent — author
+
+## Consequences
+
+- **Positive:** A `ctl:ruleRemoveById=1000-9999` directive no longer causes
+  thousands of per-transaction allocations; the range lives as a single
+  `[2]int` entry.
+- **Negative / follow-up:** Rule-eval skip now has two data structures to
+  consult (map + range slice). Both small, overall cost is net-negative.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1538
+- Related ADRs: ADR-0038 (map for `ruleRemoveByID`)
diff --git a/docs/adr/0042-regex-memoize-default-on.md b/docs/adr/0042-regex-memoize-default-on.md
new file mode 100644
index 000000000..d27164de3
--- /dev/null
+++ b/docs/adr/0042-regex-memoize-default-on.md
@@ -0,0 +1,90 @@
+# ADR-0042: Regex memoize enabled by default
+
+- **Status:** accepted
+- **Date:** 2026-03-18
+- **Version:** v3.5.0
+- **PR:** [#1540](https://github.com/corazawaf/coraza/pull/1540)
+- **Issue(s):** No linked issue (follows [ADR-0006](0006-regex-ahocorasick-memoize.md), [ADR-0043](0043-waf-close-per-owner-memoize.md))
+- **Deciders:** @jptosso, @jcchavezs, @fzipi, @app/copilot-swe-agent
+- **Category:** Perf (default-policy shift)
+
+## Context and Problem
+
+The regex + Aho-Corasick memoize cache shipped in v3.0.3 behind the
+`memoize_builders` build tag ([ADR-0006](0006-regex-ahocorasick-memoize.md)).
+Most embedders never knew to set the tag and therefore paid the full
+compile cost per WAF. Now that per-owner tracking and `WAF.Close()` landed
+([ADR-0043](0043-waf-close-per-owner-memoize.md)), the cache can be safely
+default-on.
+
+## Decision Drivers
+
+- Make the default-path fast; don't require a flag to get the obvious win.
+- Refactor the memoize package to pass a `Memoizer` explicitly through
+  `OperatorOptions` so it is testable and injectable.
+- Offer `coraza.no_memoize` as an explicit opt-out.
+
+## Considered Options
+
+- Leave opt-in.
+- Flip the tag to opt-out (`coraza.no_memoize`).
+- Default-on, no opt-out.
+
+## Decision Outcome
+
+Chosen: **default-on with `coraza.no_memoize` opt-out.**
+
+The build tag `memoize_builders` no longer exists. `OperatorOptions` grows a
+`Memoizer` field (zero value = no memoization, backwards compatible).
+
+## Technical Discussion
+
+**Caddy validation was a merge gate.** @jcchavezs asked for end-to-end
+validation with the Caddy integration:
+
+> "We need to extensively test this with Caddy before merging."
+> — @jcchavezs ([comment](https://github.com/corazawaf/coraza/pull/1540#issuecomment-4047246804))
+
+@fzipi confirmed the companion Caddy PR:
+
+> "@jcchavezs Added https://github.com/corazawaf/coraza-caddy/pull/275. Can
+> you take a look?"
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1540#issuecomment-4063209206))
+
+**TinyGo CI stalled** because the scale benchmarks that now ran on default
+builds are extremely slow on TinyGo's regex engine. @fzipi captured the
+exact arithmetic:
+
+> "**`TestCacheBoundedWithClose`** — 100 cycles × 300 patterns =
+> **30,000 `regexp.Compile` calls** under TinyGo (each `Release` clears the
+> cache, so every cycle recompiles all 300 patterns). … TinyGo's regex
+> engine is dramatically slower than Go's, so these scale tests were not a
+> good fit for the default CI matrix"
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1540#issuecomment-4064049379))
+
+The tests were reshaped to fit TinyGo timing before the PR merged.
+
+**Coverage and lint** drove two follow-up Copilot PRs (#1555, #1556).
+
+## Participants
+
+- @jptosso — author
+- @jcchavezs — review (Caddy integration gate)
+- @fzipi — review (TinyGo CI triage, coverage driver)
+- @app/copilot-swe-agent — orchestrated coverage + lint follow-ups
+
+## Consequences
+
+- **Positive:** All embedders get the memoize speedup by default; operator
+  plugins receive a `Memoizer` explicitly and are easier to test.
+- **Negative / follow-up:** TinyGo scale benchmarks were reshaped because
+  the slower regex engine can't run them in CI time. Backwards-compat for
+  out-of-tree operator plugins is maintained via the zero-value-Memoizer
+  behaviour.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1540
+- Caddy validation: https://github.com/corazawaf/coraza-caddy/pull/275
+- Related ADRs: ADR-0006 (initial memoize), ADR-0043 (`WAF.Close()` +
+  per-owner tracking)
diff --git a/docs/adr/0043-waf-close-per-owner-memoize.md b/docs/adr/0043-waf-close-per-owner-memoize.md
new file mode 100644
index 000000000..d3802b6c9
--- /dev/null
+++ b/docs/adr/0043-waf-close-per-owner-memoize.md
@@ -0,0 +1,85 @@
+# ADR-0043: `WAF.Close()` + per-owner memoize cache tracking
+
+- **Status:** accepted
+- **Date:** 2026-03-11
+- **Version:** v3.5.0
+- **PR:** [#1541](https://github.com/corazawaf/coraza/pull/1541)
+- **Issue(s):** No linked issue (follows [ADR-0006](0006-regex-ahocorasick-memoize.md))
+- **Deciders:** @jptosso
+- **Category:** Feature (new lifecycle API)
+
+## Context and Problem
+
+The memoize cache ([ADR-0006](0006-regex-ahocorasick-memoize.md)) was
+process-global with no way to release entries when a specific WAF instance
+was destroyed. In long-running processes that construct and discard many
+WAFs (reload-heavy embedders, multi-tenant hosts), this was a slow leak.
+ADR-0006 had noted the absence of `WAF.Close()` as the reason for the
+global-plus-experimental-reset shape; this PR fixes the root cause.
+
+## Decision Drivers
+
+- Release compiled regex/Aho-Corasick memory when a WAF goes away.
+- Preserve the speed benefit of the shared cache across live WAFs.
+- Safe concurrent access during Close (tombstone-based cleanup).
+- Minimal API break — expose via `experimental.WAFCloser` so stable
+  consumers are unaffected.
+
+## Considered Options
+
+- Simple refcount per entry.
+- Per-owner (per-WAF) `uint64` IDs tracked against cache entries;
+  `Release(owner)` clears the owner's refs with tombstones.
+- Full WAF-scoped cache (no sharing across WAFs — kills the benefit).
+
+## Decision Outcome
+
+Chosen: **per-owner ID tracking + tombstone-based `Release`**, exposed via
+`experimental.WAFCloser.Close()`. Two helpers: `memoize.Release(ownerID)`
+and `memoize.Reset()`.
+
+Benchmark evidence from the PR body:
+
+```
+BenchmarkCompileWithoutMemoize/WAFs=100  54,030,097 ns/op
+BenchmarkCompileWithMemoize/WAFs=100      2,227,625 ns/op   24× speedup
+
+CRS cold→warm WAF: 58ms → 9ms  (6.3× speedup)
+Close() memory release: 28MiB peak → 1MiB after Close()
+```
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR or issue thread
+beyond reviewer approvals. The PR body is the design document:
+
+> "Add per-owner tracking to the memoize cache using `uint64` owner IDs
+> for efficient WAF lifecycle management. Implement `WAF.Close()` (via
+> `experimental.WAFCloser`) to release cached regex/aho-corasick entries
+> when a WAF instance is destroyed. Add `Release()` and `Reset()`
+> functions with tombstone-based cleanup to safely handle concurrent
+> access."
+> — @jptosso, [PR body](https://github.com/corazawaf/coraza/pull/1541)
+
+> "At 100 WAFs: **24× speedup** (54ms → 2.2ms). CRS integration: Cold vs
+> warm WAF compilation: 58ms vs 9ms (**6.3× speedup**). Close() memory
+> release: 28MiB peak → 1MiB after Close() (**27MiB released**)."
+> — @jptosso, [PR body](https://github.com/corazawaf/coraza/pull/1541)
+
+## Participants
+
+- @jptosso — author
+
+## Consequences
+
+- **Positive:** Reload-heavy or multi-tenant embedders can free ~27MiB per
+  WAF after `Close()`; first-WAF compile cost is still paid once, shared
+  across all subsequent WAFs.
+- **Negative / follow-up:** Release is O(entries × owners-to-clean) at
+  tombstone-scan time — benchmarked at ~900μs for 300 entries × 100 owners,
+  acceptable for a rare-event path.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1541
+- Related ADRs: ADR-0006 (memoize initial), ADR-0042 (default-on)
diff --git a/docs/adr/0044-prefix-transformation-cache.md b/docs/adr/0044-prefix-transformation-cache.md
new file mode 100644
index 000000000..62dee8507
--- /dev/null
+++ b/docs/adr/0044-prefix-transformation-cache.md
@@ -0,0 +1,64 @@
+# ADR-0044: Prefix-based transformation cache with inline values
+
+- **Status:** accepted
+- **Date:** 2026-03-11
+- **Version:** v3.5.0
+- **PR:** [#1544](https://github.com/corazawaf/coraza/pull/1544)
+- **Issue(s):** No linked issue
+- **Deciders:** @fzipi, @jptosso
+- **Category:** Perf
+
+## Context and Problem
+
+Two rules that share a common transformation prefix
+(e.g. `t:lowercase,t:urlDecodeUni` and `t:lowercase`) redundantly recomputed
+the prefix. The existing cache stored only the final result, not the
+intermediate steps, and used pointer values (extra heap allocs).
+
+## Decision Drivers
+
+- Reuse intermediate transformation results across rules.
+- Fix `ClearTransformations` (t:none) so it resets the cached ID.
+- Cut heap allocations on the request hot path.
+
+## Considered Options
+
+- Cache only the final result per rule (status quo).
+- Cache every intermediate step, keyed by the transformation chain prefix,
+  with inline values.
+
+## Decision Outcome
+
+Chosen: **cache every intermediate step with inline values**, adding a
+`transformationPrefixIDs` field to `Rule` for backward prefix search. The
+key insight: transformations are deterministic, so two rules sharing the
+first K transformations can share the cached result after step K.
+
+PR-body benchmark against full CRS v4 (8 runs, benchstat):
+
+- Allocations: −2% (small payloads) to −19% (30 args)
+- Memory: −2% to −12%
+- Timing: −5% small/large, neutral mid-range
+
+No regressions on any metric.
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR thread. The design
+and the benchmark results are in the PR body; reviewers approved on that
+basis.
+
+## Participants
+
+- @fzipi — author
+- @jptosso — review
+
+## Consequences
+
+- **Positive:** Fewer redundant transformation runs across CRS; inline
+  values avoid heap allocation; `t:none` semantics corrected.
+- **Negative / follow-up:** None noted.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1544
diff --git a/docs/adr/0045-findstringsubmatchindex-noalloc.md b/docs/adr/0045-findstringsubmatchindex-noalloc.md
new file mode 100644
index 000000000..d81cec272
--- /dev/null
+++ b/docs/adr/0045-findstringsubmatchindex-noalloc.md
@@ -0,0 +1,65 @@
+# ADR-0045: `FindStringSubmatchIndex` replaces `FindStringSubmatch` on capture path
+
+- **Status:** accepted
+- **Date:** 2026-03-11
+- **Version:** v3.5.0
+- **PR:** [#1547](https://github.com/corazawaf/coraza/pull/1547)
+- **Issue(s):** Extracted from [#1534](https://github.com/corazawaf/coraza/pull/1534)
+- **Deciders:** @jptosso, @fzipi
+- **Category:** Perf
+
+## Context and Problem
+
+`@rx` captures used `FindStringSubmatch`, which allocates a `[]string` per
+match. With CRS loading hundreds of `@rx` rules, this allocation compounds
+across every capturing evaluation on every request.
+
+## Decision Drivers
+
+- Eliminate the per-match `[]string` allocation.
+- Keep behaviour identical for all capture cases, including
+  non-participating optional groups.
+- Ship independently of the build-tagged prefilter work in
+  [ADR-0049](0049-rx-literal-prefilter.md).
+
+## Considered Options
+
+- Keep `FindStringSubmatch` and tolerate the allocs.
+- Switch to `FindStringSubmatchIndex`, materialise substrings as slices of
+  the original input (zero-alloc).
+
+## Decision Outcome
+
+Chosen: **`FindStringSubmatchIndex` + slice-into-input substrings**,
+passing `""` for non-participating optional groups (negative index).
+
+PR-body benchmark:
+
+```
+FindStringSubmatch       355.9 ns/op  128 B/op  2 allocs
+FindStringSubmatchIndex  316.0 ns/op   64 B/op  1 alloc     (~11% faster)
+```
+
+Allocations halved; memory halved.
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR thread. The code
+change is small and self-contained; reviewers approved on the benchmark
+evidence.
+
+## Participants
+
+- @jptosso — author
+- @fzipi — review
+
+## Consequences
+
+- **Positive:** Always-on perf win on the rule-evaluation capture path;
+  this shipped outside any build tag because it is semantically identical.
+- **Negative:** None.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1547
+- Extracted from: https://github.com/corazawaf/coraza/pull/1534
diff --git a/docs/adr/0046-secuploadkeepfiles-directive.md b/docs/adr/0046-secuploadkeepfiles-directive.md
new file mode 100644
index 000000000..fa98de49a
--- /dev/null
+++ b/docs/adr/0046-secuploadkeepfiles-directive.md
@@ -0,0 +1,86 @@
+# ADR-0046: `SecUploadKeepFiles` directive
+
+- **Status:** accepted
+- **Date:** 2026-03-19
+- **Version:** v3.5.0
+- **PR:** [#1557](https://github.com/corazawaf/coraza/pull/1557)
+- **Issue(s):** [#1550](https://github.com/corazawaf/coraza/issues/1550)
+- **Deciders:** @fzipi, @M4tteoP, @Copilot
+- **Category:** Parity (ModSecurity parity)
+
+## Context and Problem
+
+ModSecurity exposes `SecUploadKeepFiles On|Off|RelevantOnly` to control
+whether uploaded multipart files are retained or deleted after processing.
+Coraza had a parser entry for the directive but the `RelevantOnly` branch
+and the lifecycle plumbing were missing; deletion was unconditional.
+
+## Decision Drivers
+
+- ModSecurity parity.
+- Respect the `RelevantOnly` semantics: keep files only when rules matched.
+- TinyGo / Wasm builds have no filesystem access — gate cleanly under the
+  existing `environment.HasAccessToFS` check.
+
+## Considered Options
+
+- Implement `On`/`Off` only.
+- Implement all three states, mirroring ModSecurity semantics.
+
+## Decision Outcome
+
+Chosen: **implement all three states** — `On`, `Off` (default),
+`RelevantOnly`. File operations are already guarded by
+`environment.HasAccessToFS`, so the directive is safe on Wasm builds.
+
+> "Also, ModSec requires `SecUploadKeepFiles` directive to work with
+> `SecUploadDir`: 'This directive requires the storage directory to be
+> defined (using SecUploadDir).' Should we distinguish the dir where we
+> save persisted files from the tmp dir where we save the tmp ones? If so,
+> we should take care of `SecUploadDir` and enforce the same requirement
+> of ModSec"
+> — @M4tteoP ([comment](https://github.com/corazawaf/coraza/pull/1557#issuecomment-4067770063))
+
+> "Makes sense. Added in 25b636d0"
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1557#issuecomment-4071743033))
+
+## Technical Discussion
+
+**Copilot flagged a consistency gap** on directive error handling:
+
+> "`directiveSecUploadKeepFiles` is the only nearby directive that doesn't
+> check for empty `options.Opts` and return `errEmptyOptions`. With the
+> current code, an empty value yields an 'invalid upload keep files status'
+> error instead of the consistent 'expected options' error used by most
+> directives in this file."
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1557#discussion_r2939770730))
+
+The author applied the guard.
+
+**A lint break from a Copilot suggestion** caused a chained follow-up:
+
+> "@copilot Fix the lint pipeline, as your latest suggestions broke it."
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1557#issuecomment-4076746486))
+
+Follow-up landed as PR #1560.
+
+## Participants
+
+- @fzipi — author
+- @M4tteoP — review (drove `SecUploadDir` alignment)
+- @Copilot — reviewer bot (directive error-handling consistency)
+- @app/copilot-swe-agent — follow-up lint fix (#1560)
+
+## Consequences
+
+- **Positive:** ModSecurity parity; operators get `RelevantOnly` to keep
+  only suspicious uploads for post-hoc forensics.
+- **Negative / follow-up:** Full ModSecurity spec requires pairing with
+  `SecUploadDir`; check was added. Wasm builds silently ignore the
+  directive (no FS access).
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1557
+- Issue: https://github.com/corazawaf/coraza/issues/1550
+- Follow-up lint fix: https://github.com/corazawaf/coraza/pull/1560
diff --git a/docs/adr/0047-regex-in-ctl-ruleremovetarget.md b/docs/adr/0047-regex-in-ctl-ruleremovetarget.md
new file mode 100644
index 000000000..c309765d1
--- /dev/null
+++ b/docs/adr/0047-regex-in-ctl-ruleremovetarget.md
@@ -0,0 +1,106 @@
+# ADR-0047: Regex keys in `ctl:ruleRemoveTarget{ById,ByTag,ByMsg}`
+
+- **Status:** accepted
+- **Date:** 2026-03-21
+- **Version:** v3.5.0
+- **PR:** [#1561](https://github.com/corazawaf/coraza/pull/1561)
+- **Issue(s):** No linked issue (parallels earlier attempt [#1207](https://github.com/corazawaf/coraza/pull/1207))
+- **Deciders:** @fzipi, @M4tteoP, @app/copilot-swe-agent
+- **Category:** Feature
+
+## Context and Problem
+
+`ctl:ruleRemoveTargetById` and siblings accepted only exact string keys.
+For dynamically indexed JSON args (`ARGS:json.0.field`,
+`ARGS:json.1.field`, …), this forced operators to either disable the rule
+entirely or exclude the whole collection. Regex-delimited keys
+(`ARGS:/^json\.\d+\.field$/`) close this gap.
+
+## Decision Drivers
+
+- Per-URI exclusions for dynamically-indexed variables.
+- Reuse logic from an earlier attempt (#1207) — notably its `HasRegex`
+  helper and escape-slash handling.
+- Dedupe compiled regexes across rules that share the same pattern
+  (memoize).
+
+## Considered Options
+
+- Implement only in `ctl.go` with ad-hoc regex detection.
+- Extract `HasRegex` into `internal/strings` and reuse in `rule.go` +
+  `ctl.go`.
+- Pass the memoizer through `OperatorOptions` to dedupe
+  `regexp.MustCompile` calls.
+
+## Decision Outcome
+
+Chosen: **extracted `HasRegex` + memoizer-based regex dedup**.
+
+- `internal/strings/strings.go` — new `HasRegex(s string) (bool, string)`
+  handling `/user\/` (literal) vs `/user\\/` (regex) correctly.
+- `ctlFn.Init` type-asserts `plugintypes.RuleMetadata` to `*corazawaf.Rule`
+  to extract its memoizer and pass it into `parseCtl`.
+- `RemoveRuleTargetByID` grows a `keyRx *regexp.Regexp` parameter stored
+  directly in `ruleVariableParams`.
+
+Example from the PR:
+
+```apache
+SecRule REQUEST_URI "@beginsWith /api/jobs" \
+  "id:100100,phase:1,pass,nolog,\
+   ctl:ruleRemoveTargetById=932125;ARGS:/^json\.\d+\.jobdescription$/"
+```
+
+## Technical Discussion
+
+**Reuse earlier work.** @fzipi steered the Copilot agent toward #1207's
+`HasRegex`:
+
+> "@copilot+claude-sonnet-4.6 Read https://github.com/corazawaf/coraza/pull/1207
+> as it is another implementation of the same feature. In particular, you
+> could take from there the `HasRegex` func (and tests) that will make the
+> code more easy to read."
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1561#issuecomment-4089545322))
+
+**Memoize the compiled regex.**
+
+> "@copilot Wouldn't this benefit from memoization?"
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1561#discussion_r2957185229))
+
+> "Yes, great suggestion. Added a public `Memoizer()` getter on `*Rule`,
+> updated `parseCtl` to accept a `plugintypes.Memoizer` parameter; when
+> non-nil, it calls `memoizer.Do(rxPattern, ...)` so identical patterns
+> across rules share a single compiled `*regexp.Regexp`"
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1561#discussion_r2957227192))
+
+**POST JSON body test coverage.** @fzipi asked for a test that exercises
+the JSON-body-processor path, where `json.0.desc` → `json.1.desc` etc.:
+
+> "@copilot+claude-sonnet-4.6 While the test 'ruleRemoveTargetById regex
+> key' targets GET arguments, a test that does POST using json formatted
+> input would also be good to have."
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1561#issuecomment-4089655772))
+
+Four integration test stages cover all three `ctl` variants plus the
+POST JSON body path.
+
+## Participants
+
+- @app/copilot-swe-agent — author
+- @fzipi — review (drove reuse, memoize, POST test coverage, docs)
+- @M4tteoP — review
+
+## Consequences
+
+- **Positive:** Operators can exclude dynamically-indexed variables
+  precisely without nuking the rule or collection; compiled regex is
+  memoized once per unique pattern across rules.
+- **Negative / follow-up:** Regex exception matching carries a per-call
+  cost (benchmarked); acceptable relative to the alternative of disabling
+  rules wholesale.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1561
+- Earlier attempt: https://github.com/corazawaf/coraza/pull/1207
+- Related ADRs: ADR-0037 (whole-collection exclusion)
diff --git a/docs/adr/0048-ndjson-body-processor.md b/docs/adr/0048-ndjson-body-processor.md
new file mode 100644
index 000000000..bbc48ab1e
--- /dev/null
+++ b/docs/adr/0048-ndjson-body-processor.md
@@ -0,0 +1,81 @@
+# ADR-0048: NDJSON (JSON Stream) body processor
+
+- **Status:** accepted
+- **Date:** 2026-03-21
+- **Version:** v3.5.0
+- **PR:** [#1563](https://github.com/corazawaf/coraza/pull/1563)
+- **Issue(s):** No linked issue
+- **Deciders:** @app/copilot-swe-agent (author), @fzipi
+- **Category:** Feature
+
+## Context and Problem
+
+NDJSON / JSON Lines / RFC 7464 (JSON Sequence) streams carry one JSON
+record per line. Applied to WAF processing, each record should be
+evaluated independently — otherwise a malicious record hiding mid-stream
+requires buffering the whole body just to catch it.
+
+## Decision Drivers
+
+- Stream-native inspection: evaluate rules per record, don't buffer.
+- Preserve cross-record state (TX variables, anomaly scores) across
+  evaluations.
+- Autodetect RFC 7464 by peeking for RS (`0x1E`) byte.
+- Enforce the same JSON depth limit as the regular JSON processor
+  ([ADR-0030](0030-secrequestbodyjsondepthlimit.md)).
+
+## Considered Options
+
+- Buffer the whole stream, then run rules once.
+- Line-by-line processing, evaluate per record, clear and repopulate
+  `ARGS_POST` between records.
+
+## Decision Outcome
+
+Chosen: **line-by-line processing with per-record rule evaluation.**
+
+- `bufio.Scanner` with configurable max token size.
+- `json.<N>.<field>` indexing pattern (same conventions as the JSON body
+  processor).
+- Registered under aliases `JSONSTREAM`, `NDJSON`, `JSONLINES`.
+- `processRequestBodyStreaming` / `processResponseBodyStreaming` on
+  `Transaction` make `Eval(Phase2)` safe to call multiple times:
+  `AllowTypePhase`, `Skip`, and transformation cache all reset between
+  calls.
+- `experimental.StreamingTransaction` exposes
+  `ProcessRequestBodyFromStream(input, output)` /
+  `ProcessResponseBodyFromStream(input, output)` for integrators building
+  streaming middleware.
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR thread. The Copilot
+SWE agent delivered the change end-to-end; the design and e2e tests are
+captured in the PR body. Reviewers approved on the strength of the
+streaming-relay API design and per-record test coverage:
+
+- clean stream → 200
+- stream with malicious record → 403
+- `application/jsonlines` content type
+- SQLi inside a record field → 403
+- blank lines ignored
+- non-NDJSON content type unaffected
+
+## Participants
+
+- @app/copilot-swe-agent — author
+- @fzipi — review
+
+## Consequences
+
+- **Positive:** Streaming APIs emitting NDJSON can be protected without
+  per-connection buffering; cross-record anomaly-score accumulation works.
+- **Negative / follow-up:** `processRequestBodyStreaming` mutates
+  `ARGS_POST` between records — embedders relying on post-phase argument
+  state will see only the last record's values.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1563
+- Related ADRs: ADR-0010 (raw body processor), ADR-0030
+  (`SecRequestBodyJsonDepthLimit`)
diff --git a/docs/adr/0049-rx-literal-prefilter.md b/docs/adr/0049-rx-literal-prefilter.md
new file mode 100644
index 000000000..3b592f883
--- /dev/null
+++ b/docs/adr/0049-rx-literal-prefilter.md
@@ -0,0 +1,92 @@
+# ADR-0049: `@rx` operator literal pre-filter (build-tag opt-in)
+
+- **Status:** accepted
+- **Date:** 2026-03-31
+- **Version:** v3.6.0 (gated by `coraza.rule.rx_prefilter`)
+- **PR:** [#1534](https://github.com/corazawaf/coraza/pull/1534)
+- **Issue(s):** No linked issue (superseded by runtime directive — [ADR-0050](0050-secrxprefilter-directive.md))
+- **Deciders:** @jptosso, @fzipi, @M4tteoP
+- **Category:** Perf
+
+## Context and Problem
+
+`@rx` is the largest hot path in Coraza. CRS loads hundreds of `@rx` rules
+and 95%+ of evaluations return `false` for benign traffic — but the regex
+engine still runs to completion before concluding "no match". Compile-time
+analysis can cheaply short-circuit clear non-matches.
+
+## Decision Drivers
+
+- Skip the regex engine entirely when a pattern's required literals are
+  absent from the input.
+- **Safety first:** a prefilter may only say "definitely no match" or
+  "maybe match" — any uncertainty must fall through to the full regex.
+  A missed attack is worse than a missed optimisation.
+- Opt-in via a build tag so existing deployments don't change behaviour
+  silently.
+
+## Considered Options
+
+- Ship only the allocation reduction from
+  [ADR-0045](0045-findstringsubmatchindex-noalloc.md).
+- Add compile-time AST walking to extract min-length + required-literal
+  pre-checks, gated by build tag.
+
+## Decision Outcome
+
+Chosen: **build-tag-gated AST prefilter with three optimizations:**
+
+1. **Minimum match length check** — walk `regexp/syntax` AST to compute
+   minimum input bytes; skip if `len(input) < minLen`.
+2. **Required literal pre-filtering (highest impact)** — extract literals
+   that *must* appear; check with `strings.Contains` (single) or
+   Aho-Corasick (alternation), reusing the `@pm` dependency.
+3. **Allocation reduction in capturing path** — `FindStringSubmatchIndex`,
+   shipped always-on in [ADR-0045](0045-findstringsubmatchindex-noalloc.md).
+
+**Safety rule** quoted from the PR body:
+
+> "When in doubt, fall back to the regex. The prefilter is purely an
+> optimization. If there is **any** uncertainty about whether the input
+> could match — non-ASCII input with `(?i)` patterns, unknown AST nodes,
+> unparseable patterns, or any other ambiguity — we return 'maybe match'
+> and let the full regex engine make the final decision. **A missed
+> optimization is free; a missed attack is a security vulnerability.**"
+> — @jptosso, PR body
+
+**Unicode case-folding safety.** The prefilter only knows ASCII case
+folding (A-Z ↔ a-z), so `(?i)` patterns that see non-ASCII input
+conservatively return "maybe match" to avoid missing `s`↔`ſ`, `k`↔`K`
+edge cases:
+
+> "In practice, 99%+ of WAF traffic is pure ASCII, so the optimization
+> still applies for the vast majority of requests."
+> — @jptosso, PR body
+
+## Technical Discussion
+
+Runtime vs. build-time activation was the unresolved question. It was
+deferred to a separate PR ([ADR-0050](0050-secrxprefilter-directive.md))
+because build-tag gating made testing harder for embedders wanting
+per-instance opt-in without a rebuild.
+
+## Participants
+
+- @jptosso — author
+- @fzipi — review
+- @M4tteoP — review (followed up with the runtime directive)
+
+## Consequences
+
+- **Positive:** For typical traffic, most `@rx` evaluations short-circuit
+  before touching the regex engine.
+- **Negative / follow-up:** Build-tag gating requires a rebuild to toggle —
+  addressed by [ADR-0050](0050-secrxprefilter-directive.md)
+  (`SecRxPreFilter` directive) in v3.7.0.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1534
+- Related ADRs: ADR-0045 (FindStringSubmatchIndex), ADR-0050
+  (`SecRxPreFilter` directive), ADR-0052 (Aho-Corasick → bitmap matcher
+  for this prefilter)
diff --git a/docs/adr/0050-secrxprefilter-directive.md b/docs/adr/0050-secrxprefilter-directive.md
new file mode 100644
index 000000000..8bc42e619
--- /dev/null
+++ b/docs/adr/0050-secrxprefilter-directive.md
@@ -0,0 +1,100 @@
+# ADR-0050: `SecRxPreFilter` runtime directive for `@rx` pre-filtering
+
+- **Status:** accepted
+- **Date:** 2026-04-05
+- **Version:** v3.7.0 (directive default `Off`)
+- **PR:** [#1589](https://github.com/corazawaf/coraza/pull/1589)
+- **Issue(s):** No linked issue (supersedes build-tag gating in [ADR-0049](0049-rx-literal-prefilter.md))
+- **Deciders:** @M4tteoP, @jptosso, @fzipi, @Copilot, @coderabbitai
+- **Category:** Feature
+
+## Context and Problem
+
+The `@rx` literal pre-filter ([ADR-0049](0049-rx-literal-prefilter.md))
+was behind the `coraza.rule.rx_prefilter` build tag. Enabling it required
+a rebuild, which made per-instance rollout and A/B testing hard in
+production settings.
+
+## Decision Drivers
+
+- Let operators toggle the prefilter per WAF instance without a rebuild.
+- Preserve the build tag for Coraza's own CI (test both codepaths).
+- Keep default behaviour conservative (directive `Off`) since the
+  prefilter is marked experimental.
+
+## Considered Options
+
+- Keep build-tag only.
+- Runtime directive, `On` by default.
+- Runtime directive, `Off` by default, build tag flips the default to `On`
+  for CI/test purposes only.
+
+## Decision Outcome
+
+Chosen: **runtime directive, default `Off`, build tag remains but only
+changes the default for tests.** The directive is explicitly labelled
+`EXPERIMENTAL` in the recommended config + docs.
+
+> "I added a warning Experimental line on both the recommended and docs
+> comments, plus some rewording."
+> — @M4tteoP ([comment](https://github.com/corazawaf/coraza/pull/1589#issuecomment-4188929785))
+
+## Technical Discussion
+
+**Copilot's catches shaped the doc and tests:**
+
+Concurrency test that didn't actually exercise the prefilter:
+
+> "`TestPrefilterConcurrentSafety` is intended to validate the prefilter
+> closure/Aho-Corasick behavior under concurrency, but `newRX` is
+> constructed without `RxPreFilterEnabled: true`, so the operator will not
+> build/use the prefilter at all."
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1589#discussion_r3032578657))
+
+Default vs. tag-dependent semantics:
+
+> "The directive doc comment says `Default: Off`, but `NewWAF()` sets
+> `RxPreFilterEnabled` from `defaultRxPreFilterEnabled`, which becomes
+> `true` when built with `coraza.rule.rx_prefilter`. Consider updating
+> this comment to reflect that the default can be tag-dependent (or
+> explicitly note that the build tag is test-only and changes the
+> default)."
+> — @Copilot ([review](https://github.com/corazawaf/coraza/pull/1589#discussion_r3032578690))
+
+Runtime-vs-compile-time wording in the recommended config:
+
+> "Line 13 currently describes `SecRxPreFilter` as compile-time behavior,
+> but this directive is runtime-configurable. This can confuse operators
+> reading the recommended config."
+> — @coderabbitai[bot] ([review](https://github.com/corazawaf/coraza/pull/1589#discussion_r3034771145))
+
+Both were applied.
+
+**Should a warning fire on use?** @jptosso asked; @fzipi and @M4tteoP
+opted for the `EXPERIMENTAL` comment in the recommended config instead of
+a runtime warn log:
+
+> "Should we send a warning telling the user this is an experimental
+> feature?"
+> — @jptosso ([comment](https://github.com/corazawaf/coraza/pull/1589#issuecomment-4185780082))
+
+## Participants
+
+- @M4tteoP — author
+- @jptosso — review (asked about experimental-warning)
+- @fzipi — review (approved wording approach)
+- @Copilot — reviewer bot (drove doc + test fixes)
+- @coderabbitai[bot] — reviewer (wording)
+
+## Consequences
+
+- **Positive:** Operators can enable / disable the prefilter without a
+  rebuild; Coraza's CI still exercises both codepaths by toggling the tag.
+- **Negative / follow-up:** Two sources of truth for the default
+  (directive + build tag); clearly documented as test-only.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1589
+- Related ADRs: ADR-0049 (rx literal prefilter), ADR-0052 (Aho-Corasick →
+  bitmap matcher)
diff --git a/docs/adr/0051-audit-log-part-j.md b/docs/adr/0051-audit-log-part-j.md
new file mode 100644
index 000000000..09ae1d650
--- /dev/null
+++ b/docs/adr/0051-audit-log-part-j.md
@@ -0,0 +1,100 @@
+# ADR-0051: Audit log Part J (uploaded files metadata)
+
+- **Status:** accepted
+- **Date:** 2026-04-03
+- **Version:** v3.7.0
+- **PR:** [#1591](https://github.com/corazawaf/coraza/pull/1591)
+- **Issue(s):** No linked issue
+- **Deciders:** @fzipi, @M4tteoP, @coderabbitai
+- **Category:** Parity (ModSecurity v2 Part J parity)
+
+## Context and Problem
+
+ModSecurity v2 defines `Part J` of `SecAuditLogParts` as a list of
+uploaded-file metadata:
+
+```
+1,12345,"image.png","image/png"
+2,67890,"doc.pdf","application/pdf"
+Total,80235
+```
+
+Coraza documented Part J but emitted nothing; uploaded-file metadata was
+being folded into Part C in a way that wasn't spec-compliant.
+
+## Decision Drivers
+
+- ModSecurity v2 format parity for audit-log consumers that already know
+  Part J.
+- Safe escaping of filenames / MIME types (`strconv.Quote`).
+- Fallback MIME string when Content-Type missing:
+  `<Unknown Content-Type>`.
+
+## Considered Options
+
+- Leave file metadata in Part C.
+- Move metadata to Part J per spec, keep native/JSON/OCSF formats in sync.
+
+## Decision Outcome
+
+Chosen: **move to Part J, emit in ModSecurity v2 native format**, use
+`strconv.Quote` for safe escaping. JSON format inherits the data via
+struct marshalling; OCSF already read from `Request().Files()` so it gains
+the data automatically.
+
+## Technical Discussion
+
+**Implementation notes from the PR body:**
+
+> "**Native format** matches ModSecurity v2's Part J output from
+> `msc_logging.c` … **JSON format** gets file data automatically via struct
+> marshaling — no extra code needed. **OCSF format** already had file
+> observable logic in `formats_ocsf.go:110` that reads from
+> `Request().Files()`, so it works once the data is populated."
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1591#issuecomment-4183561086))
+
+**TODO cleanup** @M4tteoP asked:
+
+> "Is this still a todo? Should it be revisited and just become code
+> documentation?"
+> — @M4tteoP ([review](https://github.com/corazawaf/coraza/pull/1591#discussion_r3033682654))
+
+> "Converted to a concise documentation note — no longer a TODO, just
+> describes what Part I would do (still not implemented)."
+> — @fzipi ([review](https://github.com/corazawaf/coraza/pull/1591#discussion_r3034070981))
+
+**Version tag on docs:**
+
+> "Also `internal/seclang/directives.go directiveSecAuditLogParts`
+> documentation should be updated: 'not implemented yet.' → 'Available
+> from Coraza v3.7.0' or similar"
+> — @M4tteoP ([review](https://github.com/corazawaf/coraza/pull/1591#discussion_r3033700886))
+
+Applied.
+
+**Error-handling discipline on size parsing:**
+
+> "`strconv.ParseInt` for file sizes now checks the error and logs a debug
+> message with the file name, raw value, and parse error via
+> `tx.DebugLogger()`. Size defaults to 0 on failure."
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1591#issuecomment-4183650976))
+
+## Participants
+
+- @fzipi — author
+- @M4tteoP — review (TODO cleanup, version-tag in docs)
+- @coderabbitai[bot] — reviewer (MIME assertion in tests)
+
+## Consequences
+
+- **Positive:** Coraza emits ModSecurity v2 Part J verbatim; SIEM
+  pipelines that parse Part J work out of the box across native, JSON, and
+  OCSF formats.
+- **Negative / follow-up:** Part I (fake urlencoded body for multipart
+  requests) is still unimplemented and documented as such.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1591
+- ModSecurity reference: Part J in `msc_logging.c`
+- Related ADRs: ADR-0005 (formatter interface), ADR-0018 (OCSF)
diff --git a/docs/adr/0052-ahocorasick-to-bitmap.md b/docs/adr/0052-ahocorasick-to-bitmap.md
new file mode 100644
index 000000000..ed24fc49d
--- /dev/null
+++ b/docs/adr/0052-ahocorasick-to-bitmap.md
@@ -0,0 +1,96 @@
+# ADR-0052: Replace Aho-Corasick with indexed-bitmap matcher for `@rx` `anyRequired` prefilter
+
+- **Status:** accepted
+- **Date:** 2026-04-09
+- **Version:** unreleased (post-v3.7.0)
+- **PR:** [#1597](https://github.com/corazawaf/coraza/pull/1597)
+- **Issue(s):** No linked issue
+- **Deciders:** @soujanyanmbri, @fzipi, @coderabbitai
+- **Category:** Perf
+
+## Context and Problem
+
+The `@rx` prefilter ([ADR-0049](0049-rx-literal-prefilter.md)) used
+Aho-Corasick for `anyRequired` alternations. Aho-Corasick scans at O(H)
+with non-trivial allocation. A Wu-Manber-style indexed-bitmap matcher can
+do sub-linear scans with zero match-time allocations.
+
+Two additional structural issues were found:
+
+1. Go's `regexp/syntax.Simplify()` rewrites `(select|sleep|substr)` into
+   a trie with a 1-byte shared prefix. The old extractor saw the short
+   prefix, returned `nil`, and built no prefilter at all.
+2. `anyRequired` sets nested inside `OpConcat` nodes (e.g.
+   `(?:^|["':;=])\s*(?:select|union|drop)`) were discarded.
+
+## Decision Drivers
+
+- Faster `anyRequired` scanning; zero-alloc match path.
+- Recover literals from simplified tries so large SQL keyword sets
+  actually benefit from the prefilter.
+- Propagate `anyRequired` through `OpConcat` children.
+- Cheap length-only prefilter for patterns with no extractable literals.
+
+## Considered Options
+
+- Keep Aho-Corasick, accept the allocations.
+- Replace with Wu-Manber indexed-bitmap matcher + trie reconstruction + 
+  propagation + min-length fallback.
+
+## Decision Outcome
+
+Chosen: **Wu-Manber indexed-bitmap matcher + three structural fixes.**
+
+- `indexedMatcher` scanner with a 2-byte bigram shift table; sub-linear
+  average step (`minNeedleLen/2`), zero heap allocation at match time,
+  up to 256 needles before falling back.
+- `trieReconstruct`: detects `OpConcat(OpLiteral, OpAlternate)` and
+  prepends the shared prefix to each suffix branch, recovering the full
+  keyword set for the scanner.
+- `extractLiterals` walks `OpConcat` children and surfaces the most
+  restrictive `anyRequired`.
+- If no literals can be extracted and `minMatchLength >= 4`, a
+  length-only prefilter `len(s) >= mml` is returned — free O(1) guard.
+
+## Technical Discussion
+
+**Safety claim from the PR body:**
+
+> "The prefilter is **safe by construction**: it can only say 'definitely
+> no match' (skip regex) or 'maybe match' (run regex). A bug in literal
+> extraction degrades performance; it cannot produce a false negative.
+> When in doubt (non-ASCII CI input, unknown AST nodes, unparseable
+> patterns), we fall through to the regex."
+> — @soujanyanmbri, PR body
+
+**Coverage was a merge gate:**
+
+> "Looks amazing @soujanyanmbri Can you add more coverage?"
+> — @fzipi ([comment](https://github.com/corazawaf/coraza/pull/1597#issuecomment-4189353503))
+
+> "Thank you! Done, added more coverage. Please check :)"
+> — @soujanyanmbri ([comment](https://github.com/corazawaf/coraza/pull/1597#issuecomment-4189392213))
+
+No architectural debate — the three structural fixes plus the matcher
+swap were approved on the evidence of CRS-scale benchmarks in the PR body.
+
+## Participants
+
+- @soujanyanmbri — author
+- @fzipi — review (coverage driver)
+- @coderabbitai[bot] — reviewer
+
+## Consequences
+
+- **Positive:** Large SQL-keyword alternations (previously un-prefiltered
+  because of the trie-simplification issue) now short-circuit; zero-alloc
+  hot path for `anyRequired` scanning.
+- **Negative / follow-up:** `indexedMatcher` is a second literal-matching
+  primitive alongside the `@pm` Aho-Corasick path — operator of the two
+  codepaths must be aware of the distinct responsibilities.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1597
+- Related ADRs: ADR-0049 (rx literal prefilter), ADR-0053 (`@pm` minLen
+  prefilter)
diff --git a/docs/adr/0053-pm-minlen-prefilter.md b/docs/adr/0053-pm-minlen-prefilter.md
new file mode 100644
index 000000000..2a2ea0258
--- /dev/null
+++ b/docs/adr/0053-pm-minlen-prefilter.md
@@ -0,0 +1,82 @@
+# ADR-0053: `@pm` operator `minLen` prefilter
+
+- **Status:** accepted
+- **Date:** 2026-04-13
+- **Version:** unreleased (post-v3.7.0)
+- **PR:** [#1601](https://github.com/corazawaf/coraza/pull/1601)
+- **Issue(s):** No linked issue
+- **Deciders:** @fzipi
+- **Category:** Perf
+
+## Context and Problem
+
+`@pm` (and `@pmFromFile`, `@pmFromDataset`) dispatches into the upstream
+`aho-corasick` library even for inputs shorter than the shortest pattern.
+That library has its own prefilter (rare-byte scanning) but no
+minimum-length early exit — so calling `matcher.Iter("ab")` with a set
+whose shortest pattern is 4 chars still copies the string, allocates a
+`*prefilterState`, allocates a `*findIter`, and walks some automaton
+states before concluding "no match".
+
+## Decision Drivers
+
+- Cut the cost of short-input `@pm` evaluations — common on headers,
+  cookies, single-token query params.
+- Zero-alloc on the early-exit path.
+
+## Considered Options
+
+- Push the fix upstream into `aho-corasick`.
+- Compute the shortest-pattern length at init, add a trivial `len(value)
+  < minLen` gate inside the `@pm` operator.
+
+## Decision Outcome
+
+Chosen: **`minLen` field on the `pm` struct, checked before the upstream
+matcher.** Applies uniformly to `pm`, `pmFromFile`, `pmFromDataset`.
+
+**Why not upstream:**
+
+> "The aho-corasick library has its own prefilter (`startBytes`/`rareBytes`
+> — scanning for rare start bytes to skip automaton states), but it does
+> **not** have a minimum-length early exit. Calling `matcher.Iter(value)`
+> always: 1. Copies the string to `[]byte` (allocation) 2. Creates a
+> `*prefilterState` (heap allocation) 3. Creates a `*findIter` (heap
+> allocation via interface) 4. Walks the automaton on `Next()` before
+> concluding 'no match'."
+> — @fzipi, PR body
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR thread. The
+benchmarks, CRS-workload numbers, and allocation analysis are all in the
+PR body. Reviewers approved on that basis.
+
+Micro-benchmark from the PR body:
+
+| Input | ns/op | allocs |
+|---|---:|---:|
+| below minLen (3 chars) | **2** | 0 |
+| at minLen, no match (4 chars) | 98 | 4 |
+| longer, no match (62 chars) | 317 | 4 |
+
+CRS benchmark: −3% memory / −3% wall-time on simple GET/POST.
+
+## Participants
+
+- @fzipi — author
+
+## Consequences
+
+- **Positive:** Short inputs (shorter than any `@pm` pattern) skip the
+  upstream matcher entirely — roughly 50× faster on the pure skip path;
+  CRS wall-time drops several percent end-to-end.
+- **Negative:** `minLen` adds state on the `pm` struct; unchanged if
+  the pattern list is dynamic.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1601
+- Upstream library: https://github.com/petar-dambovaliev/aho-corasick
+- Related ADRs: ADR-0049 (rx literal prefilter — analogous `minMatchLength`
+  for `@rx`)
diff --git a/docs/adr/0054-xml-unexpected-eof.md b/docs/adr/0054-xml-unexpected-eof.md
new file mode 100644
index 000000000..14167d969
--- /dev/null
+++ b/docs/adr/0054-xml-unexpected-eof.md
@@ -0,0 +1,61 @@
+# ADR-0054: Ignore `SyntaxError` unexpected EOF in XML body processor
+
+- **Status:** accepted
+- **Date:** 2025-12-18
+- **Version:** v3.4.0
+- **PR:** [#1452](https://github.com/corazawaf/coraza/pull/1452)
+- **Issue(s):** No linked issue
+- **Deciders:** @hnakamur
+- **Category:** Parity (ProcessPartial semantics)
+
+## Context and Problem
+
+`SecRequestBodyLimitAction ProcessPartial` can truncate an XML document
+mid-parse. The XML body processor treated the resulting
+`xml.SyntaxError: unexpected EOF` as fatal, discarding whatever had been
+parsed. This is the XML twin of the multipart fix in
+[ADR-0031](0031-multipart-unexpected-eof.md).
+
+## Decision Drivers
+
+- Honour `ProcessPartial`'s contract for XML bodies.
+- Stay consistent with the multipart processor's handling.
+
+## Considered Options
+
+- Propagate the error (status quo).
+- Treat unexpected-EOF as clean termination for ProcessPartial.
+
+## Decision Outcome
+
+Chosen: **treat `SyntaxError` unexpected-EOF as clean termination** so
+whatever parsed before the cut is retained.
+
+## Technical Discussion
+
+No substantive technical discussion recorded on the PR or issue thread.
+The rationale is stated in the PR body:
+
+> "We need this behavior since we need to process an incomplete XML
+> document when `SecRequestBodyLimitAction` is set to `ProcessPartial`."
+> — @hnakamur, [PR body](https://github.com/corazawaf/coraza/pull/1452)
+
+The PR merged with approvals and a clean codecov report; no reviewer
+counter-proposals on the thread.
+
+## Participants
+
+- @hnakamur — author
+
+## Consequences
+
+- **Positive:** Parity with [ADR-0031](0031-multipart-unexpected-eof.md)
+  for XML; `ProcessPartial` consistently yields partial data across body
+  processors.
+- **Negative:** Genuine XML corruption becomes indistinguishable from a
+  legitimate truncation on the parser side.
+
+## References
+
+- PR: https://github.com/corazawaf/coraza/pull/1452
+- Related ADRs: ADR-0031 (multipart unexpected EOF)
diff --git a/docs/adr/README.md b/docs/adr/README.md
new file mode 100644
index 000000000..dc1e5c105
--- /dev/null
+++ b/docs/adr/README.md
@@ -0,0 +1,128 @@
+# Architecture Decision Records (ADRs) — Coraza v3.x
+
+This directory documents the structural decisions landed in the
+`corazawaf/coraza` repository across the v3.x release train
+(**v3.0.0 released 2023-05-31** through **v3.7.0 released 2026-04-06** and
+subsequent unreleased work on `main`).
+
+Each ADR is grounded in a real merged PR and, where available, a linked issue.
+Every ADR contains direct GitHub permalinks to the discussion that drove the
+decision and at least one quoted comment — or an explicit "No substantive
+technical discussion recorded" statement when the change was merged without
+architectural debate.
+
+## Scope
+
+- **In scope:** PRs that introduced new public API, new directives, operators,
+  actions, transformations, variables, collections, subsystems, breaking
+  changes, or algorithmic performance changes.
+- **Out of scope:** bugfixes, documentation-only changes, CI/chore changes,
+  dependency bumps (Renovate, Dependabot). Those are tracked in git history
+  and release notes.
+
+Copilot SWE-agent PRs are included when they represent structural feature or
+algorithmic work (they are reviewed by humans before merge).
+
+## Format
+
+ADRs follow MADR 3.0 with a mandatory `Technical Discussion` section. The
+canonical template lives at [`0000-template.md`](0000-template.md).
+
+## Index
+
+Listed in chronological order of merge. `Cat.` column uses shorthand:
+**F** = Feature (net-new capability / API / subsystem);
+**P** = Parity (ModSecurity / RFC / framework / platform compatibility);
+**⚡** = Perf (algorithmic or allocation change, same semantics);
+**R** = Refactor (internal-shape or public-surface cleanup).
+
+| ADR | PR | Merged | Version | Cat. | Title |
+|-----|----|--------|---------|------|-------|
+| [0001](0001-response-args-collection.md) | [#811](https://github.com/corazawaf/coraza/pull/811) | 2023-06-12 | v3.0.1 | P | RESPONSE_ARGS collection |
+| [0002](0002-secargumentslimit-directive.md) | [#812](https://github.com/corazawaf/coraza/pull/812) | 2023-06-14 | v3.0.2 | P | SecArgumentsLimit directive |
+| [0003](0003-https-audit-log-writer.md) | [#826](https://github.com/corazawaf/coraza/pull/826) | 2023-07-11 | v3.0.3 | F | HTTPS audit log writer |
+| [0004](0004-matchedrule-log-method.md) | [#848](https://github.com/corazawaf/coraza/pull/848) | 2023-07-25 | v3.0.3 | F | `MatchedRule.Log()` method |
+| [0005](0005-auditlogformatter-interface.md) | [#850](https://github.com/corazawaf/coraza/pull/850) | 2023-08-06 | v3.0.3 | R | `AuditLogFormatter` interface |
+| [0006](0006-regex-ahocorasick-memoize.md) | [#836](https://github.com/corazawaf/coraza/pull/836) | 2023-08-06 | v3.0.3 | ⚡ | Regex & Aho-Corasick memoize cache |
+| [0007](0007-uppercase-transformation.md) | [#935](https://github.com/corazawaf/coraza/pull/935) | 2023-12-18 | v3.1.0 | P | `uppercase` transformation |
+| [0008](0008-transaction-context.md) | [#963](https://github.com/corazawaf/coraza/pull/963) | 2024-01-31 | v3.1.0 | F | Transaction `context.Context` plumbing |
+| [0009](0009-structured-logging.md) | [#971](https://github.com/corazawaf/coraza/pull/971) | 2024-02-01 | v3.1.0 | R | Structured `debuglog` facade |
+| [0010](0010-raw-body-processor.md) | [#983](https://github.com/corazawaf/coraza/pull/983) | 2024-02-06 | v3.1.0 | F | `raw` request body processor |
+| [0011](0011-expose-expected-directives.md) | [#1012](https://github.com/corazawaf/coraza/pull/1012) | 2024-03-08 | v3.2.0 | F | Expose expected directives for e2e |
+| [0012](0012-secruleupdatetargetbytag.md) | [#1020](https://github.com/corazawaf/coraza/pull/1020) | 2024-03-28 | v3.2.0 | P | `SecRuleUpdateTargetByTag` + ID ranges |
+| [0013](0013-tinygo-formatter-registration.md) | [#1027](https://github.com/corazawaf/coraza/pull/1027) | 2024-04-02 | v3.2.0 | P | TinyGo formatter registration |
+| [0014](0014-base64decodeext-transformation.md) | [#1046](https://github.com/corazawaf/coraza/pull/1046) | 2024-04-24 | v3.2.0 | P | `base64DecodeExt` transformation |
+| [0015](0015-case-sensitive-maps.md) | [#1055](https://github.com/corazawaf/coraza/pull/1055) | 2024-05-01 | v3.2.0 | F | Case-sensitive maps |
+| [0016](0016-case-sensitive-args.md) | [#1059](https://github.com/corazawaf/coraza/pull/1059) | 2024-05-28 | v3.2.0 | P | Case-sensitive args support |
+| [0017](0017-multipart-strict-error.md) | [#1098](https://github.com/corazawaf/coraza/pull/1098) | 2024-07-18 | v3.3.0 | P | `MULTIPART_STRICT_ERROR` variable |
+| [0018](0018-ocsf-audit-log.md) | [#1089](https://github.com/corazawaf/coraza/pull/1089) | 2024-09-17 | v3.3.0 | F | OCSF audit log format |
+| [0019](0019-unsafe-stringdata-refactor.md) | [#1162](https://github.com/corazawaf/coraza/pull/1162) | 2024-10-04 | v3.3.0 | R | `reflect.StringHeader` → `unsafe.StringData` |
+| [0020](0020-secruleupdateactionbyid.md) | [#1071](https://github.com/corazawaf/coraza/pull/1071) | 2024-10-31 | v3.3.0 | P | `SecRuleUpdateActionById` directive |
+| [0021](0021-square-brackets-in-variables.md) | [#1226](https://github.com/corazawaf/coraza/pull/1226) | 2024-11-21 | v3.3.0 | P | Square brackets in macro variables |
+| [0022](0022-time-variables.md) | [#1223](https://github.com/corazawaf/coraza/pull/1223) | 2024-12-09 | v3.3.0 | P | `TIME_*` variables |
+| [0023](0023-base64encode-transformation.md) | [#1257](https://github.com/corazawaf/coraza/pull/1257) | 2024-12-29 | v3.3.0 | P | `base64Encode` transformation |
+| [0024](0024-hexdecode-transformation.md) | [#1275](https://github.com/corazawaf/coraza/pull/1275) | 2025-01-24 | v3.3.2 | P | `hexDecode` transformation |
+| [0025](0025-selectors-on-names-collections.md) | [#1143](https://github.com/corazawaf/coraza/pull/1143) | 2025-05-30 | v3.4.0 | P | Selectors on `*_NAMES` collections |
+| [0026](0026-pmf-short-alias.md) | [#1356](https://github.com/corazawaf/coraza/pull/1356) | 2025-05-12 | v3.4.0 | P | `@pmf` short alias |
+| [0027](0027-ipmatchf-short-alias.md) | [#1357](https://github.com/corazawaf/coraza/pull/1357) | 2025-05-13 | v3.4.0 | P | `@ipMatchF` short alias |
+| [0028](0028-syslog-audit-log-writer.md) | [#1383](https://github.com/corazawaf/coraza/pull/1383) | 2025-07-21 | v3.4.0 | F | Syslog audit log writer |
+| [0029](0029-json-schema-improvements.md) | [#1384](https://github.com/corazawaf/coraza/pull/1384) | 2025-08-11 | v3.4.0 | F | JSON schema audit log improvements |
+| [0030](0030-secrequestbodyjsondepthlimit.md) | [#1110](https://github.com/corazawaf/coraza/pull/1110) | 2026-03-06 | v3.4.0 | F | `SecRequestBodyJsonDepthLimit` directive |
+| [0031](0031-multipart-unexpected-eof.md) | [#1453](https://github.com/corazawaf/coraza/pull/1453) | 2026-03-06 | v3.4.0 | P | Ignore unexpected EOF in multipart |
+| [0032](0032-ctl-auditlogparts-plus-minus.md) | [#1467](https://github.com/corazawaf/coraza/pull/1467) | 2026-01-13 | v3.4.0 | P | `ctl:auditLogParts` `+`/`-` syntax |
+| [0033](0033-strmatch-operator.md) | [#1473](https://github.com/corazawaf/coraza/pull/1473) | 2026-01-15 | v3.4.0 | P | `@strmatch` operator |
+| [0034](0034-rule-observer-callback.md) | [#1478](https://github.com/corazawaf/coraza/pull/1478) | 2026-02-24 | v3.4.0 | F | Optional rule observer callback |
+| [0035](0035-wafwithrules-interface.md) | [#1492](https://github.com/corazawaf/coraza/pull/1492) | 2026-02-27 | v3.4.0 | F | `WAFWithRules` interface |
+| [0036](0036-remove-root-experimental-dep.md) | [#1494](https://github.com/corazawaf/coraza/pull/1494) | 2026-02-24 | v3.4.0 | R | Remove root package dependency on `experimental` |
+| [0037](0037-ctl-whole-collection-exclusion.md) | [#1495](https://github.com/corazawaf/coraza/pull/1495) | 2026-03-05 | v3.4.0 | P | `ctl:ruleRemoveTargetById` whole-collection exclusion |
+| [0038](0038-map-for-ruleremovebyid.md) | [#1524](https://github.com/corazawaf/coraza/pull/1524) | 2026-03-06 | v3.4.0 | ⚡ | `map` for `ruleRemoveByID` O(1) lookup |
+| [0039](0039-bulk-allocate-matchdata.md) | [#1530](https://github.com/corazawaf/coraza/pull/1530) | 2026-03-11 | v3.4.0 | ⚡ | Bulk-allocate `MatchData` in `collection.Find*` |
+| [0040](0040-crslang-antlr4-buildtag.md) | [#1536](https://github.com/corazawaf/coraza/pull/1536) | 2026-03-08 | v3.4.0 | F | `crslang` ANTLR4 parser behind build tag |
+| [0041](0041-ruleremovebyid-range-storage.md) | [#1538](https://github.com/corazawaf/coraza/pull/1538) | 2026-03-09 | v3.4.0 | ⚡ | `ruleRemoveById` range storage |
+| [0042](0042-regex-memoize-default-on.md) | [#1540](https://github.com/corazawaf/coraza/pull/1540) | 2026-03-18 | v3.5.0 | ⚡ | Regex memoize enabled by default |
+| [0043](0043-waf-close-per-owner-memoize.md) | [#1541](https://github.com/corazawaf/coraza/pull/1541) | 2026-03-11 | v3.5.0 | F | `WAF.Close()` + per-owner memoize tracking |
+| [0044](0044-prefix-transformation-cache.md) | [#1544](https://github.com/corazawaf/coraza/pull/1544) | 2026-03-11 | v3.5.0 | ⚡ | Prefix-based transformation cache |
+| [0045](0045-findstringsubmatchindex-noalloc.md) | [#1547](https://github.com/corazawaf/coraza/pull/1547) | 2026-03-11 | v3.5.0 | ⚡ | `FindStringSubmatchIndex` no-alloc path |
+| [0046](0046-secuploadkeepfiles-directive.md) | [#1557](https://github.com/corazawaf/coraza/pull/1557) | 2026-03-19 | v3.5.0 | P | `SecUploadKeepFiles` directive |
+| [0047](0047-regex-in-ctl-ruleremovetarget.md) | [#1561](https://github.com/corazawaf/coraza/pull/1561) | 2026-03-21 | v3.5.0 | F | Regex in `ctl:ruleRemoveTarget*` |
+| [0048](0048-ndjson-body-processor.md) | [#1563](https://github.com/corazawaf/coraza/pull/1563) | 2026-03-21 | v3.5.0 | F | NDJSON (JSON Stream) body processor |
+| [0049](0049-rx-literal-prefilter.md) | [#1534](https://github.com/corazawaf/coraza/pull/1534) | 2026-03-31 | v3.6.0 | ⚡ | `@rx` literal pre-filter |
+| [0050](0050-secrxprefilter-directive.md) | [#1589](https://github.com/corazawaf/coraza/pull/1589) | 2026-04-05 | v3.7.0 | F | `SecRxPreFilter` directive |
+| [0051](0051-audit-log-part-j.md) | [#1591](https://github.com/corazawaf/coraza/pull/1591) | 2026-04-03 | v3.7.0 | P | Audit log Part J (uploaded files) |
+| [0052](0052-ahocorasick-to-bitmap.md) | [#1597](https://github.com/corazawaf/coraza/pull/1597) | 2026-04-09 | unreleased | ⚡ | Aho-Corasick → indexed-bitmap matcher |
+| [0053](0053-pm-minlen-prefilter.md) | [#1601](https://github.com/corazawaf/coraza/pull/1601) | 2026-04-13 | unreleased | ⚡ | `@pm` `minLen` prefilter |
+| [0054](0054-xml-unexpected-eof.md) | [#1452](https://github.com/corazawaf/coraza/pull/1452) | 2025-12-18 | v3.4.0 | P | Ignore unexpected EOF in XML body processor |
+
+## Totals
+
+**54 structural ADRs** across v3.0.0 → v3.7.0 (plus two unreleased
+post-v3.7.0 changes on `main`):
+
+| Category | Count | Share |
+|---|---:|---:|
+| Feature | 17 | 31 % |
+| Parity | 23 | 43 % |
+| Perf | 10 | 19 % |
+| Refactor | 4 | 7 % |
+
+**≈ 1 in 3 structural changes is a Feature; the other 2 are upkeep**
+(Parity + Perf + Refactor). Bugfixes are excluded from the denominator.
+
+**14 / 54 ADRs (26 %)** ship with no substantive on-GitHub technical
+discussion — see the `## Technical Discussion` section of each ADR for
+its own reviewer dialogue or the "No substantive technical discussion
+recorded" marker.
+
+## How to read an ADR
+
+- **Context and Problem** — why the change was needed.
+- **Technical Discussion** — the PR/issue thread. If empty, it says so.
+- **Participants** — authors, reviewers, and any issue commenters.
+- **Consequences** — the surviving effect on the code and API.
+
+## How to add a new ADR
+
+1. Copy [`0000-template.md`](0000-template.md) to `NNNN-slug.md`.
+2. Fill in every section; do not invent discussion.
+3. Add the new row to the index table above.
+4. Commit alongside (or immediately after) the implementing PR merges.