From b954a04b5ce0fca1aa884380679372017c9fce60 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Thu, 6 Nov 2025 19:21:09 +0000
Subject: [PATCH 01/32] Documentation

---
 .github/workflows/build.yml                   |   2 +
 README.md                                     |   2 +-
 docs/README.md                                |  14 +
 docs/addresses.md                             | 100 ++++
 docs/c-api/api.md                             | 441 ++++++++++++++++++
 .../c-api/binding-integration-guide.md        |  84 ++--
 docs/changelog/CHANGELOG-latest.md            |   1 +
 .../changelog/CHANGELOG-v1.x.md               |   0
 docs/changelog/CHANGELOG-v2.0.0.md            |   0
 docs/exclusions.md                            | 120 +++++
 docs/operators.md                             | 160 +++++++
 docs/overview.md                              | 116 +++++
 docs/processors.md                            | 107 +++++
 docs/rules.md                                 | 125 +++++
 docs/transformers.md                          |  30 ++
 docs/upgrading/UPGRADING-latest.md            |   1 +
 .../upgrading/UPGRADING-v1.x.md               |   0
 docs/upgrading/UPGRADING-v2.0.md              | 170 +++++++
 18 files changed, 1434 insertions(+), 39 deletions(-)
 create mode 100644 docs/README.md
 create mode 100644 docs/addresses.md
 create mode 100644 docs/c-api/api.md
 rename BINDING_IMPL_NOTES.md => docs/c-api/binding-integration-guide.md (58%)
 create mode 120000 docs/changelog/CHANGELOG-latest.md
 rename CHANGELOG.md => docs/changelog/CHANGELOG-v1.x.md (100%)
 create mode 100644 docs/changelog/CHANGELOG-v2.0.0.md
 create mode 100644 docs/exclusions.md
 create mode 100644 docs/operators.md
 create mode 100644 docs/overview.md
 create mode 100644 docs/processors.md
 create mode 100644 docs/rules.md
 create mode 100644 docs/transformers.md
 create mode 120000 docs/upgrading/UPGRADING-latest.md
 rename UPGRADING.md => docs/upgrading/UPGRADING-v1.x.md (100%)
 create mode 100644 docs/upgrading/UPGRADING-v2.0.md

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 9e7646da8..68253e515 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -394,6 +394,8 @@ jobs:
         uses: softprops/action-gh-release@c062e08bd532815e2082a85e87e3ef29c3e6d191 # v2.0.8
         with:
           draft: true
+          name: v${{ github.ref_name }}
+          body_path: ${{ github.workspace }}/docs/changelog/CHANGELOG-latest.md
           files: |
             ./artifacts/**/*.tar.gz
             ./artifacts/**/*.sha256
diff --git a/README.md b/README.md
index 6a8617470..29b7ab27c 100644
--- a/README.md
+++ b/README.md
@@ -352,4 +352,4 @@ applied to the `http.server.query` value `http://localhost/?q=<script>alert() he
 
 ## Binding implementation notes
 
-See [`BINDING_IMPL_NOTES.md`](./BINDING_IMPL_NOTES.md).
+See [`docs/c-api/binding-integration-guide.md`](docs/c-api/binding-integration-guide.md).
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..1c7acbf02
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,14 @@
+# Documentation Index
+
+The documents below describe libddwaf’s public API and internal primitives. Use them as entry points when integrating or upgrading the engine.
+
+- [Overview](overview.md) – Architectural summary and execution pipeline.
+- [Address Reference](addresses.md) – List of supported ASM addresses and their expected value types.
+- [Operator Reference](operators.md) – Scalar and detector operators with parameters and version notes.
+- [Transformer Reference](transformers.md) – Input transformation utilities available to rules.
+- [Processor Reference](processors.md) – Built-in preprocessors/postprocessors and configuration options.
+- [Rule Definitions](rules.md) – Structure, metadata, and output controls for writing rules.
+- [Exclusion Filters](exclusions.md) – Configure rule and input exclusions in configuration documents.
+- [C API Reference](c-api/api.md) – Comprehensive description of all exported functions, structs, and macros.
+
+For migration guidance, start with [Upgrading to 2.0](upgrading/UPGRADING-v2.0.md) or consult the versioned guides in [`docs/upgrading/`](upgrading/).
diff --git a/docs/addresses.md b/docs/addresses.md
new file mode 100644
index 000000000..1dd7c8776
--- /dev/null
+++ b/docs/addresses.md
@@ -0,0 +1,100 @@
+# Address Reference
+
+This page lists the Application Security Management (ASM) addresses that libddwaf understands. Addresses represent the structured inputs that processors, filters, and rules consume. The canonical rule packs that reference these addresses live in [`appsec-event-rules`](https://github.com/DataDog/appsec-event-rules/blob/main/build/recommended.json).
+
+---
+
+## HTTP Request & Response Addresses
+
+| Address | Type | Description / Notes | Example |
+| --- | --- | --- | --- |
+| `server.request.body` | Native value (framework-specific) | Parsed HTTP request body as exposed by the framework. See the dedicated `server.request.body` binder documentation for language-specific nuances. | *(varies)* |
+| `server.request.body.filenames` | Array | Filenames supplied through RFC-1867 HTML file uploads. Each entry reflects the original client filename. | `["invoice.pdf", "avatar.png"]` |
+| `server.request.body.files_field_names` | Array | Form field names associated with uploaded files (RFC-1867). | `["attachment", "photo"]` |
+| `server.request.query` | Native value | Framework-parsed query string (can contain duplicate keys). In .NET a query such as `?test&[$slice]` keeps all keys. | `{ "test": "", "[$slice]": "" }` |
+| `server.request.headers.no_cookies` | Headers object | Incoming headers with cookie-related fields removed. Header keys must be lowercase. | `{ "x-forwarded-for": "1.2.3.4", "user-agent": "Moustache" }` |
+| `server.request.trailers` | Headers object | HTTP trailing headers. | `{ "grpc-status": "0" }` |
+| `server.request.uri.raw` | String | Relative URI (path and query, without scheme or authority). | `/path/bla.php?param1=a&param2=b%20c` |
+| `server.request.method` | String | HTTP method. | `"GET"` |
+| `server.request.path_params` | Native value | Framework-parsed path parameters (e.g. `/foo/:id` yields `{ id: 123 }`). | `{ "id": "42" }` |
+| `server.request.cookies` | Cookies map | Cookies parsed by the framework. AppSec obfuscation operates on keys and values as needed. | `{ "password": ["1234"], "foo": ["bar", "baz"] }` |
+| `server.response.status` | String | HTTP response status code. | `"404"` |
+| `server.response.headers.no_cookies` | Headers object | Outgoing headers without any `Set-Cookie` entries. | `{ "content-type": "application/json" }` |
+| `http.client_ip` | String | Client IP determined by the Datadog client IP resolution policy. | `"203.0.113.10"` |
+
+---
+
+## Exploit Prevention Addresses
+
+| Address | Type | Description |
+| --- | --- | --- |
+| `server.io.fs.file` | String | File paths analysed by local file inclusion (LFI) rules. |
+| `server.io.net.url` | String | URLs analysed by server-side request forgery (SSRF) rules. |
+| `server.db.statement` | String | SQL statements inspected by SQL injection rules. |
+| `server.db.system` | String | SQL dialect associated with `server.db.statement` (see APM span attribute `db.system`). |
+| `server.sys.shell.cmd` | String or array (≥ v1.20.1) | Shell commands analysed by command/remote code injection rules. |
+
+---
+
+## User Monitoring Addresses
+
+| Address | Type | Description |
+| --- | --- | --- |
+| `usr.id` | String | User identifier captured automatically or via the SDK. |
+| `usr.session_id` | String | Session identifier associated with the current request or user. |
+
+---
+
+## Business Logic Addresses
+
+| Address | Type | Description |
+| --- | --- | --- |
+| `server.business_logic.users.login.success` | Null | Event marker indicating a successful login. |
+| `server.business_logic.users.login.failure` | Null | Event marker indicating a failed login. |
+
+---
+
+## Virtual & Auxiliary Addresses
+
+| Address | Type | Description |
+| --- | --- | --- |
+| `waf.context.event` | Null | Internally generated when an event is triggered; used to gate postprocessors. |
+| `waf.context.processor` | Map | Flags enabling processor-dependent features (for example schema extraction). | `{ "extract-schema": true }` |
+
+---
+
+## gRPC Server Addresses
+
+| Address | Type | Description / Notes | Occurrences per RPC | Example |
+| --- | --- | --- | --- | --- |
+| `grpc.server.method` | String | Fully qualified RPC name of the form `/$package.$service/$method`. Must match the APM span tag `rpc.grpc.full_method`. | 1 (all RPC types) | `"/my.package.Greeter/SayHello"` |
+| `grpc.server.request.message` | Native value | Parsed inbound message payload. Provide as ephemeral data per message for streaming RPCs. | Unary: 1<br>Client stream: N<br>Server stream: 1<br>Bidirectional: N | `{ "user": { "id": "42" } }` |
+| `grpc.server.request.metadata` | Native string kv map | Client request metadata (headers). Keys must be lowercase; binary keys (`*-bin`) should be base64 encoded. | 0 or 1 (all RPC types) | `{ "user-agent": ["grpc-go/1.58.0"] }` |
+| `grpc.server.response.message` | Native value | Parsed outbound message payload generated by the server. Provide as ephemeral data per message for streaming RPCs. | Unary: 1<br>Client stream: 1<br>Server stream: N<br>Bidirectional: M | `{ "status": "OK", "score": 0.97 }` |
+| `grpc.server.response.metadata.headers` | Native string kv map | Initial response metadata returned before the first message. | 0 or 1 (all RPC types) | `{ "content-type": ["application/grpc+proto"] }` |
+| `grpc.server.response.metadata.trailers` | Native string kv map | Trailing response metadata sent after the final message. | 0 or 1 (all RPC types) | `{ "grpc-message": ["permission denied"] }` |
+| `grpc.server.response.status` | Number | Canonical gRPC status code (see [grpc/grpc status codes](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md)). | 1 (all RPC types) | `7` |
+
+---
+
+## GraphQL Server Addresses
+
+| Address | Type | Description / Notes | Occurrences per Request | Example |
+| --- | --- | --- | --- | --- |
+| `graphql.server.all_resolvers` | Array of resolver objects | Full collection of resolver payloads captured after the GraphQL layer executes. Typically mirrors the HTTP body content but structured per resolver. | 1 aggregated payload | `[{"path":["Query","product"],"arguments":{"id":"123"},"value":"..."}, {"path":["Product","reviews"],"arguments":{},"value":[...] }]` |
+| `graphql.server.resolver` | Native value | Resolver payload emitted as each resolver executes. Shape is instrumentation-specific and usually matches a single entry inside `graphql.server.all_resolvers`. | Number of resolvers executed | `{ "path": ["Query","product"], "arguments": { "id": "123" }, "value": "..." }` |
+
+GraphQL payloads generally arrive as part of the HTTP request body before the GraphQL-specific addresses are emitted. libddwaf deduplicates matches across addresses, so a single attack surface only triggers one event even if it appears in both `server.request.body` and a GraphQL address. In practice, GraphQL rule matches surface on the HTTP body address.
+
+---
+
+## Types and Conventions
+
+- **Headers object**: Use the framework’s native header representation as long as keys are lowercased (e.g. `X-Forwarded-For` → `x-forwarded-for`).
+- **Native string kv map**: Map of lowercase string keys to arrays of strings, as used by gRPC metadata. Binary keys ending with `-bin` must use base64-encoded values.
+- **Native value**: A value in the language/framework’s natural representation. The same address may look different across runtimes; the WAF only relies on the logical content (strings, numbers, collections).
+- **Resolver object**: Instrumentation-defined GraphQL resolver payload that usually includes resolver path, arguments, and the resolved value. Resolvers supplied individually and within `graphql.server.all_resolvers` must use the same structure.
+- **Cookies map**: A map of cookie names to their values as parsed by the HTTP framework. Values may be strings or arrays of strings depending on language support.
+- **Sensitive data obfuscation**: Cookie maps and header objects are scanned by the generic AppSec obfuscator. Keys matching sensitive names (for example `Bearer`) will have their values redacted in emitted events.
+
+These conventions ensure libddwaf can evaluate requests consistently across agents and frameworks while still allowing each integration to map its native data structures to the addresses used by Datadog’s managed rules.
diff --git a/docs/c-api/api.md b/docs/c-api/api.md
new file mode 100644
index 000000000..0cd5f8f99
--- /dev/null
+++ b/docs/c-api/api.md
@@ -0,0 +1,441 @@
+# libddwaf C API Reference
+
+This document provides a complete reference for the public symbols exported through `include/ddwaf.h`. It covers every macro, enumeration, structure, type alias, callback signature, and function available to C or C++ callers embedding libddwaf 2.0.0 or later.
+
+- All prototypes and types are defined in `include/ddwaf.h`.
+- Functions follow the conventional C calling convention; when used from C++ be sure to include the header without wrapping it in your own `extern "C"`.
+- Every function that receives or returns `ddwaf_object` instances requires the caller to respect the allocator ownership rules described in the *Allocator APIs* section.
+
+---
+
+## Preprocessor Macros
+
+### `DDWAF_H`
+Include guard that prevents the header from being processed multiple times. It has no behavioural meaning and should not be referenced directly.
+
+### `DDWAF_OBJ_SSTR_SIZE`
+Defines the storage capacity (in bytes) of the inline small-string buffer inside `_ddwaf_object_small_string`. The constant has the value `14`.
+
+### `static_assert`
+For C compilers that expose `_Static_assert` but not `static_assert`, the header maps `static_assert` to `_Static_assert`. Prefer the standard spelling in your own code.
+
+---
+
+## Enumerations
+
+### `DDWAF_OBJ_TYPE`
+Identifies the payload stored in a `ddwaf_object`.
+
+| Value | Meaning |
+| --- | --- |
+| `DDWAF_OBJ_INVALID` | Sentinel for uninitialised or invalid objects. |
+| `DDWAF_OBJ_NULL` | Represents an explicit `null` value. |
+| `DDWAF_OBJ_BOOL` | Boolean payload. |
+| `DDWAF_OBJ_SIGNED` | Signed 64-bit integer payload. |
+| `DDWAF_OBJ_UNSIGNED` | Unsigned 64-bit integer payload. |
+| `DDWAF_OBJ_FLOAT` | Double-precision floating point payload. |
+| `DDWAF_OBJ_STRING` | Heap-allocated UTF-8 string. |
+| `DDWAF_OBJ_LITERAL_STRING` | Non-owning string literal; libddwaf never frees it. |
+| `DDWAF_OBJ_SMALL_STRING` | Inline UTF-8 string up to `DDWAF_OBJ_SSTR_SIZE`. |
+| `DDWAF_OBJ_ARRAY` | Sequential container of `ddwaf_object`. |
+| `DDWAF_OBJ_MAP` | Associative container of key/value `ddwaf_object` pairs. |
+
+### `DDWAF_RET_CODE`
+Return codes produced by the evaluation functions.
+
+| Value | Meaning |
+| --- | --- |
+| `DDWAF_ERR_INTERNAL` (`-3`) | Unexpected internal error; context state is undefined. |
+| `DDWAF_ERR_INVALID_OBJECT` (`-2`) | Input object did not match the expected structure. |
+| `DDWAF_ERR_INVALID_ARGUMENT` (`-1`) | Call failed because an argument was not valid. |
+| `DDWAF_OK` (`0`) | Call completed without generating matches or errors. |
+| `DDWAF_MATCH` (`1`) | Call completed with at least one rule match. |
+
+### `DDWAF_LOG_LEVEL`
+Verbosity levels used by the logging subsystem.
+
+`DDWAF_LOG_TRACE`, `DDWAF_LOG_DEBUG`, `DDWAF_LOG_INFO`, `DDWAF_LOG_WARN`, `DDWAF_LOG_ERROR`, `DDWAF_LOG_OFF`.
+
+---
+
+## Type Aliases and Callback Signatures
+
+| Symbol | Description |
+| --- | --- |
+| `ddwaf_handle` | Opaque pointer to a WAF instance returned by `ddwaf_init` or `ddwaf_builder_build_instance`. |
+| `ddwaf_context` | Opaque pointer representing an evaluation context obtained via `ddwaf_context_init`. |
+| `ddwaf_subcontext` | Opaque pointer representing a lightweight clone of a context created with `ddwaf_subcontext_init`. |
+| `ddwaf_builder` | Opaque pointer to the configuration builder returned by `ddwaf_builder_init`. |
+| `ddwaf_allocator` | Opaque pointer identifying an allocator instance. |
+| `ddwaf_alloc_fn_type` | Signature for custom allocation callbacks used with `ddwaf_user_allocator_init`. |
+| `ddwaf_free_fn_type` | Signature for custom free callbacks passed to `ddwaf_user_allocator_init`. |
+| `ddwaf_udata_free_fn_type` | Optional destructor for the user data passed to `ddwaf_user_allocator_init`. |
+
+### `ddwaf_log_cb`
+
+```c
+typedef void (*ddwaf_log_cb)(
+    DDWAF_LOG_LEVEL level,
+    const char *function,
+    const char *file,
+    unsigned line,
+    const char *message,
+    uint64_t message_len);
+```
+
+Logging callback used by `ddwaf_set_log_cb`. The strings are null-terminated, and `message_len` excludes the terminator.
+
+---
+
+## Structure and Union Layouts
+
+The header exposes the internal representation of `ddwaf_object` for interoperability. Always prefer the accessor helpers instead of touching fields directly unless you are implementing a low-level binding.
+
+- Primitive wrappers: `_ddwaf_object_bool`, `_ddwaf_object_signed`, `_ddwaf_object_unsigned`, `_ddwaf_object_float`, `_ddwaf_object_string`, `_ddwaf_object_small_string`.
+- Container wrappers: `_ddwaf_object_array`, `_ddwaf_object_map`, `_ddwaf_object_kv`.
+- Tagged union: `_ddwaf_object` (aliased as `ddwaf_object`).
+
+The type tag stored in `via` must match the helper you use; mixing the two is undefined behaviour.
+
+---
+
+## Library Lifecycle Functions
+
+### `ddwaf_init`
+
+```c
+ddwaf_handle ddwaf_init(const ddwaf_object *ruleset, ddwaf_object *diagnostics);
+```
+
+Creates a WAF instance from a configuration object. The `ruleset` must be a map that contains the rule definitions, overrides, data, and exclusions. When supplied, `diagnostics` receives parser warnings and errors; destroy it with `ddwaf_object_destroy` after use. Returns `NULL` on failure.
+
+### `ddwaf_destroy`
+
+```c
+void ddwaf_destroy(ddwaf_handle handle);
+```
+
+Destroys a WAF instance and releases its resources. Safe to call with `NULL`.
+
+### `ddwaf_get_version`
+
+```c
+const char *ddwaf_get_version(void);
+```
+
+Returns a null-terminated string describing the libddwaf version. The pointer remains owned by the library.
+
+### `ddwaf_set_log_cb`
+
+```c
+bool ddwaf_set_log_cb(ddwaf_log_cb cb, DDWAF_LOG_LEVEL min_level);
+```
+
+Installs a callback that receives libddwaf log messages at or above `min_level`. Passing `NULL` disables logging. Returns `false` if the logging system rejects the callback (for example, when called concurrently).
+
+---
+
+## Introspection Helpers
+
+### `ddwaf_known_addresses`
+
+```c
+const char *const *ddwaf_known_addresses(const ddwaf_handle handle, uint32_t *size);
+```
+
+Returns the null-terminated root addresses referenced by the active configuration. The returned array is owned by libddwaf and becomes invalid after `ddwaf_destroy`.
+
+### `ddwaf_known_actions`
+
+```c
+const char *const *ddwaf_known_actions(const ddwaf_handle handle, uint32_t *size);
+```
+
+Lists the action identifiers that may appear in evaluation results. Ownership rules mirror `ddwaf_known_addresses`.
+
+---
+
+## Context APIs
+
+### `ddwaf_context_init`
+
+```c
+ddwaf_context ddwaf_context_init(const ddwaf_handle handle, ddwaf_allocator output_alloc);
+```
+
+Creates an evaluation context bound to a WAF instance. The allocator manages any output or cached copies of request data. Returns `NULL` on allocation errors.
+
+### `ddwaf_context_eval`
+
+```c
+DDWAF_RET_CODE ddwaf_context_eval(
+    ddwaf_context context,
+    ddwaf_object *data,
+    ddwaf_allocator alloc,
+    ddwaf_object *result,
+    uint64_t timeout);
+```
+
+Evaluates a request payload. `data` must be a map keyed by address and built with the same allocator used to destroy it. `alloc` supplies storage for intermediate copies and the optional `result`. When `result` is non-null and the return code is `DDWAF_OK` or `DDWAF_MATCH`, it contains detailed events and metadata which must be released with `ddwaf_object_destroy(result, alloc)`. The function enforces a microsecond timeout.
+
+### `ddwaf_context_destroy`
+
+```c
+void ddwaf_context_destroy(ddwaf_context context);
+```
+
+Destroys a context and releases any persistent copies of request data using the allocator associated with the context.
+
+---
+
+## Subcontext APIs
+
+### `ddwaf_subcontext_init`
+
+```c
+ddwaf_subcontext ddwaf_subcontext_init(ddwaf_context context);
+```
+
+Creates a lightweight clone that shares persistent state with its parent context. The subcontext inherits the allocator that was passed to `ddwaf_context_init`.
+
+### `ddwaf_subcontext_eval`
+
+```c
+DDWAF_RET_CODE ddwaf_subcontext_eval(
+    ddwaf_subcontext subcontext,
+    ddwaf_object *data,
+    ddwaf_allocator alloc,
+    ddwaf_object *result,
+    uint64_t timeout);
+```
+
+Evaluates request data against a subcontext using the same semantics as `ddwaf_context_eval`. The allocator must be identical to the one used when creating the parent context.
+
+### `ddwaf_subcontext_destroy`
+
+```c
+void ddwaf_subcontext_destroy(ddwaf_subcontext subcontext);
+```
+
+Destroys the subcontext and releases any data cached within it.
+
+---
+
+## Builder APIs
+
+Use the builder when you need to manage multiple configurations or build WAF instances incrementally.
+
+### `ddwaf_builder_init`
+
+```c
+ddwaf_builder ddwaf_builder_init(void);
+```
+
+Allocates a new builder instance. Returns `NULL` on failure.
+
+### `ddwaf_builder_add_or_update_config`
+
+```c
+bool ddwaf_builder_add_or_update_config(
+    ddwaf_builder builder,
+    const char *path,
+    uint32_t path_len,
+    const ddwaf_object *config,
+    ddwaf_object *diagnostics);
+```
+
+Registers or refreshes a configuration identified by `path`. The `config` object is parsed immediately; on error the return value is `false` and `diagnostics` (when provided) contains parser feedback.
+
+### `ddwaf_builder_remove_config`
+
+```c
+bool ddwaf_builder_remove_config(
+    ddwaf_builder builder,
+    const char *path,
+    uint32_t path_len);
+```
+
+Deletes the configuration identified by `path`. Returns `false` if the path was not known.
+
+### `ddwaf_builder_build_instance`
+
+```c
+ddwaf_handle ddwaf_builder_build_instance(ddwaf_builder builder);
+```
+
+Compiles the currently loaded configurations into a WAF instance. Returns `NULL` when compilation fails.
+
+### `ddwaf_builder_get_config_paths`
+
+```c
+uint32_t ddwaf_builder_get_config_paths(
+    ddwaf_builder builder,
+    ddwaf_object *paths,
+    const char *filter,
+    uint32_t filter_len);
+```
+
+Counts the configurations present in the builder and optionally populates `paths` with their identifiers. If `filter` is non-null, only the paths matching the unanchored regular expression are reported.
+
+### `ddwaf_builder_destroy`
+
+```c
+void ddwaf_builder_destroy(ddwaf_builder builder);
+```
+
+Releases all resources associated with the builder.
+
+---
+
+## Allocator APIs
+
+### `ddwaf_get_default_allocator`
+
+```c
+ddwaf_allocator ddwaf_get_default_allocator(void);
+```
+
+Returns the allocator used internally by libddwaf. The handle is owned by the library and must not be destroyed.
+
+### Pool and monotonic allocators
+
+```c
+ddwaf_allocator ddwaf_synchronized_pool_allocator_init(void);
+ddwaf_allocator ddwaf_unsynchronized_pool_allocator_init(void);
+ddwaf_allocator ddwaf_monotonic_allocator_init(void);
+```
+
+Factory functions that create dedicated allocators. Destroy them with `ddwaf_allocator_destroy` when no outstanding allocations remain.
+
+### `ddwaf_user_allocator_init`
+
+```c
+ddwaf_allocator ddwaf_user_allocator_init(
+    ddwaf_alloc_fn_type alloc_fn,
+    ddwaf_free_fn_type free_fn,
+    void *udata,
+    ddwaf_udata_free_fn_type udata_free_fn);
+```
+
+Wraps user-provided allocation routines in a libddwaf-compatible allocator. When `udata_free_fn` is non-null it is called automatically during `ddwaf_allocator_destroy`.
+
+### Allocation helpers
+
+```c
+void *ddwaf_allocator_alloc(ddwaf_allocator alloc, size_t bytes, size_t alignment);
+void ddwaf_allocator_free(ddwaf_allocator alloc, void *p, size_t bytes, size_t alignment);
+void ddwaf_allocator_destroy(ddwaf_allocator alloc);
+```
+
+Low-level allocation routines. The `alloc` argument must be the same handle returned by the allocator factory. `ddwaf_allocator_destroy` is a no-op for the default allocator but must be called for user-created allocators once all objects have been released.
+
+---
+
+## Object Construction Helpers
+
+Each helper returns the pointer passed in on success and `NULL` on failure unless stated otherwise.
+
+```c
+ddwaf_object *ddwaf_object_set_invalid(ddwaf_object *object);
+ddwaf_object *ddwaf_object_set_null(ddwaf_object *object);
+ddwaf_object *ddwaf_object_set_string(ddwaf_object *object, const char *string, uint32_t length, ddwaf_allocator alloc);
+ddwaf_object *ddwaf_object_set_string_literal(ddwaf_object *object, const char *string, uint32_t length);
+ddwaf_object *ddwaf_object_set_string_nocopy(ddwaf_object *object, const char *string, uint32_t length);
+ddwaf_object *ddwaf_object_set_unsigned(ddwaf_object *object, uint64_t value);
+ddwaf_object *ddwaf_object_set_signed(ddwaf_object *object, int64_t value);
+ddwaf_object *ddwaf_object_set_bool(ddwaf_object *object, bool value);
+ddwaf_object *ddwaf_object_set_float(ddwaf_object *object, double value);
+ddwaf_object *ddwaf_object_set_array(ddwaf_object *object, uint16_t capacity, ddwaf_allocator alloc);
+ddwaf_object *ddwaf_object_set_map(ddwaf_object *object, uint16_t capacity, ddwaf_allocator alloc);
+```
+
+- The `_string_literal` variant never copies the buffer; the caller must guarantee its lifetime exceeds that of the object.
+- The `_string_nocopy` variant assumes the buffer was allocated by the same allocator that will be used during destruction.
+- Arrays and maps allocate storage with the capacity supplied; call `ddwaf_object_insert*` to populate them.
+
+### Container insertion and JSON parsing
+
+```c
+ddwaf_object *ddwaf_object_insert(ddwaf_object *array, ddwaf_allocator alloc);
+ddwaf_object *ddwaf_object_insert_key(ddwaf_object *map, const char *key, uint32_t length, ddwaf_allocator alloc);
+ddwaf_object *ddwaf_object_insert_literal_key(ddwaf_object *map, const char *key, uint32_t length, ddwaf_allocator alloc);
+ddwaf_object *ddwaf_object_insert_key_nocopy(ddwaf_object *map, const char *key, uint32_t length, ddwaf_allocator alloc);
+bool ddwaf_object_from_json(ddwaf_object *output, const char *json_str, uint32_t length, ddwaf_allocator alloc);
+```
+
+Insertion helpers expand array or map containers by one element and return the slot to be filled. `ddwaf_object_from_json` parses a JSON document into a `ddwaf_object`; destroy the result with `ddwaf_object_destroy`.
+
+---
+
+## Object Accessors and Predicates
+
+### Introspection
+
+```c
+DDWAF_OBJ_TYPE ddwaf_object_get_type(const ddwaf_object *object);
+size_t ddwaf_object_get_size(const ddwaf_object *object);
+size_t ddwaf_object_get_length(const ddwaf_object *object);
+const char *ddwaf_object_get_string(const ddwaf_object *object, size_t *length);
+uint64_t ddwaf_object_get_unsigned(const ddwaf_object *object);
+int64_t ddwaf_object_get_signed(const ddwaf_object *object);
+double ddwaf_object_get_float(const ddwaf_object *object);
+bool ddwaf_object_get_bool(const ddwaf_object *object);
+```
+
+Retrieve metadata or scalar values from an object. When the object is not of the expected type, the returned value is zero or `NULL`.
+
+### Container lookup
+
+```c
+const ddwaf_object *ddwaf_object_at_key(const ddwaf_object *object, size_t index);
+const ddwaf_object *ddwaf_object_at_value(const ddwaf_object *object, size_t index);
+const ddwaf_object *ddwaf_object_find(const ddwaf_object *object, const char *key, size_t length);
+```
+
+`ddwaf_object_at_key` returns the key object for the entry at `index` when iterating over a map (arrays do not expose keys). `ddwaf_object_at_value` returns the corresponding value object. `ddwaf_object_find` performs a direct lookup by key and returns the associated value.
+
+### Cloning
+
+```c
+ddwaf_object *ddwaf_object_clone(
+    const ddwaf_object *source,
+    ddwaf_object *destination,
+    ddwaf_allocator alloc);
+```
+
+Performs a deep copy of `source` into `destination`, allocating any necessary storage from `alloc`. The destination must be destroyed with the same allocator once it is no longer needed.
+
+### Type predicates
+
+```c
+bool ddwaf_object_is_invalid(const ddwaf_object *object);
+bool ddwaf_object_is_null(const ddwaf_object *object);
+bool ddwaf_object_is_bool(const ddwaf_object *object);
+bool ddwaf_object_is_signed(const ddwaf_object *object);
+bool ddwaf_object_is_unsigned(const ddwaf_object *object);
+bool ddwaf_object_is_float(const ddwaf_object *object);
+bool ddwaf_object_is_string(const ddwaf_object *object);
+bool ddwaf_object_is_array(const ddwaf_object *object);
+bool ddwaf_object_is_map(const ddwaf_object *object);
+```
+
+Convenience wrappers that compare the object type to the respective category.
+
+### Destruction
+
+```c
+void ddwaf_object_destroy(ddwaf_object *object, ddwaf_allocator alloc);
+```
+
+Reclaims any memory owned by the object. Always pass the allocator that was used to build it.
+
+---
+
+## Thread Safety and Lifetime Notes
+
+- WAF handles are thread-safe for evaluation once a context has been created. Builder operations and configuration mutation are not thread-safe.
+- Allocation routines inherit the thread-safety guarantees of the allocator instance returned by the corresponding factory.
+- Objects created with `_string_literal` or `_insert_literal_key` expect the referenced buffers to outlive the object or to remain immutable.
+- Result objects returned by evaluation functions remain valid until destroyed. Never reuse them across calls without destroying or reinitialising them first.
+
+This reference mirrors the API shipped in `include/ddwaf.h` and should be kept in sync whenever the header changes.
diff --git a/BINDING_IMPL_NOTES.md b/docs/c-api/binding-integration-guide.md
similarity index 58%
rename from BINDING_IMPL_NOTES.md
rename to docs/c-api/binding-integration-guide.md
index 49919f8e5..9761cc1c3 100644
--- a/BINDING_IMPL_NOTES.md
+++ b/docs/c-api/binding-integration-guide.md
@@ -1,22 +1,19 @@
-# Implementation notes for bindings
+# libddwaf binding integration guide
 
+This guide complements the API reference in `docs/c-api/api.md`. It focuses on
+the concurrency and lifecycle concerns that most native bindings must handle to
+provide a safe libddwaf integration.
 
-## `ddwaf_handle`
+## `ddwaf_handle` lifecycle
 
-`ddwaf_handle` represents a rule set, with associated rule data, exclusions,
-and so on. It is created through `ddwaf_init` and `ddwaf_update`.
+`ddwaf_handle` represents the compiled ruleset, related data providers, and
+exclusions. Handles are built through `ddwaf_init` and updated in place through
+`ddwaf_update`. Only one instance is typically kept by a tracer or agent.
 
-A tracer will want to keep only one live `ddwaf_handle`. The first one will be
-created through `ddwaf_init`, and then it will replace it through
-`ddwaf_update` as it gets new configurations through remote config.
-
-The two relevant operations on `ddwaf_handle` are `ddwaf_context_init` and
-`ddwaf_update`. Neither of these operations changes the `ddwaf_handle`. So, at
-this point, it is sufficient to ensure that threads calling
-`ddwaf_context_init` and `ddwaf_update` see a fully constructed `ddwaf_handle`
-— put in other words, it is sufficient that the write to the pointer/reference
-happens after `ddwaf_init/update` is called (as seen by other threads). For
-this, a release-acquire operation suffices:
+The two operations that observe a handle are `ddwaf_context_init` and
+`ddwaf_update`. Neither mutates the handle content, but callers must ensure that
+other threads only observe a fully initialised pointer. A release/acquire pair
+is enough for this requirement:
 
 ```c++
 std::atomic<ddwaf_handle> cur_ddwaf_handle; // global variable; the live handle
@@ -70,25 +67,21 @@ through `ddwaf_update`, though that is less of a problem because generally the
 tracers will not want to update the global `ddwaf_handle` from several threads
 simultaneously).
 
-There are many possible strategies to deal with this memory reclamation
-problem, but the most straightforward are:
+There are many ways to guarantee safe reclamation. Two common strategies are
+outlined below.
 
-* If the runtime uses garbage collection, we can delay the call to
-  `ddwaf_destroy` until the garbage collector determines the object wrapping
-  the native `ddwaf_handle` has no more references. This is relatively easy to
-  do and doesn't involve extra usage of locks, but the memory used by the
-  `ddwaf_handle` will not be available until the garbage collector decides
-  to reclaim the wrapped object. Because the garbage collector does not see
-  the memory being used by the `ddwaf_handle`, if garbage collection never
-  happens, there is a risk that memory consumption gets too high. This is a
-  rather unlikely scenario though.
+* Delay `ddwaf_destroy` until your runtime can prove that no other code keeps a
+  reference. Garbage-collected environments can let the wrapper object finalise
+  the native handle, but keep in mind that the collector is blind to the native
+  memory usage.
 
-* You can use read-write locks:
+* Protect access with reader/writer locks so that `ddwaf_destroy` only executes
+  after new contexts can no longer be created:
 
 ```c++
 // global variables
 std::shared_mutex mutex;
-ddwaf_handle cur_ddwaf_handle;
+ddwaf_handle cur_ddwaf_handle = nullptr;
 
 // Initialization thread
 void initialize_handle(
@@ -106,7 +99,7 @@ void initialize_handle(
 void update_handle(const ddwaf_object *ruleset, ddwaf_object *diagnostics)
 {
     std::unique_lock lock{mutex}; // acquire write lock
-    ddwaf_handle old_handle = cur_ddwaf_handle.load(std::memory_order_acquire);
+    ddwaf_handle old_handle = cur_ddwaf_handle;
     ddwaf_handle new_handle = ddwaf_update(old_handle, ruleset, diagnostics);
     cur_ddwaf_handle = new_handle;
     ddwaf_destroy(old_handle);
@@ -122,16 +115,18 @@ ddwaf_context create_context() {
 }
 ```
 
-## `ddwaf_context`
+## `ddwaf_context` and `ddwaf_subcontext`
+
+`ddwaf_context` is not thread-safe. If a context can be touched by multiple
+threads (for example, when the web server hands off the same request to another
+thread), guard calls to `ddwaf_context_eval` and `ddwaf_context_destroy`. You
+must also prevent any evaluation after the owning handle has been destroyed.
 
-On the other hand, `ddwaf_context` is not thread-safe. If a `ddwaf_context` is
-used by multiple threads (in web servers where the processing of the request
-can move between several threads, or happen in several threads simultaneously),
-you need to use locks so that calls to `ddwaf_context_eval/destroy` are not run
-concurrently, and that changes made to the `ddwaf_context` in one thread through
-`ddwaf_context_eval/destroy` are visible to the other threads subsequently run
-`ddwaf_context_eval/destroy` on the same context. You also need to ensure that no calls
-to `ddwaf_context_eval/destroy` happen after `ddwaf_destroy` is called.
+When you only need isolated evaluation state but still share the same handle,
+prefer `ddwaf_context_init` per request. `ddwaf_subcontext_init` (documented in
+the API reference) can provide a cheaper clone when your binding benefits from
+sharing captures between stages. Subcontexts inherit the parent lifetime, so
+they must never outlive the original context.
 
 ```c++
 // each request will have one of these associated with it
@@ -156,3 +151,16 @@ void destroy_ctx(ctx_wrapper &wrapper) {
     wrapper.ctx = nullptr;
 }
 ```
+
+## Custom allocators and diagnostics
+
+Consult `docs/c-api/api.md` for the exact signatures of allocator hooks. Any
+binding that offers native memory tracking should expose `ddwaf_user_allocator_init`
+wrappers and document the ownership of `ddwaf_object`. The documented helpers in
+the header (`ddwaf_object_*`) ensure that objects stay consistent with their
+type tag.
+
+libddwaf can emit logs through `ddwaf_set_log_cb`. Bindings should translate
+the `DDWAF_LOG_LEVEL` levels into their host logging facilities and pay
+attention to thread-safety inside the callback. The callback can run from hot
+paths, so limit the amount of work performed there.
diff --git a/docs/changelog/CHANGELOG-latest.md b/docs/changelog/CHANGELOG-latest.md
new file mode 120000
index 000000000..d9113fc67
--- /dev/null
+++ b/docs/changelog/CHANGELOG-latest.md
@@ -0,0 +1 @@
+CHANGELOG-v2.0.0.md
\ No newline at end of file
diff --git a/CHANGELOG.md b/docs/changelog/CHANGELOG-v1.x.md
similarity index 100%
rename from CHANGELOG.md
rename to docs/changelog/CHANGELOG-v1.x.md
diff --git a/docs/changelog/CHANGELOG-v2.0.0.md b/docs/changelog/CHANGELOG-v2.0.0.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs/exclusions.md b/docs/exclusions.md
new file mode 100644
index 000000000..a27d10f83
--- /dev/null
+++ b/docs/exclusions.md
@@ -0,0 +1,120 @@
+# Exclusion Filters
+
+Exclusions let you refine how a ruleset responds to specific situations without
+editing the rules themselves. They are defined in the `exclusions` array of a
+configuration payload and come in two flavours:
+
+- **Rule exclusions** change the verdict of matching rules.
+- **Input exclusions** remove particular request fields from consideration while
+  the rule logic still runs.
+
+Both types share a common structure and can be combined in the same document.
+
+## Shared fields
+
+Every exclusion object accepts the following keys:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | string | yes | Unique identifier for diagnostics and deduplication. |
+| `min_version`, `max_version` | semantic version | no | Restrict the exclusion to specific libddwaf versions. |
+| `conditions` | array | no | Expression evaluated against request values. When omitted the exclusion is unconditional. |
+| `rules_target` | array | no | List of rules to affect. Each entry can provide `id`/`rule_id` (exact rule identifier) or a `tags` object to match by tag set. Omit to target every rule. |
+
+An exclusion must provide at least one of `conditions`, `rules_target`, or
+`inputs` (for input exclusions). If all of them are omitted the entry is
+rejected.
+
+## Rule exclusions
+
+A rule exclusion changes how selected rules behave once its conditions match.
+Use the `on_match` field to express the desired outcome:
+
+| Value | Effect |
+| --- | --- |
+| `bypass` (default) | Skip rule evaluation entirely. No event is produced. |
+| `monitor` | Evaluate the rule but force the verdict to monitoring and set the action to the built-in `monitor` action. |
+| `<custom action>` | Run the rule normally and override any produced action with the provided string. |
+
+Rule exclusions ignore the `inputs` field and do not remove data from the
+request. They are best suited for turning off noisy rules, forcing monitoring
+mode for specific traffic, or routing matches to a custom action.
+
+### Example
+
+```json
+{
+  "id": "skip-log4shell-on-backend",
+  "conditions": [
+    { "operator": "match_regex", "parameters": { "inputs": [ { "value": { "address": "server.address" } } ], "regex": "^10\\." } }
+  ],
+  "rules_target": [
+    { "rule_id": "log4shell" }
+  ],
+  "on_match": "bypass"
+}
+```
+
+This exclusion disables the `log4shell` rule whenever the server address starts
+with `10.`.
+
+## Input exclusions
+
+Input exclusions keep the rule active while hiding specific request fields. Use
+them when a rule should ignore known benign parameters or payload sections.
+
+Additional fields:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `inputs` | array | yes | List of addresses and optional key paths pointing to values that should be removed from rule evaluation. |
+
+Each entry inside `inputs` must contain:
+
+- `address` (string, required): data collection to inspect. Examples include
+  `server.request.query`, `server.request.body`, or any address recognised by
+  the ruleset.
+- `key_path` (array of strings, optional): navigates into nested structures.
+  Leave empty to ignore the entire address. Use `"*"` to match any key at that
+  depth. Omitted keys (such as array indices) are treated as wildcards.
+
+When the optional `conditions` array evaluates to `true`, all matching values
+described by `inputs` are removed for the targeted rules. Other rules continue
+to see the original data.
+
+### Example
+
+```json
+{
+  "id": "ignore-debug-parameter",
+  "inputs": [
+    {
+      "address": "server.request.query",
+      "key_path": ["debug"]
+    }
+  ],
+  "rules_target": [
+    { "tags": { "type": "security_scanner" } }
+  ]
+}
+```
+
+Here, any rule tagged with `type=security_scanner` ignores the `debug` query
+parameter. The exclusion applies unconditionally because no `conditions` field
+is provided.
+
+## When exclusions are evaluated
+
+- Configuration loading enforces unique `id` values and drops exclusions whose
+  version constraints do not match the running library.
+- During request processing libddwaf evaluates exclusion conditions before each
+  rule. The first successful match is memoised for the rest of the request,
+  keeping filters fast even when multiple rules reference them.
+- Rule exclusions determine the final verdict (`bypass`, `monitor`, or custom
+  action). Input exclusions prune fields and let the rule produce a normal
+  result using the reduced data.
+
+Use exclusions sparingly and document their intent. They provide fine-grained
+control over rule behaviour, but overly broad entries can hide important
+signals. Start with specific targets and conditions, monitor the effect, and
+expand only when necessary.
diff --git a/docs/operators.md b/docs/operators.md
new file mode 100644
index 000000000..96f9b27df
--- /dev/null
+++ b/docs/operators.md
@@ -0,0 +1,160 @@
+# Operator Reference
+
+libddwaf supports a mixture of low-level “scalar” match operators and higher-level detectors that encapsulate complex heuristics. This document enumerates every operator wired through `src/matcher` and `src/condition`, together with the arguments they expect in security rule definitions. Configuration examples follow the format consumed by the expression parser in `src/configuration/common/expression_parser.cpp`.
+
+Unless stated otherwise, operators consume data from the `inputs` argument (the list of addresses on which the condition runs). Each address can declare its own transformer chain; negated scalar operators accept at most one address.
+
+---
+
+## Scalar match operators
+
+These operators compare request data against literal values, numerical thresholds, or pattern libraries. They are implemented in `src/matcher/*` and are available both in positive form (`operator`) and negated form (`!operator`) unless noted.
+
+### `equals`
+- **Purpose:** Compare a value to a literal.
+- **Arguments:**  
+  - `inputs` (variadic list of addresses).  
+  - `type`: `"string"`, `"boolean"`, `"unsigned"`, `"signed"`, or `"float"`.  
+  - `value`: literal to compare against.  
+  - `delta` (optional, floats only): tolerance when comparing floating point numbers.
+- **Notes:** Supports negation (`!equals`) which must be scoped to a single address.
+
+### `exact_match`
+- **Purpose:** Match against a list of exact strings.
+- **Arguments:**  
+  - `inputs`.  
+  - Either `list` (array of strings) or `data` (rules-data identifier, mutually exclusive).
+- **Notes:** Works on string inputs only; negated form `!exact_match` is supported.
+
+### `greater_than`
+- **Purpose:** Numeric greater-than comparison.
+- **Arguments:**  
+  - `inputs`.  
+  - `type`: `"unsigned"`, `"signed"`, or `"float"`.  
+  - `value`: comparison threshold.
+- **Notes:** Negated form `!greater_than` inverts the comparison.
+
+### `lower_than`
+- **Purpose:** Numeric less-than comparison.
+- **Arguments:**  
+  - `inputs`.  
+  - `type`: `"unsigned"`, `"signed"`, or `"float"`.  
+  - `value`: comparison threshold.
+- **Notes:** Negated form `!lower_than` inverts the comparison.
+
+### `match_regex`
+- **Purpose:** Evaluate a RE2 regular expression.
+- **Arguments:**  
+  - `inputs`.  
+  - `regex`: pattern string.  
+  - `options` (optional map):  
+    - `min_length` (non-negative integer).  
+    - `case_sensitive` (boolean, defaults to `false`).
+- **Notes:** Negation `!match_regex` is available.
+
+### `match_regex_with_checksum`
+- **Purpose:** Run a regular expression alongside a checksum gate.
+- **Arguments:**  
+  - `inputs`.  
+  - `regex`: pattern string.  
+  - `checksum`: expected checksum identifier; compiled via `checksum_builder`.  
+  - `options` (optional): `min_length`, `case_sensitive`.
+- **Notes:** Negated form `!match_regex_with_checksum` is supported. Useful for large pattern sets where checksum pre-filtering trims evaluation cost.
+
+### `phrase_match`
+- **Purpose:** Fast multi-string search using the Aho–Corasick algorithm.
+- **Arguments:**  
+  - `inputs`.  
+  - `list`: array of phrases.  
+  - `options.enforce_word_boundary` (optional boolean) to require matches on word boundaries.
+- **Notes:** Negation `!phrase_match` is supported.
+
+### `ip_match`
+- **Purpose:** Match values against IP addresses or CIDR ranges.
+- **Arguments:**  
+  - `inputs`.  
+  - Either `list` (array of IP/CIDR strings) or `data` (rules-data identifier).  
+  - Optional transformers may normalise header values before matching.
+- **Notes:** Negated form `!ip_match` is supported. Lists are parsed into a radix tree internally.
+
+### `is_xss`
+- **Purpose:** Detect cross-site scripting payloads using libinjection.
+- **Arguments:** `inputs`.
+- **Notes:** Negated form `!is_xss` is supported.
+
+### `is_sqli`
+- **Purpose:** Detect SQL injection payloads using libinjection.
+- **Arguments:** `inputs`.
+- **Notes:** Negated form `!is_sqli` is supported.
+
+### `hidden_ascii_match`
+- **Purpose:** Flag strings containing hidden or non-printable ASCII characters.
+- **Arguments:** `inputs`.
+- **Notes:** Negated form `!hidden_ascii_match` is supported.
+
+### `exists` / `!exists`
+- **Purpose:** Assert the presence (`exists`) or absence (`!exists`) of addresses.
+- **Arguments:**  
+  - `exists`: `inputs` (variadic). Returns `true` as soon as any address resolves. Key paths are ignored.  
+  - `!exists`: `inputs` (exactly one). Returns `true` only when the address cannot be resolved.
+- **Notes:** Implemented as scalar conditions; the negated form must target a single address.
+
+---
+
+## Detector operators
+
+Detector operators combine multiple signals and heuristics. They are versioned: a rule can request a specific revision using the `operator@vN` syntax, but the engine enforces the maximum version compiled into libddwaf (see the `version` constant in each detector).
+
+### `lfi_detector` (≤ v2)
+- **Purpose:** Detect local file inclusion attempts.
+- **Arguments:**  
+  - `resource`: unary argument pointing to the resolved filesystem path (for example, the file ultimately accessed).  
+  - `params`: variadic argument listing user-controlled inputs that contributed to the path.
+- **Behaviour:** Validates that user input is not escaping directories or forging absolute paths. Handles Unix and Windows path semantics.
+
+### `ssrf_detector` (≤ v3)
+- **Purpose:** Detect server-side request forgery attempts.
+- **Arguments:**  
+  - `resource`: the outbound URL being fetched.  
+  - `params`: request parameters associated with that URL.  
+  - `options` (optional map):  
+    - `authority-inspection` (bool, default `true`).  
+    - `path-inspection` (bool, default `false`).  
+    - `query-inspection` (bool, default `false`).  
+    - `forbid-full-url-injection` (bool, default `false`).  
+    - `enforce-policy-without-injection` (bool, default `false`).  
+  - `policy` (optional map):  
+    - `allowed-schemes` (array of scheme strings; defaults to `["https","http","ftps","ftp"]`).  
+    - `forbidden-domains` (array; defaults provided in the header).  
+    - `forbidden-ips` (array; defaults include RFC1918, loopback, and cloud metadata ranges).
+- **Behaviour:** Normalises the destination URL, evaluates it against the policy (schemes, domains, IPs), and inspects user parameters for full-URL injections.
+
+### `sqli_detector` (≤ v3)
+- **Purpose:** Detect SQL injection by analysing the concrete query and bound parameters.
+- **Arguments:**  
+  - `resource`: SQL statement emitted by the application.  
+  - `params`: parameters interpolated into the statement.  
+  - `db_type`: string identifying the SQL dialect (`mysql`, `pgsql`, `sqlite`, etc.).
+- **Behaviour:** Tokenises the query, strips literals, and inspects parameter tokens for tautologies, comment abuse, or structural anomalies given the specified dialect.
+
+### `shi_detector` (≤ v1)
+- **Purpose:** Detect shell injection across command invocations.
+- **Arguments:**  
+  - `resource`: shell command (string or array of tokens).  
+  - `params`: user-controlled arguments being appended to the command.
+- **Behaviour:** Tokenises both the base command and parameters, looking for injected commands or dangerous expansions (for example, `;`, `&&`, subshell operators). Supports string or array representations of the command.
+
+### `cmdi_detector` (≤ v1)
+- **Purpose:** Detect command injection patterns in command-line executions.
+- **Arguments:**  
+  - `resource`: executable path or command string captured from the application.  
+  - `params`: user-provided arguments.
+- **Behaviour:** Identifies attempt to append shell directives or bypass argument escaping by understanding known shell option formats (for Bash, PowerShell, etc.) and highlighting injected payloads.
+
+---
+
+## Operator negation
+
+Scalar match operators (the ones backed by `src/matcher`) automatically expose a negated variant prefixed with `!`—for example, `!match_regex` or `!ip_match`. Negated operators accept exactly one address and invert the underlying predicate. Detector operators (`*_detector`) do **not** provide negated forms; wrap them in logical NOT expressions if alternative behaviour is needed.
+
+When combining operators, remember that each address may declare transformers and that the global condition applies them in the order specified in the rule definition.
diff --git a/docs/overview.md b/docs/overview.md
new file mode 100644
index 000000000..ad83ed1b6
--- /dev/null
+++ b/docs/overview.md
@@ -0,0 +1,116 @@
+# Understanding libddwaf
+
+libddwaf is Datadog’s embeddable web application firewall engine. It ingests a declarative security configuration (rules, exclusions, processors, actions) and exposes a compact C API that any tracer or agent can use to evaluate inbound requests. At runtime the library:
+
+1. Parses one or more configuration documents into an immutable **WAF handle** (`ddwaf_handle`).
+2. Creates per-request **contexts** (`ddwaf_context`) bound to the handle and a memory allocator.
+3. Accepts request metadata as a tree of `ddwaf_object` values keyed by semantic **addresses** such as `server.request.body` or `http.client_ip`.
+4. Produces structured matches, derived attributes, and actions when rules trigger.
+
+The evaluation pipeline is incremental. Each call to `ddwaf_context_eval` updates the context with new data, derives additional inputs, applies exclusions, evaluates rules, and finally runs any post processing steps before returning results.
+
+---
+
+## Execution Pipeline
+
+When a context receives new data, libddwaf processes it in a fixed order:
+
+1. **Preprocessors** enrich or rewrite the input map, often normalising raw user input into structured addresses used by rules.
+2. **Exclusion filters** decide which rules or inputs must be ignored for this evaluation (for example to suppress alerts on known-safe endpoints).
+3. **Rules** run matchers against the current address store and queue actions and events when they trigger.
+4. **Postprocessors** run after rule evaluation to augment the result payload—typically by calculating additional attributes or serialising payloads for downstream systems.
+5. The serializer aggregates matches, actions, derived attributes, and timeout information into the `result` object returned by `ddwaf_context_eval`.
+
+Any step can terminate early if the caller’s timeout elapses; in that case the engine short-circuits remaining work while preserving as much partial state as possible.
+
+---
+
+## Configuration Primitives
+
+### Rules
+
+Rules define the core detection logic. Each rule carries:
+
+- Metadata (`id`, `name`, and `tags`) that identifies its purpose and target module.
+- One or more **conditions**, each of which applies an operator (such as `match_regex`, `phrase_match`, or `validate_schema`) to a set of addresses. Conditions may also specify key paths and transformers.
+- Optional **actions** or overrides that tell integrating products how to respond when the rule matches.
+
+Rules are grouped by **module** internally (for example `network-acl`, `business-logic`, `waf`). Modules isolate specialised detection logic and let the engine maintain separate matcher caches. Each module sorts its rules first by the verdict they can emit (`block` before `monitor`), then by the rule **source** (user vs. Datadog) according to the precedence defined for that module (see *Module ordering and short-circuiting* below), and finally by the rule “type” string when applicable. If a rule returns a blocking verdict the module stops evaluating further rules, avoiding duplicate work once a decisive outcome is known. Monitor-level matches still allow evaluation to continue so other informative events can be collected.
+
+#### Module ordering and short-circuiting
+
+`src/builder/module_builder.cpp` assigns every rule to one of seven categories:
+
+1. `network-acl`
+2. `authentication-acl`
+3. `custom-acl`
+4. `configuration`
+5. `business-logic`
+6. `rasp`
+7. `waf`
+
+The engine evaluates modules in that exact order every time `ddwaf_context_eval` runs. The first two categories are marked as *non-expiring* in `module_builder.hpp`, so `network-acl` and `authentication-acl` always run to completion even if the caller-provided timeout expires. Modules `custom-acl` through `waf` propagate the deadline and will abort early once the budget is exhausted.
+
+Within each module, rule precedence differs:
+
+- `network-acl`, `authentication-acl`, and `rasp` examine Datadog-supplied rules before user-defined ones. These guardrails are meant to fire reliably even when custom rules are misconfigured.
+- `custom-acl`, `configuration`, `business-logic`, and `waf` prioritise user rules so that tenant-specific logic can take precedence over built-in defaults.
+
+The `waf` module groups rules by their `type` tag. For each type, user blocking rules run first, followed by Datadog blocking rules, then user monitor rules, and finally Datadog monitor rules. A blocking verdict inside any collection short-circuits the remaining collections and modules. This layering ensures user logic can override defaults where appropriate without sacrificing baseline coverage from Datadog’s managed rules. When a module produces a blocking verdict, remaining modules are skipped and the pipeline advances directly to postprocessors.
+
+---
+
+## Evaluation Flow
+
+The diagram below summarises how the primitives interact during a single call to `ddwaf_context_eval`:
+
+During a single `ddwaf_context_eval` call:
+
+- The incoming `ddwaf_object` map is handed to preprocessors (`evaluate: true` processors) which can create or rewrite addresses. Their outputs become part of the context store.
+- Rule and input exclusion filters run next, pruning the address set or muting matching rules before any detection logic executes.
+- The engine iterates through the modules in fixed order (`network-acl`, `authentication-acl`, `custom-acl`, `configuration`, `business-logic`, `rasp`, `waf`). The first two modules are non-expiring and always run to completion; the remaining modules respect the caller’s timeout.
+- Inside each module, rules are ordered by verdict, source precedence (user vs. Datadog), and optionally type. If a rule returns a blocking verdict the module stops and subsequent modules are skipped; monitor verdicts allow evaluation to continue.
+- Once the module loop finishes (or short-circuits), postprocessors (`output: true` processors) enrich the collector with derived attributes that will appear in the result payload.
+- The serializer produces the final `result` object: matches, actions, derived attributes, execution metadata, and the `DDWAF_OK`/`DDWAF_MATCH` status that the caller receives.
+
+This sequencing keeps the evaluation deterministic while allowing preprocessors, filters, and postprocessors to cooperate around the shared context state.
+
+### Processors: Preprocessors and Postprocessors
+
+Processors are reusable pieces of logic that transform request data. Each entry in the `processors` section of the configuration specifies a `generator` (for example `uri_parse`, `extract_schema`, `jwt_decode`, or `fingerprint`), optional conditions, and a set of input/output mappings.
+
+Two booleans determine when a processor runs:
+
+- `evaluate: true` marks a **preprocessor**. It runs before exclusions and rules, and any derived addresses are available to matchers in the same evaluation. Typical use cases include decomposing URLs, parsing JWTs, or generating request fingerprints.
+- `output: true` marks a **postprocessor**. It runs after rules complete and can emit additional attributes into the result object—for example to expose the parsed URI or schema extraction summaries to telemetry pipelines.
+
+A single processor can act as both a pre- and postprocessor by setting both flags.
+
+Processors are cached per context so expensive computations are only repeated when their inputs change. They can also depend on **scanners**, which provide auxiliary data (for example known good fingerprints) to generator implementations.
+
+### Exclusion Filters
+
+Exclusion filters allow operators to silence noisy rules or drop inputs that should not be considered during evaluation. The configuration distinguishes two flavours:
+
+- **Rule filters** decide whether entire rules (or groups of rules identified by tags) should be skipped. They often key off request metadata such as the current service, endpoint, or environment.
+- **Input filters** remove or redact specific addresses before rules see them. They are useful to shield sensitive fields from inspection or to ignore known benign payloads that would otherwise trigger false positives.
+
+Both filter types execute before rule evaluation, and their decisions are cached so later calls within the same context remain consistent.
+
+### Postprocessors (Result Enrichment)
+
+Although postprocessors are defined alongside preprocessors, it is worth calling them out separately: a postprocessor (`output: true`) runs after all rules have evaluated and has access to the request store, the intermediate collector, and the actions selected by the rules. Its job is to attach derived attributes—such as structured URI fields, schema summaries, or decoded tokens—to the `attributes` section of the result returned by `ddwaf_context_eval`. Those attributes help downstream systems present rich diagnostics without recomputing heavy transformations.
+
+---
+
+## Putting It All Together
+
+A minimal integration typically follows these steps:
+
+1. **Load configuration**: parse the JSON/YAML documents describing rules, processors, exclusions, and overrides into `ddwaf_object` instances, then call `ddwaf_init` (or drive the builder API for multi-document workflows).
+2. **Create a context per request**: obtain an allocator (`ddwaf_get_default_allocator` or a custom one) and call `ddwaf_context_init`.
+3. **Populate addresses**: build a map of request data (`ddwaf_object_set_map` plus insertion helpers) covering the addresses referenced by your rules and preprocessors.
+4. **Evaluate**: call `ddwaf_context_eval` with the map, allocator, an optional result object, and a timeout. Inspect `DDWAF_MATCH` or `DDWAF_OK`, along with the populated `events`, `actions`, and `attributes`.
+5. **Clean up**: destroy the result with `ddwaf_object_destroy`, then destroy the context (and allocator if you created a custom one).
+
+Because preprocessors, exclusion filters, and postprocessors all operate deterministically on the same address store, their combined effect keeps the rule execution focused on actionable signals while still surfacing rich telemetry to downstream pipelines.
diff --git a/docs/processors.md b/docs/processors.md
new file mode 100644
index 000000000..72e114820
--- /dev/null
+++ b/docs/processors.md
@@ -0,0 +1,107 @@
+# Processor Reference
+
+Processors are reusable building blocks that derive new addresses from existing request data. They can run before rule evaluation to enrich the object store (preprocessors) or after evaluation to attach additional attributes to the result payload (postprocessors). Each processor definition lives in the `processors` section of a configuration document and is parsed by `configuration/processor_parser.cpp`.
+
+---
+
+## Lifecycle and execution
+
+- **Expression gate:** every processor carries a simplified expression (`conditions`) evaluated against the current context. If the expression returns `false` the processor is skipped for that evaluation.
+- **Mappings:** for every entry under `parameters.mappings`, the engine resolves the addresses declared in the mapping according to the processor’s `param_names`. Key paths are supported but each parameter currently accepts a single address.
+- **Evaluate flag:** when `evaluate: true`, the generated object is inserted into the context’s object store. Downstream rules can immediately consume the derived address.
+- **Output flag:** when `output: true`, the generated object is added to the attribute collector so that it surfaces in the `attributes` map returned by `ddwaf_context_eval`.
+- **Caching:** `processor_cache` keeps track of outputs that were already produced during the same evaluation (`generated`), optional arguments that have already been resolved (`evaluated`), and processor-specific state (for example fingerprint fragments). This prevents duplicate work when the same context is evaluated repeatedly.
+- **Memory ownership:** preprocessors that feed rule evaluation clone their result into the user-provided allocator before returning it to the caller; otherwise results are stored directly in the default allocator.
+
+A processor configured with `evaluate: true, output: false` behaves like a classic preprocessor. A processor with `evaluate: false, output: true` acts as a pure postprocessor. Many rule packs use `waf.context.processor` to gate expensive postprocessors so that agents can opt-in address by address.
+
+---
+
+## Configuration fields
+
+Each entry in the `processors` array supports:
+
+| Field | Description |
+| --- | --- |
+| `id` | Unique identifier for the processor definition. |
+| `generator` | The processor type (see the list below). |
+| `conditions` | Optional simplified expression that must evaluate to `true` before the processor runs. |
+| `parameters.mappings` | Array of mappings. Every mapping defines the required inputs (per `param_names`) and an `output` address. |
+| `parameters.scanners` | Optional include/exclude list of scanners (only used by `extract_schema`). |
+| `min_version` / `max_version` | Optional semantic-version bounds for libddwaf compatibility. |
+| `evaluate` | Boolean, defaults to `true`. Controls whether the output is inserted into the object store. |
+| `output` | Boolean, defaults to `false`. Controls whether the output is exported via the attribute collector. |
+
+If neither `evaluate` nor `output` is set, the processor is rejected during parsing.
+
+---
+
+## Scanners
+
+`extract_schema` can depend on scanners (see `src/scanner.hpp`) to annotate or filter parts of the generated schema. Scanners can be referenced by ID or by tags. The builder resolves references with the following precedence:
+
+1. Exclusions by ID (apply to everything).
+2. Inclusions by ID.
+3. Exclusions by tags.
+4. Inclusions by tags.
+
+The resulting set of `scanner*` pointers is passed to the processor instance.
+
+---
+
+## Supported generators
+
+### `extract_schema`
+- **Inputs:** `inputs` (variadic). Each mapping typically targets a request container such as `server.request.body`.
+- **Usage:** Commonly configured with `evaluate: true` to materialise `{address}.schema` maps consumed by rules; optional `output: true` exposes the schema in WAF results.
+- **Behaviour:** Walks complex objects up to a bounded depth (`max_container_depth`), summarises value types (null, boolean, integer, real, string), and records array shapes. The result is a compact JSON-like structure (see integration tests for examples). Scanners can tag or prune fields based on custom logic.
+
+### `jwt_decode`
+- **Inputs:** `inputs` (single address), often pointing to `server.request.headers.no_cookies["authorization"]`.
+- **Usage:**  
+  - `evaluate: true, output: false` (preprocessor) populates `server.request.jwt` so rules can inspect JWT header/payload claims.  
+  - `evaluate: false, output: true` (postprocessor) exports the decoded token in results.
+- **Behaviour:** Looks for `"Bearer "` prefixes, splits the token into header/payload/signature segments, base64url-decodes header and payload, and emits a map such as:  
+  `{"header": {...}, "payload": {...}, "signature": {"available": true}}`.
+
+### `uri_parse`
+- **Inputs:** `inputs` (single string address, for example `server.request.uri.raw`).
+- **Usage:** Usually configured as a postprocessor (`evaluate: false, output: true`) to expose structured URI data. With `evaluate: true` it can populate derived addresses for rules.
+- **Behaviour:** Parses the URI into scheme, user info, host, port, path, fragment, and a map of query parameters where repeated keys are promoted to arrays. Outputs a map with keys `scheme`, `userinfo`, `host`, `port`, `path`, `query`, and `fragment`.
+
+### Fingerprint processors
+
+These generators emit deterministic strings (fragments) prefixed with the fingerprint family. The fragments follow the `<prefix>-<normalized components…>` convention.
+
+- **`http_endpoint_fingerprint`**  
+  - **Inputs:** `method`, `uri_raw`, optional `query`, optional `body`.  
+  - **Output address:** `_dd.appsec.fp.http.endpoint`.  
+  - **Behaviour:** Normalises the method, strips queries from the raw URI, hashes selected parameters, and caches fragments per context to avoid recomputation when optional inputs arrive late.
+
+- **`http_header_fingerprint`**  
+  - **Inputs:** `headers` (map).  
+  - **Output address:** `_dd.appsec.fp.http.header`.  
+  - **Behaviour:** Records which well-known headers are present, normalises unknown headers, and includes a lowercase hash of the User-Agent.
+
+- **`http_network_fingerprint`**  
+  - **Inputs:** `headers` (map).  
+  - **Output address:** `_dd.appsec.fp.http.network`.  
+  - **Behaviour:** Tracks which forwarding headers carry client IP information and counts comma-separated IPs in the highest precedence header.
+
+- **`session_fingerprint`**  
+  - **Inputs:** optional `cookies`, optional `session_id`, optional `user_id`.  
+  - **Output address:** `_dd.appsec.fp.session`.  
+  - **Behaviour:** Hashes user/session identifiers and the cookie map to build a session fingerprint. Optional inputs trigger re-evaluation only when new data appears thanks to `processor_cache.evaluated`.
+
+Fingerprints are usually configured as postprocessors (`evaluate: false, output: true`) and gated by the `waf.context.processor["fingerprint"]` address.
+
+---
+
+## Practical tips
+
+- **Opt-in toggles:** use `waf.context.processor` flags in rule packs so agents can enable expensive processors selectively.
+- **Key paths:** mappings accept `key_path`, but the current parser only consumes the first address per parameter. If you need multiple inputs, define multiple mappings targeting different outputs.
+- **Preprocessor vs postprocessor:** remember that preprocessors mutate the context store. Postprocessors never affect rule evaluation—only the result payload.
+- **Timeouts:** processors honour the evaluation deadline; long-running logic should handle `ddwaf::timeout_exception`.
+
+Refer to `tests/integration/processors/*` for concrete configuration examples and expected outputs.
diff --git a/docs/rules.md b/docs/rules.md
new file mode 100644
index 000000000..775d35529
--- /dev/null
+++ b/docs/rules.md
@@ -0,0 +1,125 @@
+# Rule Definitions
+
+Rules describe the detections performed by libddwaf. They live inside either the
+`rules` array (Datadog-maintained content) or `custom_rules` (user-supplied
+additions) within a configuration document. Each entry declares the conditions
+to inspect in the request, the metadata attached to any matches, and the
+actions that should follow.
+
+## Required structure
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | string | yes | Stable identifier. Must be unique across all rules (base and custom). |
+| `name` | string | yes | Human-readable label shown in diagnostics. |
+| `tags` | object | yes | Metadata used for grouping, routing, and overrides. Must include a `type` key (for example `"type": "lfi"`). Optionally include `category`, `module`, or any other taxonomy keys you rely on. |
+| `conditions` | array | yes | List of condition objects describing the match logic. See the [Operator Reference](operators.md) for supported operators and parameter schemas. |
+
+## Optional common fields
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `enabled` | boolean | `true` | Disable a rule without removing it from the document. |
+| `min_version`, `max_version` | semantic version | unrestricted | Restrict the rule to specific libddwaf versions. |
+| `transformers` | array | empty | Sequence of transformer identifiers applied to all inputs referenced by the rule before conditions run. See the [Transformer Reference](transformers.md). At most 10 entries are accepted. |
+| `on_match` | array of strings | empty | Ordered list of action identifiers to emit when the rule matches. Actions are resolved at runtime through the ruleset's action catalogue. |
+| `output` | object | implicit event+keep | Fine-tune the generated event and attributes. Details below. |
+
+### Tags and modules
+
+- `tags.type` is required and typically mirrors the threat category (for example
+  `sql_injection`, `lfi`, or `grpc_request_blocking`).
+- `tags.module` is optional. When present it controls rule grouping inside the
+  engine. Recognised values include `network-acl`, `authentication-acl`,
+  `custom-acl`, `configuration`, `business-logic`, `rasp`, and `waf` (default).
+- Additional tags are free-form and can be used to express application, service,
+  or platform metadata. They are emitted in rule events and are also available
+  to rule overrides or filters via tag-based selectors.
+
+## Output controls
+
+The `output` object lets you shape the payload returned when a rule matches:
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `event` | boolean | `true` | When `false`, the rule does not generate an event. Combine with attributes to create silent annotation rules. |
+| `keep` | boolean | `true` | When `false`, the rule outcome may be dropped during sampling. Leave enabled when the match should always be preserved. |
+| `attributes` | object | `{}` | Map of additional fields attached to the rule result. Each entry accepts either a static `value` or a reference to request data via `address`/`key_path`. |
+
+Attribute entries support two shapes:
+
+```json
+{
+  "attributes": {
+    "static-example": { "value": "constant value" },
+    "copied-field": {
+      "address": "server.request.query",
+      "key_path": ["user_id"]
+    }
+  }
+}
+```
+
+- `value` accepts strings, integers, floats, and booleans.
+- Referencing request data requires an `address` and an optional `key_path`.
+  Each element in `key_path` is either a string (map key) or an integer (array
+  index). Omit `key_path` to copy the entire address.
+
+Rules must generate at least one event or attribute. A rule with
+`output.event = false` and an empty `attributes` object is rejected during
+parsing.
+
+## Rule evaluation overview
+
+- Conditions operate on the request `values` data source. Each condition
+  contributes matches that are collected in the rule's event payload.
+- Transformers listed at the rule level run before the operator chain and apply
+  to every input reference in the rule.
+- `on_match` actions fire in the order provided. Combine them with
+  [exclusion filters](exclusions.md) to tune the eventual verdict
+  (`monitor`, `block`, or custom actions).
+- Disabled rules, rules gated by incompatible versions, or rules filtered out by
+  exclusions are skipped without evaluating their conditions.
+
+## Example rule
+
+```json
+{
+  "id": "my-app-login-bruteforce",
+  "name": "Login brute force detector",
+  "tags": {
+    "type": "security_scanner",
+    "category": "misc_checks",
+    "module": "waf",
+    "service": "frontend"
+  },
+  "transformers": ["remove_nulls"],
+  "conditions": [
+    {
+      "operator": "match_regex",
+      "parameters": {
+        "regex": "(?i)login failed",
+        "inputs": [
+          { "address": "server.response.body" }
+        ]
+      }
+    }
+  ],
+  "on_match": ["block_request"],
+  "output": {
+    "event": true,
+    "keep": true,
+    "attributes": {
+      "response_body": {
+        "address": "server.response.body",
+        "key_path": []
+      }
+    }
+  }
+}
+```
+
+This example inspects the response body for an authentication failure pattern,
+ensures the match is always kept, and attaches the full response body to the
+generated event while instructing the engine to trigger the `block_request`
+action.
diff --git a/docs/transformers.md b/docs/transformers.md
new file mode 100644
index 000000000..1d6aec87e
--- /dev/null
+++ b/docs/transformers.md
@@ -0,0 +1,30 @@
+# Transformer Reference
+
+Transformers preprocess request data before operators or rules consume it. They can be chained within rule conditions and are applied in the order listed.
+
+| Name (v1.12+) | Alias (≤ v1.11) | Purpose | Example | Availability |
+| --- | --- | --- | --- | --- |
+| `remove_nulls` | `removeNulls` | Strip null bytes. | `bla\0bla → blabla` | ≥ v1.0 |
+| `html_entity_decode` | `htmlEntityDecode` | Decode HTML entities (UTF-16 aware). | `&lt;&gt;&amp;&quot;&nbsp; → <>&"\xa0` | ≥ v1.0 |
+| `js_decode` | `jsDecode` | Decode JavaScript escapes (UTF-16 aware). | `bla\x20bla → bla bla`<br>`\udbff\udfff → \xF0\x8F\xBF\xBF` | ≥ v1.0 |
+| `css_decode` | `cssDecode` | Decode CSS escapes (UTF-16 aware). | `"CSS\%0a tran\sf → CSS transformations` | ≥ v1.0 |
+| `base64_encode` | `base64Encode` | Base64 encode. | `bla → Ymxh` | ≥ v1.0 |
+| `base64_decode` | `base64Decode` | Decode Base64 (RFC 4648). | `Zm9v → foo`<br>`Zm==============9v → ❌` | ≥ v1.0 |
+| `base64DecodeExt` | — | Decode Base64 (RFC 2045). **Deprecated** in v1.12. | `Zm==============9v → foo` | ≥ v1.0 (deprecated v1.12) |
+| `url_decode` | `urlDecode` | Decode URL encoding. | `%01hex+encoder%0f → \x01hex encoder\x0f` | ≥ v1.0 |
+| `url_decode_iis` | `urlDecodeUni` | Decode URL encoding with IIS extensions. | `%u1234 → \xE1\x88\xB4` | ≥ v1.0 |
+| `normalize_path` | `normalizePath` | Collapse relative path segments. | `pony/../bla/ → bla/` | ≥ v1.0 |
+| `normalize_path_win` | `normalizePathWin` | Collapse Windows-style relative paths. | `pony\\..\\bla\\ → bla/` | ≥ v1.0 |
+| `compress_whitespace` | `compressWhiteSpace` | Replace repeated whitespace with a single space. | `bla  bla → bla bla` | ≥ v1.0 |
+| `lowercase` | `lowercase` | Convert to lowercase. | `BlA → bla` | ≥ v1.0 |
+| `length` | — | Compute string length. **Deprecated** in v1.12. | `bla → 3` | ≥ v1.0 (deprecated v1.12) |
+| `shell_unescape` | `cmdLine` | Remove shell escaping. | `normal \t\v\f\n\r (really) → normal(really)` | ≥ v1.0 |
+| `remove_comments` | `removeComments` | Strip C/HTML/SQL/shell comments. | `a/*b*/c<!--d-->e--f → ace` | ≥ v1.0 |
+| `numerize` | — | Parse integer strings (INT64_MIN ↔ UINT64_MAX). **Deprecated** in v1.12. | `"-123" → -123`<br>`"1.0" → ❌` | ≥ v1.0 (deprecated v1.12) |
+| `url_basename` | `_sqr_basename` | Extract filename from URI. | `/path/index.php?a=b → index.php` | ≥ v1.0 |
+| `url_path` | `_sqr_filename` | Extract path from URI. | `/path/index.php?a=b → /path/index.php` | ≥ v1.0 |
+| `url_querystring` | `_sqr_querystring` | Extract query string from URI. | `/path/index.php?a=b#d → a=b` | ≥ v1.0 |
+| `unicode_normalize` | — | Apply Unicode NFKD normalization to UTF-8 strings. | `a𝑎éßıfi2⁵—⅖ → aaessifi25-2/5` | ≥ v1.5 |
+| `keys_only` | — | Flatten structured data to a list of keys. | `{ a: b, c: { d: e } } → [a, c, d]` | ≥ v1.1 |
+
+Deprecated transformers remain available for backward compatibility but should be avoided in new rules.
diff --git a/docs/upgrading/UPGRADING-latest.md b/docs/upgrading/UPGRADING-latest.md
new file mode 120000
index 000000000..08b9e86c5
--- /dev/null
+++ b/docs/upgrading/UPGRADING-latest.md
@@ -0,0 +1 @@
+UPGRADING-v2.0.md
\ No newline at end of file
diff --git a/UPGRADING.md b/docs/upgrading/UPGRADING-v1.x.md
similarity index 100%
rename from UPGRADING.md
rename to docs/upgrading/UPGRADING-v1.x.md
diff --git a/docs/upgrading/UPGRADING-v2.0.md b/docs/upgrading/UPGRADING-v2.0.md
new file mode 100644
index 000000000..c29fa5bcc
--- /dev/null
+++ b/docs/upgrading/UPGRADING-v2.0.md
@@ -0,0 +1,170 @@
+# Upgrading libddwaf
+
+This guide helps you migrate call sites of the C API from libddwaf 1.30.x to 2.0.0. It captures the high-impact breaking changes and illustrates them with snippets lifted from the integration tests that ship with 2.0.
+
+## Migration Overview
+- Evaluation limits, obfuscator regexes and the result free hook inside `ddwaf_config` have been removed. The core now enforces internal limits; only the obfuscator survives and must be supplied inside configuration documents when needed. All memory ownership should switch to the allocator API.
+- `ddwaf_run` has been replaced by `ddwaf_context_eval`. Persistent and ephemeral maps are merged into a single input object, and every evaluation needs an allocator handle.
+- `ddwaf_object_*` constructors now accept the allocator that owns the storage. Container insertion helpers were renamed, and getters migrated to a namespaced family (for example `ddwaf_object_get_type`).
+- Context cloning exposed through `ddwaf_subcontext` and the allocator factories enable safe parallel use. Builders no longer take a `ddwaf_config*` argument.
+
+## 1. Remove legacy runtime configuration
+
+`ddwaf_config` and the macros `DDWAF_MAX_STRING_LENGTH`, `DDWAF_MAX_CONTAINER_DEPTH`, `DDWAF_MAX_CONTAINER_SIZE` and `DDWAF_RUN_TIMEOUT` disappeared. Evaluation limits are no longer user-configurable: libddwaf 2.0 ships with built-in safeguards and rejects oversized inputs internally. If you depended on the obfuscator settings, provide them through the configuration documents you load via `ddwaf_init` or `ddwaf_builder_add_or_update_config` (see `src/configuration/configuration_manager.cpp` for the supported `obfuscator` section). There is no replacement for the removed limits hooks.
+
+## 2. Update initialization and evaluation
+
+`ddwaf_init` now only expects the ruleset and an optional diagnostics object. Context creation requires an allocator, and the evaluation call takes a single request payload. The following example shows the common migration (compare `tests/integration/context/test.cpp` with its `1.30.0` counterpart):
+
+```c
+/* libddwaf 1.30.x */
+ddwaf_config cfg{
+    {.max_container_size = 256, .max_container_depth = 20, .max_string_length = 4096},
+    {.key_regex = nullptr, .value_regex = nullptr},
+    ddwaf_object_free
+};
+
+ddwaf_handle handle = ddwaf_init(&ruleset, &cfg, /*diagnostics=*/nullptr);
+ddwaf_context ctx = ddwaf_context_init(handle);
+
+ddwaf_object args = DDWAF_OBJECT_MAP;
+ddwaf_object tmp;
+ddwaf_object_map_add(&args, "value", ddwaf_object_string(&tmp, "rule2"));
+
+ddwaf_object result;
+DDWAF_RET_CODE rc = ddwaf_run(ctx, &args, /*ephemeral=*/nullptr, &result, timeout);
+ddwaf_object_free(&result);
+ddwaf_context_destroy(ctx);
+ddwaf_destroy(handle);
+```
+
+```c
+/* libddwaf 2.0.0 */
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+ddwaf_handle handle = ddwaf_init(&ruleset, /*diagnostics=*/nullptr);
+ddwaf_context ctx = ddwaf_context_init(handle, alloc);
+
+ddwaf_object args;
+ddwaf_object_set_map(&args, 1, alloc);
+ddwaf_object_set_string(
+    ddwaf_object_insert_key(&args, "value", sizeof("value") - 1, alloc),
+    "rule2", sizeof("rule2") - 1, alloc);
+
+ddwaf_object result;
+DDWAF_RET_CODE rc = ddwaf_context_eval(ctx, &args, alloc, &result, timeout);
+ddwaf_object_destroy(&result, alloc);
+ddwaf_context_destroy(ctx);
+ddwaf_destroy(handle);
+```
+
+Key points:
+
+- The request data passed to `ddwaf_context_eval` must remain valid until the context (or any subcontext) is destroyed because libddwaf can hold references to the objects you insert.
+- You can create lightweight clones with `ddwaf_subcontext_init` when you need concurrent evaluations that share the same persistent state (see `tests/integration/context/test.cpp:508` for usage). Subcontexts reuse the allocator you gave to the parent.
+
+## 3. Manage allocators explicitly
+
+Memory ownership is now routed through `ddwaf_allocator`. Every object that can allocate memory has an overload that accepts an allocator, and any destruction (objects, contexts, results) must receive the same allocator.
+
+- The default allocator is returned by `ddwaf_get_default_allocator()` and is used throughout the integration tests (`tests/integration/context/test.cpp`). The pointer is owned by libddwaf; do not pass it to `ddwaf_allocator_destroy`.
+- Pool and monotonic allocators (`ddwaf_{synchronized,unsynchronized}_pool_allocator_init`, `ddwaf_monotonic_allocator_init`) reduce per-request allocations (`tests/integration/interface/allocator/test.cpp:16`).
+- Provide your own hooks with `ddwaf_user_allocator_init`. The snippet below is adapted from `tests/integration/interface/allocator/test.cpp:539`:
+
+```c
+static void *counting_alloc(void *udata, size_t bytes, size_t alignment) { /* ... */ }
+static void counting_free(void *udata, void *p, size_t bytes, size_t alignment) { /* ... */ }
+
+counting_allocator state{};
+ddwaf_allocator alloc =
+    ddwaf_user_allocator_init(&counting_alloc, &counting_free, &state, /*udata_dtor=*/nullptr);
+
+ddwaf_context ctx = ddwaf_context_init(handle, alloc);
+/* ... build inputs and call ddwaf_context_eval ... */
+ddwaf_context_destroy(ctx);
+ddwaf_allocator_destroy(alloc);
+```
+
+Whenever you clone or destroy `ddwaf_object` instances (for instance via `ddwaf_object_clone`, `ddwaf_object_destroy`), pass the allocator that owns their memory.
+
+## 4. Refactor `ddwaf_object` helpers
+
+`ddwaf_object` changed from macro-based initialisers to allocator-aware setters and insertion helpers. The example below mirrors the change implemented in `tests/integration/context/test.cpp`.
+
+```c
+/* libddwaf 1.30.x */
+ddwaf_object root = DDWAF_OBJECT_MAP;
+ddwaf_object tmp, nested = DDWAF_OBJECT_MAP;
+ddwaf_object_map_add(&nested, "key", ddwaf_object_string(&tmp, "rule3"));
+ddwaf_object_map_add(&root, "value2", &nested);
+```
+
+```c
+/* libddwaf 2.0.0 */
+ddwaf_object root;
+ddwaf_object_set_map(&root, 1, alloc);
+ddwaf_object *nested = ddwaf_object_insert_key(&root, "value2", sizeof("value2") - 1, alloc);
+ddwaf_object_set_map(nested, 1, alloc);
+ddwaf_object_set_string(
+    ddwaf_object_insert_key(nested, "key", sizeof("key") - 1, alloc),
+    "rule3", sizeof("rule3") - 1, alloc);
+```
+
+Additional tips:
+
+- Choose the string setter that matches your ownership model:
+  - `ddwaf_object_set_string` copies the buffer.
+  - `ddwaf_object_set_string_literal` marks the storage as caller-owned and never frees it.
+  - `ddwaf_object_set_string_nocopy` keeps a pointer you manage.
+- Arrays and maps are sized up-front (`ddwaf_object_set_array`, `ddwaf_object_set_map`) and filled with `ddwaf_object_insert` / `ddwaf_object_insert_key*`.
+- Use the new getters (`ddwaf_object_get_type`, `ddwaf_object_get_size`, `ddwaf_object_get_string`, `ddwaf_object_get_bool`, etc.) together with `ddwaf_object_at_key` / `ddwaf_object_at_value` for iteration.
+
+## 5. Builder workflow updates
+
+`ddwaf_builder_init` no longer accepts a `ddwaf_config*`. Instantiate it without arguments and pass configuration documents that already carry optional obfuscator settings. Inputs still need to be destroyed with `ddwaf_object_destroy`. The integration test at `tests/integration/interface/builder/test.cpp` reflects the new pattern:
+
+```c
+ddwaf_builder builder = ddwaf_builder_init();
+ddwaf_object config = yaml_to_object<ddwaf_object>(...);
+
+ddwaf_builder_add_or_update_config(builder, "default", sizeof("default") - 1, &config, nullptr);
+ddwaf_object_destroy(&config, alloc);
+
+ddwaf_handle handle = ddwaf_builder_build_instance(builder);
+/* ... */
+ddwaf_builder_destroy(builder);
+```
+
+## 6. Quick reference for renamed helpers
+
+- Initialisation and teardown:
+  - `ddwaf_run` → `ddwaf_context_eval`
+  - `ddwaf_object_free` → `ddwaf_object_destroy`
+  - `ddwaf_context_init(handle)` → `ddwaf_context_init(handle, alloc)`
+- Primitive setters:
+  - `ddwaf_object_invalid/null` → `ddwaf_object_set_invalid/null`
+  - `ddwaf_object_string*` → `ddwaf_object_set_string` / `*_literal` / `*_nocopy`
+  - `ddwaf_object_unsigned/signed/float/bool` → `ddwaf_object_set_unsigned/signed/float/bool`
+- Containers:
+  - `ddwaf_object_array` / `ddwaf_object_map` → `ddwaf_object_set_array` / `ddwaf_object_set_map`
+  - `ddwaf_object_array_add` → `ddwaf_object_insert`
+  - `ddwaf_object_map_add*` → `ddwaf_object_insert_key`, `_insert_literal_key`, `_insert_key_nocopy`
+- Accessors:
+  - `ddwaf_object_type` / `size` / `length` → `ddwaf_object_get_type` / `get_size` / `get_length`
+  - `ddwaf_object_get_key` / `get_index` → `ddwaf_object_at_key` / `ddwaf_object_at_value`
+
+## 7. Reference examples in this repository
+
+- `tests/integration/context/test.cpp` showcases context creation, evaluation, subcontexts and result handling with the new API.
+- `tests/integration/interface/waf/test.cpp` exercises error handling, subcontexts and edge cases around `ddwaf_context_eval`.
+- `tests/integration/interface/allocator/test.cpp` demonstrates the allocator factories and how to integrate a custom allocator.
+- `tests/integration/interface/builder/test.cpp` covers the builder flow without `ddwaf_config`.
+
+## Migration checklist
+
+- [ ] Drop any attempt to configure evaluation limits; they are no longer exposed.
+- [ ] If you rely on custom obfuscator patterns, embed them in the configuration documents you load.
+- [ ] Update every `ddwaf_context_init` call to pass an allocator and replace `ddwaf_run` with `ddwaf_context_eval`.
+- [ ] Swap out deprecated `ddwaf_object_*` constructors for the allocator-aware setters and ensure destruction happens through `ddwaf_object_destroy`.
+- [ ] Review result-handling code for the new getter helpers and the unified request payload.
+- [ ] If you provide custom allocators, migrate the hook to `ddwaf_user_allocator_init` and pair it with `ddwaf_allocator_destroy`.
+- [ ] Drop the `ddwaf_config` argument when using the builder and ensure configurations are destroyed with the correct allocator.

From 6f6579516bca11e85b5bfae990f8e3b230d22a55 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 19 Nov 2025 09:32:01 +0100
Subject: [PATCH 02/32] Add UPGRADING.md for backwards compat

---
 UPGRADING.md | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 UPGRADING.md

diff --git a/UPGRADING.md b/UPGRADING.md
new file mode 100644
index 000000000..56bd7cbd5
--- /dev/null
+++ b/UPGRADING.md
@@ -0,0 +1 @@
+Moved to [docs/upgrading/](docs/upgrading/)

From 890cd5f4002040e861b6406b5f6b495f185cd396 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Mon, 24 Nov 2025 12:45:51 +0000
Subject: [PATCH 03/32] Add more documentation

---
 docs/README.md                                |  4 +-
 docs/configuration/common/conditions.md       | 81 +++++++++++++++++++
 docs/{ => configuration/common}/operators.md  | 21 +++--
 .../common}/transformers.md                   |  0
 docs/rules.md                                 |  4 +-
 5 files changed, 94 insertions(+), 16 deletions(-)
 create mode 100644 docs/configuration/common/conditions.md
 rename docs/{ => configuration/common}/operators.md (83%)
 rename docs/{ => configuration/common}/transformers.md (100%)

diff --git a/docs/README.md b/docs/README.md
index 1c7acbf02..f06d70d1b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,8 +4,8 @@ The documents below describe libddwaf’s public API and internal primitives. Us
 
 - [Overview](overview.md) – Architectural summary and execution pipeline.
 - [Address Reference](addresses.md) – List of supported ASM addresses and their expected value types.
-- [Operator Reference](operators.md) – Scalar and detector operators with parameters and version notes.
-- [Transformer Reference](transformers.md) – Input transformation utilities available to rules.
+- [Operator Reference](configuration/common/operators.md) – Scalar and detector operators with parameters and version notes.
+- [Transformer Reference](configuration/common/transformers.md) – Input transformation utilities available to rules.
 - [Processor Reference](processors.md) – Built-in preprocessors/postprocessors and configuration options.
 - [Rule Definitions](rules.md) – Structure, metadata, and output controls for writing rules.
 - [Exclusion Filters](exclusions.md) – Configure rule and input exclusions in configuration documents.
diff --git a/docs/configuration/common/conditions.md b/docs/configuration/common/conditions.md
new file mode 100644
index 000000000..30b3557a8
--- /dev/null
+++ b/docs/configuration/common/conditions.md
@@ -0,0 +1,81 @@
+# Condition Schema
+
+Conditions are the common building block used by rules, processors, and exclusion filters. Each component embeds a `conditions` array that forms a logical expression evaluated against the current request data. The parser for these expressions lives in `src/configuration/common/expression_parser.cpp` and is shared across configuration types.
+
+## Expression semantics
+
+- The `conditions` array represents a conjunction: entries are evaluated in order until one fails; if all succeed the expression is `true`. An empty array implicitly evaluates to `true`.
+- Results are cached per context. Once a condition has matched a given object, subsequent evaluations in the same request skip the work unless new input appears.
+- All operators documented in the [Operator Reference](operators.md) are valid inside any expression. Processor and exclusion expressions are parsed with the same rules as rule expressions.
+
+## Condition object
+
+Every element in the `conditions` array has the same top-level shape:
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `operator` | string | yes | Name of the matcher to run (for example `match_regex`, `phrase_match`, `exists`). Operators that carry a schema version use the `name@vN` suffix (for example `ssrf_detector@v1`). |
+| `parameters` | object | yes | Operator-specific parameters plus the argument mappings (see below). |
+
+The exact keys inside `parameters` depend on the operator. Scalar matchers such as `equals`, `match_regex`, `ip_match`, `phrase_match`, `greater_than`, and `lower_than` require a `value` and `type` (or a `regex`/`list`/`data` depending on the matcher) in addition to their inputs. Complex detectors such as `ssrf_detector` also accept `options` and `policy` blocks. Refer to the operator documentation for the full list of supported keys per matcher.
+
+## Mapping inputs to a condition
+
+Most operators accept an `inputs` argument under `parameters`. Each entry in `inputs` maps one address from the request (or derived data) into the operator:
+
+| Key | Type | Required | Description |
+| --- | --- | --- | --- |
+| `address` | string | yes | The address to inspect, such as `server.request.query`, `server.request.body`, or `_dd.appsec.fp.http.endpoint`. |
+| `key_path` | array of string/int | no | Optional navigation into nested maps or arrays. Strings address map keys; integers address array indices. Use `"*"` as a wildcard segment. |
+| `transformers` | array of strings | no | Overrides the transformer chain for this input. At most 10 entries. When omitted, the expression-level transformers (rule-level) apply. |
+
+Inputs are ordered; non-variadic operators accept exactly one entry while variadic ones consume every entry in the list. The accepted argument names (`inputs`, `value`, etc.) come from the operator signature; for example the `exists` operator only accepts `inputs` while structured detectors may name their arguments differently.
+
+### Data source and transformers
+
+- By default expressions read **values** from each address. If a rule-level `transformers` array includes the sentinel `keys_only`, the condition walks map keys instead. The sentinel `values_only` restores the default. These sentinels are ignored for processors and exclusions because they do not carry a rule-level transformer list.
+- Per-input `transformers` replace the rule-level chain for that target and always operate on values. When present, the data source for that input is forced back to values even if `keys_only` was declared at the rule level.
+- Transformer identifiers are listed in the [Transformer Reference](transformers.md).
+
+## Putting it together
+
+Rule, processor, and exclusion configurations all embed conditions using the schema above. Examples:
+
+- **Rule condition** that matches a numeric status code:  
+  ```json
+  {
+    "operator": "equals",
+    "parameters": {
+      "inputs": [{ "address": "server.response.status" }],
+      "type": "unsigned",
+      "value": 403
+    }
+  }
+  ```
+- **Processor gate** controlled by a context flag:  
+  ```json
+  {
+    "operator": "equals",
+    "parameters": {
+      "inputs": [
+        { "address": "waf.context.processor", "key_path": ["fingerprint"] }
+      ],
+      "type": "boolean",
+      "value": true
+    }
+  }
+  ```
+- **Exclusion filter** applied when the request path contains `/health`:  
+  ```json
+  {
+    "operator": "match_regex",
+    "parameters": {
+      "inputs": [
+        { "address": "server.request.uri.raw", "transformers": ["lowercase"] }
+      ],
+      "regex": "/health(/|$)"
+    }
+  }
+  ```
+
+Whichever component owns the `conditions` array determines how the expression is used—rules treat it as the match logic for detection, processors as an execution gate, and exclusions as the predicate for muting or pruning. The underlying schema and evaluation semantics remain the same.
diff --git a/docs/operators.md b/docs/configuration/common/operators.md
similarity index 83%
rename from docs/operators.md
rename to docs/configuration/common/operators.md
index 96f9b27df..2b5332793 100644
--- a/docs/operators.md
+++ b/docs/configuration/common/operators.md
@@ -1,8 +1,6 @@
 # Operator Reference
 
-libddwaf supports a mixture of low-level “scalar” match operators and higher-level detectors that encapsulate complex heuristics. This document enumerates every operator wired through `src/matcher` and `src/condition`, together with the arguments they expect in security rule definitions. Configuration examples follow the format consumed by the expression parser in `src/configuration/common/expression_parser.cpp`.
-
-Unless stated otherwise, operators consume data from the `inputs` argument (the list of addresses on which the condition runs). Each address can declare its own transformer chain; negated scalar operators accept at most one address.
+Libddwaf supports a mixture of low-level “scalar” match operators and higher-level detectors that encapsulate complex heuristics. This document enumerates each of the available operators, together with the arguments they expect.
 
 ---
 
@@ -13,11 +11,10 @@ These operators compare request data against literal values, numerical threshold
 ### `equals`
 - **Purpose:** Compare a value to a literal.
 - **Arguments:**  
-  - `inputs` (variadic list of addresses).  
   - `type`: `"string"`, `"boolean"`, `"unsigned"`, `"signed"`, or `"float"`.  
   - `value`: literal to compare against.  
   - `delta` (optional, floats only): tolerance when comparing floating point numbers.
-- **Notes:** Supports negation (`!equals`) which must be scoped to a single address.
+- **Notes:** Supports negation (`!equals`) which must be scoped to a single address and / or key path.
 
 ### `exact_match`
 - **Purpose:** Match against a list of exact strings.
@@ -32,7 +29,7 @@ These operators compare request data against literal values, numerical threshold
   - `inputs`.  
   - `type`: `"unsigned"`, `"signed"`, or `"float"`.  
   - `value`: comparison threshold.
-- **Notes:** Negated form `!greater_than` inverts the comparison.
+- **Notes:** No direct `!greater_than` variant exists; use `lower_than`/`equals` to express the complementary logic.
 
 ### `lower_than`
 - **Purpose:** Numeric less-than comparison.
@@ -40,7 +37,7 @@ These operators compare request data against literal values, numerical threshold
   - `inputs`.  
   - `type`: `"unsigned"`, `"signed"`, or `"float"`.  
   - `value`: comparison threshold.
-- **Notes:** Negated form `!lower_than` inverts the comparison.
+- **Notes:** No direct `!lower_than` matcher exists; use `greater_than`/`equals` to cover the opposite condition.
 
 ### `match_regex`
 - **Purpose:** Evaluate a RE2 regular expression.
@@ -80,22 +77,22 @@ These operators compare request data against literal values, numerical threshold
 ### `is_xss`
 - **Purpose:** Detect cross-site scripting payloads using libinjection.
 - **Arguments:** `inputs`.
-- **Notes:** Negated form `!is_xss` is supported.
+- **Notes:** Only the positive matcher is available; there is no `!is_xss`.
 
 ### `is_sqli`
 - **Purpose:** Detect SQL injection payloads using libinjection.
 - **Arguments:** `inputs`.
-- **Notes:** Negated form `!is_sqli` is supported.
+- **Notes:** Only the positive matcher is available; there is no `!is_sqli`.
 
 ### `hidden_ascii_match`
 - **Purpose:** Flag strings containing hidden or non-printable ASCII characters.
 - **Arguments:** `inputs`.
-- **Notes:** Negated form `!hidden_ascii_match` is supported.
+- **Notes:** Only the positive matcher is available; there is no `!hidden_ascii_match`.
 
 ### `exists` / `!exists`
 - **Purpose:** Assert the presence (`exists`) or absence (`!exists`) of addresses.
 - **Arguments:**  
-  - `exists`: `inputs` (variadic). Returns `true` as soon as any address resolves. Key paths are ignored.  
+  - `exists`: `inputs` (variadic). Returns `true` as soon as any address resolves; key paths are traversed so nested lookups honour the provided selectors.  
   - `!exists`: `inputs` (exactly one). Returns `true` only when the address cannot be resolved.
 - **Notes:** Implemented as scalar conditions; the negated form must target a single address.
 
@@ -155,6 +152,6 @@ Detector operators combine multiple signals and heuristics. They are versioned:
 
 ## Operator negation
 
-Scalar match operators (the ones backed by `src/matcher`) automatically expose a negated variant prefixed with `!`—for example, `!match_regex` or `!ip_match`. Negated operators accept exactly one address and invert the underlying predicate. Detector operators (`*_detector`) do **not** provide negated forms; wrap them in logical NOT expressions if alternative behaviour is needed.
+Only the scalar match operators `equals`, `exact_match`, `match_regex`, `match_regex_with_checksum`, `phrase_match`, and `ip_match` expose a dedicated negated variant prefixed with `!`—for example, `!match_regex` or `!ip_match`. Those negated operators accept exactly one address and invert the underlying predicate. Detector operators (`*_detector`) and the remaining scalar matchers do **not** provide negated forms; use complementary positive operators if alternative behaviour is needed.
 
 When combining operators, remember that each address may declare transformers and that the global condition applies them in the order specified in the rule definition.
diff --git a/docs/transformers.md b/docs/configuration/common/transformers.md
similarity index 100%
rename from docs/transformers.md
rename to docs/configuration/common/transformers.md
diff --git a/docs/rules.md b/docs/rules.md
index 775d35529..6cb394f2c 100644
--- a/docs/rules.md
+++ b/docs/rules.md
@@ -13,7 +13,7 @@ actions that should follow.
 | `id` | string | yes | Stable identifier. Must be unique across all rules (base and custom). |
 | `name` | string | yes | Human-readable label shown in diagnostics. |
 | `tags` | object | yes | Metadata used for grouping, routing, and overrides. Must include a `type` key (for example `"type": "lfi"`). Optionally include `category`, `module`, or any other taxonomy keys you rely on. |
-| `conditions` | array | yes | List of condition objects describing the match logic. See the [Operator Reference](operators.md) for supported operators and parameter schemas. |
+| `conditions` | array | yes | List of condition objects describing the match logic. See the [Operator Reference](configuration/common/operators.md) for supported operators and parameter schemas. |
 
 ## Optional common fields
 
@@ -21,7 +21,7 @@ actions that should follow.
 | --- | --- | --- | --- |
 | `enabled` | boolean | `true` | Disable a rule without removing it from the document. |
 | `min_version`, `max_version` | semantic version | unrestricted | Restrict the rule to specific libddwaf versions. |
-| `transformers` | array | empty | Sequence of transformer identifiers applied to all inputs referenced by the rule before conditions run. See the [Transformer Reference](transformers.md). At most 10 entries are accepted. |
+| `transformers` | array | empty | Sequence of transformer identifiers applied to all inputs referenced by the rule before conditions run. See the [Transformer Reference](configuration/common/transformers.md). At most 10 entries are accepted. |
 | `on_match` | array of strings | empty | Ordered list of action identifiers to emit when the rule matches. Actions are resolved at runtime through the ruleset's action catalogue. |
 | `output` | object | implicit event+keep | Fine-tune the generated event and attributes. Details below. |
 

From ba9923b1152f4b53f434bc922c1f936feae0b7db Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Mon, 24 Nov 2025 14:01:38 +0000
Subject: [PATCH 04/32] Add more documentation

---
 docs/README.md                   |   7 +-
 docs/configuration/actions.md    |  32 +++++++
 docs/configuration/exclusions.md |  86 +++++++++++++++++++
 docs/configuration/processors.md |  92 ++++++++++++++++++++
 docs/configuration/rules.md      | 142 +++++++++++++++++++++++++++++++
 docs/exclusions.md               | 120 --------------------------
 docs/overview.md                 |   3 +-
 docs/processors.md               | 107 -----------------------
 docs/rules.md                    | 125 ---------------------------
 9 files changed, 358 insertions(+), 356 deletions(-)
 create mode 100644 docs/configuration/actions.md
 create mode 100644 docs/configuration/exclusions.md
 create mode 100644 docs/configuration/processors.md
 create mode 100644 docs/configuration/rules.md
 delete mode 100644 docs/exclusions.md
 delete mode 100644 docs/processors.md
 delete mode 100644 docs/rules.md

diff --git a/docs/README.md b/docs/README.md
index f06d70d1b..ba89bdce2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -6,9 +6,10 @@ The documents below describe libddwaf’s public API and internal primitives. Us
 - [Address Reference](addresses.md) – List of supported ASM addresses and their expected value types.
 - [Operator Reference](configuration/common/operators.md) – Scalar and detector operators with parameters and version notes.
 - [Transformer Reference](configuration/common/transformers.md) – Input transformation utilities available to rules.
-- [Processor Reference](processors.md) – Built-in preprocessors/postprocessors and configuration options.
-- [Rule Definitions](rules.md) – Structure, metadata, and output controls for writing rules.
-- [Exclusion Filters](exclusions.md) – Configure rule and input exclusions in configuration documents.
+- [Processor Reference](configuration/processors.md) – Built-in preprocessors/postprocessors and configuration options.
+- [Actions](configuration/actions.md) – Top-level action catalogue referenced by rules.
+- [Rules Configuration](configuration/rules.md) – Schema, metadata, and placement of `rules` and `custom_rules` entries in configuration payloads.
+- [Exclusion Filters](configuration/exclusions.md) – Configure rule and input exclusions in configuration documents.
 - [C API Reference](c-api/api.md) – Comprehensive description of all exported functions, structs, and macros.
 
 For migration guidance, start with [Upgrading to 2.0](upgrading/UPGRADING-v2.0.md) or consult the versioned guides in [`docs/upgrading/`](upgrading/).
diff --git a/docs/configuration/actions.md b/docs/configuration/actions.md
new file mode 100644
index 000000000..f499760a2
--- /dev/null
+++ b/docs/configuration/actions.md
@@ -0,0 +1,32 @@
+# Actions Catalogue
+
+Actions describe what the host should do when a rule matches. They are defined in the optional top-level `actions` array of a configuration document and are referenced by rules via their `on_match` field.
+
+## Action schema
+
+Each entry in `actions` uses this shape:
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `id` | string | yes | Identifier referenced by `on_match`. Must be unique across the document. |
+| `type` | string | yes | One of `block_request`, `redirect_request`, `monitor`, `generate_stack`, `generate_schema`, or a custom type understood by the host application. |
+| `parameters` | object | yes | Free-form parameters passed through to the action mapper. |
+
+## Built-in defaults
+
+libddwaf always exposes a baseline catalogue, even if the `actions` array is omitted:
+
+- `block` (alias of `block_request`) with defaults: `status_code=403`, `grpc_status_code=10`, `type=auto`.
+- `monitor` (no parameters).
+- `stack_trace` (`generate_stack`).
+- `extract_schema` (`generate_schema`).
+
+You can override these by redefining their IDs in `actions`, or add new entries for custom behaviour.
+
+## Validation rules
+
+- `block_request` accepts `status_code`, `grpc_status_code`, and `type` (transport hint). Missing fields are filled from the default block action.
+- `redirect_request` requires a non-empty `location` URL and an HTTP status code in `{301,302,303,307}` (default 303). Invalid redirects are downgraded to `block_request`.
+- Reserved parameters `security_response_id` and `stack_id` are stripped for safety.
+
+All other types are passed through as-is; the host integration is responsible for interpreting custom action types.
diff --git a/docs/configuration/exclusions.md b/docs/configuration/exclusions.md
new file mode 100644
index 000000000..1982c49bd
--- /dev/null
+++ b/docs/configuration/exclusions.md
@@ -0,0 +1,86 @@
+# Exclusion Filters
+
+Exclusions refine how rules respond to specific traffic without editing the rules themselves. Two flavours exist:
+
+- **Rule exclusions** change the verdict of matching rules.
+- **Input exclusions** remove request fields from rule evaluation while leaving the rule active.
+
+Both live in the `exclusions` array of a configuration document and share the same top-level shape.
+
+## Shared schema
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `id` | string | yes | Unique identifier for diagnostics and deduplication. |
+| `min_version`, `max_version` | semantic version | no | Restrict the exclusion to specific libddwaf versions. |
+| `conditions` | array | no | Expression evaluated against request data. See the [Condition schema](common/conditions.md). Omit for unconditional exclusions. |
+| `rules_target` | array | no | List of rules to affect. Entries may include `rule_id`/`id` (exact match) or `tags` for tag-based selection. Omit to target all rules. |
+
+At least one of `conditions`, `rules_target`, or `inputs` (for input exclusions) must be provided; otherwise the entry is rejected.
+
+## Rule exclusions
+
+Additional field:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `on_match` | string | no | Outcome when the exclusion triggers: `bypass` (default, skip rule entirely), `monitor` (force monitor verdict), or a custom action ID from the [action catalogue](actions.md). |
+
+Use rule exclusions to silence noisy rules, force monitoring, or reroute matches to a custom action.
+
+### Example
+
+```json
+{
+  "id": "skip-log4shell-on-backend",
+  "conditions": [
+    {
+      "operator": "match_regex",
+      "parameters": {
+        "inputs": [{ "address": "server.address" }],
+        "regex": "^10\\."
+      }
+    }
+  ],
+  "rules_target": [{ "rule_id": "log4shell" }],
+  "on_match": "bypass"
+}
+```
+
+## Input exclusions
+
+Additional field:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `inputs` | array | yes | Addresses (and optional key paths) to remove from rule evaluation when the exclusion matches. |
+
+Each entry inside `inputs` accepts:
+
+| Key | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `address` | string | yes | Address to prune (for example `server.request.query`). |
+| `key_path` | array of strings | no | Navigate into nested structures; use `"*"` as a wildcard. Omit to remove the entire address. Missing segments are treated as wildcards. |
+
+Input exclusions let rules keep running but with sensitive or noisy fields removed.
+
+### Example
+
+```json
+{
+  "id": "ignore-debug-parameter",
+  "inputs": [
+    { "address": "server.request.query", "key_path": ["debug"] }
+  ],
+  "rules_target": [
+    { "tags": { "type": "security_scanner" } }
+  ]
+}
+```
+
+## Evaluation notes
+
+- Unique `id` values are enforced. Entries with incompatible version bounds are skipped.
+- Exclusions run before rule evaluation. The first match is memoised for the rest of the request to keep lookups fast.
+- Rule exclusions decide the final verdict (`bypass`, `monitor`, or custom action). Input exclusions prune data and allow the rule to produce a normal outcome on the reduced input.
+- Combine exclusions with rule `on_match` actions to tune blocking/monitoring decisions without modifying the rule logic.
diff --git a/docs/configuration/processors.md b/docs/configuration/processors.md
new file mode 100644
index 000000000..6953c6008
--- /dev/null
+++ b/docs/configuration/processors.md
@@ -0,0 +1,92 @@
+# Processors
+
+Processors are reusable transformations that derive new addresses from request data. They can run before rule evaluation (preprocessors) or after rule evaluation to enrich result attributes (postprocessors). Each processor lives in the `processors` array of a configuration document.
+
+## Processor schema
+
+Required fields:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | string | Unique identifier for diagnostics and overrides. |
+| `generator` | string | Processor type (for example `uri_parse`, `jwt_decode`, `extract_schema`, fingerprint generators). |
+
+Optional fields:
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `conditions` | array | `[]` | Simplified expression that must evaluate to `true` before the processor runs. See [conditions](common/conditions.md). |
+| `parameters.mappings` | array | `[]` | Input/output bindings; see below. |
+| `parameters.scanners` | array | `[]` | Scanner include/exclude filters (only for `extract_schema`). |
+| `min_version`, `max_version` | semantic version | unrestricted | Restrict the processor to specific libddwaf versions. |
+| `evaluate` | boolean | `true` | When `true`, output is inserted into the object store (preprocessor). |
+| `output` | boolean | `false` | When `true`, output is exported via the attribute collector (postprocessor). |
+
+At least one of `evaluate` or `output` must be `true`; otherwise the processor is rejected.
+
+### Mappings
+
+Each entry in `parameters.mappings` wires processor inputs to addresses and declares an output:
+
+| Key | Type | Notes |
+| --- | --- | --- |
+| `<param>` | array | Required inputs keyed by the generator’s `param_names` (for example `inputs`, `headers`, `uri_raw`, `output`). Each array entry contains an `address` and optional `key_path`. |
+| `output` | string | Address where the generated object will be stored/emitted. |
+
+Inputs can provide `key_path` to navigate nested structures and may include only one address per parameter (current parser limitation).
+
+### Lifecycle and caching
+
+- **Preprocessors** (`evaluate: true`) run before exclusions and rules. Derived addresses are immediately available to conditions. Results are cloned into the caller allocator.
+- **Postprocessors** (`output: true`) run after rule evaluation and append attributes to the result payload without affecting rule logic.
+- Expressions, resolved inputs, and generated outputs are cached per context to avoid recomputation across evaluations. Optional parameters trigger re-evaluation only when new inputs appear.
+- Processors honor the evaluation deadline and throw on timeout.
+
+## Supported generators (summary)
+
+- `extract_schema`: Walks complex objects to build `{address}.schema` summaries; can use scanners; often configured as both pre- and postprocessor.
+- `jwt_decode`: Decodes JWT header/payload; commonly populates `server.request.jwt`.
+- `uri_parse`: Breaks a URI into structured components and query map.
+- Fingerprints: `http_endpoint_fingerprint`, `http_header_fingerprint`, `http_network_fingerprint`, `session_fingerprint`; emit deterministic fingerprint fragments under `_dd.appsec.fp.*`.
+
+Refer to integration tests under `tests/integration/processors` for concrete payloads and expected outputs.
+
+## Example configuration
+
+```json
+{
+  "processors": [
+    {
+      "id": "fingerprint-http-endpoint",
+      "generator": "http_endpoint_fingerprint",
+      "conditions": [
+        {
+          "operator": "equals",
+          "parameters": {
+            "inputs": [
+              { "address": "waf.context.processor", "key_path": ["fingerprint"] }
+            ],
+            "type": "boolean",
+            "value": true
+          }
+        }
+      ],
+      "parameters": {
+        "mappings": [
+          {
+            "method": [{ "address": "server.request.method" }],
+            "uri_raw": [{ "address": "server.request.uri.raw" }],
+            "query": [{ "address": "server.request.query" }],
+            "body": [{ "address": "server.request.body" }],
+            "output": "_dd.appsec.fp.http.endpoint"
+          }
+        ]
+      },
+      "evaluate": false,
+      "output": true
+    }
+  ]
+}
+```
+
+This example gates a postprocessor on a context flag, generates a deterministic endpoint fingerprint, and exports it as an attribute without affecting rule evaluation.
diff --git a/docs/configuration/rules.md b/docs/configuration/rules.md
new file mode 100644
index 000000000..0cc0edd69
--- /dev/null
+++ b/docs/configuration/rules.md
@@ -0,0 +1,142 @@
+# Rules and Custom Rules
+
+Configuration documents declare detections under two top-level arrays:
+
+- `rules`: Datadog-supplied content shipped with the ruleset.
+- `custom_rules`: Tenant- or agent-supplied additions.
+
+Both arrays share the same schema. Entries are merged by ID; IDs must be unique across both arrays or the duplicate is rejected.
+Rule actions referenced via `on_match` are resolved against the document’s action catalogue; see [Actions](actions.md).
+
+## Rule schema
+
+Required fields:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | string | Stable identifier. Must not collide with any other rule in the document set. |
+| `name` | string | Human-readable label for diagnostics. |
+| `tags` | object | Metadata emitted in events and used for grouping/overrides. Must include a `type` key; may include `module`, `category`, or any custom taxonomy. |
+| `conditions` | array | Expression evaluated against request data. See the [Condition schema](common/conditions.md). |
+
+Optional fields:
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `enabled` | boolean | `true` | Disable the rule without removing it. |
+| `min_version`, `max_version` | semantic version | unrestricted | Load the rule only when the running libddwaf version falls within the range. |
+| `transformers` | array | `[]` | Up to 10 identifiers applied to every input in the rule. See the [Transformer Reference](common/transformers.md). |
+| `on_match` | array of strings | `[]` | Ordered list of action IDs to emit when the rule matches. See [Actions](actions.md) for the catalogue schema. |
+| `output` | object | `{ event: true, keep: true, attributes: {} }` | Shape the emitted event; see below. |
+
+### Tags and modules
+
+- `tags.type` is required and typically mirrors the threat category (for example `sql_injection`, `lfi`, or `grpc_request_blocking`).
+- `tags.module` is optional. Recognised values include `network-acl`, `authentication-acl`, `custom-acl`, `configuration`, `business-logic`, `rasp`, and `waf` (default). Modules control execution order and precedence (see `docs/overview.md`).
+- Additional tags are free-form and surface in events; they can be used by overrides and exclusions for selection.
+
+### Output object
+
+The `output` object controls how matches surface:
+
+- `event` (bool): when `false`, no event is produced.
+- `keep` (bool): when `false`, the match may be dropped during sampling.
+- `attributes` (object): map of extra fields to include in the result. Each value is either a static scalar (`value`) or a reference to request data via `address` and optional `key_path`.
+
+Attribute entries support:
+
+```json
+{
+  "attributes": {
+    "static-example": { "value": "constant value" },
+    "copied-field": {
+      "address": "server.request.query",
+      "key_path": ["user_id"]
+    }
+  }
+}
+```
+
+- `value` accepts strings, integers, floats, and booleans.
+- Referencing request data requires an `address` and an optional `key_path` (strings for map keys, integers for array indices). Omit `key_path` to copy the entire address.
+
+Rules must generate at least one event or attribute. A rule with `output.event = false` and an empty `attributes` object is rejected during parsing.
+
+Example:
+
+```json
+{
+  "output": {
+    "event": true,
+    "keep": true,
+    "attributes": {
+      "user-id": { "address": "usr.id" },
+      "static-tag": { "value": "auth" }
+    }
+  }
+}
+```
+
+### Conditions and operators
+
+Conditions use the shared expression schema documented in [conditions.md](common/conditions.md) and can reference any operator from the [Operator Reference](common/operators.md). Rule-level transformers apply to every input unless an input overrides them with its own `transformers` list.
+
+### Evaluation notes
+
+- Conditions operate on the request `values` data source by default and contribute matches to the rule event payload.
+- Rule-level transformers run before the operator chain and apply to every input reference unless overridden at the input level.
+- `on_match` actions fire in the order provided. Combine them with [exclusion filters](exclusions.md) to adjust the eventual verdict (`monitor`, `block`, or custom actions).
+- Disabled rules, rules gated by incompatible versions, or rules filtered out by exclusions are skipped without evaluating their conditions.
+
+## Example configuration
+
+```json
+{
+  "version": "2.2",
+  "actions": [
+    { "id": "redirect-to-login", "type": "redirect_request", "parameters": { "location": "/login", "status_code": 303 } }
+  ],
+  "rules": [
+    {
+      "id": "ddos-rate-limit",
+      "name": "Generic request flood",
+      "tags": { "type": "configuration", "module": "waf" },
+      "transformers": ["remove_nulls"],
+      "conditions": [
+        {
+          "operator": "greater_than",
+          "parameters": {
+            "inputs": [{ "address": "server.request.rate" }],
+            "type": "unsigned",
+            "value": 200
+          }
+        }
+      ],
+      "on_match": ["block_request"]
+    }
+  ],
+  "custom_rules": [
+    {
+      "id": "my-app-login-bruteforce",
+      "name": "Login brute force detector",
+      "tags": { "type": "security_scanner", "category": "auth", "module": "waf" },
+      "conditions": [
+        {
+          "operator": "match_regex",
+          "parameters": {
+            "inputs": [{ "address": "server.response.body" }],
+            "regex": "(?i)login failed"
+          }
+        }
+      ],
+      "on_match": ["monitor"],
+      "output": {
+        "event": true,
+        "attributes": { "response_snippet": { "address": "server.response.body" } }
+      }
+    }
+  ]
+}
+```
+
+Both rule collections are parsed with the same validation rules: missing required fields or incompatible versions cause the entry to be skipped with diagnostics; rules that generate neither events nor attributes are rejected. Modules and precedence follow the execution order described in `docs/overview.md` (user-defined rules in `custom_rules` take precedence within modules that favour user content).
diff --git a/docs/exclusions.md b/docs/exclusions.md
deleted file mode 100644
index a27d10f83..000000000
--- a/docs/exclusions.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# Exclusion Filters
-
-Exclusions let you refine how a ruleset responds to specific situations without
-editing the rules themselves. They are defined in the `exclusions` array of a
-configuration payload and come in two flavours:
-
-- **Rule exclusions** change the verdict of matching rules.
-- **Input exclusions** remove particular request fields from consideration while
-  the rule logic still runs.
-
-Both types share a common structure and can be combined in the same document.
-
-## Shared fields
-
-Every exclusion object accepts the following keys:
-
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `id` | string | yes | Unique identifier for diagnostics and deduplication. |
-| `min_version`, `max_version` | semantic version | no | Restrict the exclusion to specific libddwaf versions. |
-| `conditions` | array | no | Expression evaluated against request values. When omitted the exclusion is unconditional. |
-| `rules_target` | array | no | List of rules to affect. Each entry can provide `id`/`rule_id` (exact rule identifier) or a `tags` object to match by tag set. Omit to target every rule. |
-
-An exclusion must provide at least one of `conditions`, `rules_target`, or
-`inputs` (for input exclusions). If all of them are omitted the entry is
-rejected.
-
-## Rule exclusions
-
-A rule exclusion changes how selected rules behave once its conditions match.
-Use the `on_match` field to express the desired outcome:
-
-| Value | Effect |
-| --- | --- |
-| `bypass` (default) | Skip rule evaluation entirely. No event is produced. |
-| `monitor` | Evaluate the rule but force the verdict to monitoring and set the action to the built-in `monitor` action. |
-| `<custom action>` | Run the rule normally and override any produced action with the provided string. |
-
-Rule exclusions ignore the `inputs` field and do not remove data from the
-request. They are best suited for turning off noisy rules, forcing monitoring
-mode for specific traffic, or routing matches to a custom action.
-
-### Example
-
-```json
-{
-  "id": "skip-log4shell-on-backend",
-  "conditions": [
-    { "operator": "match_regex", "parameters": { "inputs": [ { "value": { "address": "server.address" } } ], "regex": "^10\\." } }
-  ],
-  "rules_target": [
-    { "rule_id": "log4shell" }
-  ],
-  "on_match": "bypass"
-}
-```
-
-This exclusion disables the `log4shell` rule whenever the server address starts
-with `10.`.
-
-## Input exclusions
-
-Input exclusions keep the rule active while hiding specific request fields. Use
-them when a rule should ignore known benign parameters or payload sections.
-
-Additional fields:
-
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `inputs` | array | yes | List of addresses and optional key paths pointing to values that should be removed from rule evaluation. |
-
-Each entry inside `inputs` must contain:
-
-- `address` (string, required): data collection to inspect. Examples include
-  `server.request.query`, `server.request.body`, or any address recognised by
-  the ruleset.
-- `key_path` (array of strings, optional): navigates into nested structures.
-  Leave empty to ignore the entire address. Use `"*"` to match any key at that
-  depth. Omitted keys (such as array indices) are treated as wildcards.
-
-When the optional `conditions` array evaluates to `true`, all matching values
-described by `inputs` are removed for the targeted rules. Other rules continue
-to see the original data.
-
-### Example
-
-```json
-{
-  "id": "ignore-debug-parameter",
-  "inputs": [
-    {
-      "address": "server.request.query",
-      "key_path": ["debug"]
-    }
-  ],
-  "rules_target": [
-    { "tags": { "type": "security_scanner" } }
-  ]
-}
-```
-
-Here, any rule tagged with `type=security_scanner` ignores the `debug` query
-parameter. The exclusion applies unconditionally because no `conditions` field
-is provided.
-
-## When exclusions are evaluated
-
-- Configuration loading enforces unique `id` values and drops exclusions whose
-  version constraints do not match the running library.
-- During request processing libddwaf evaluates exclusion conditions before each
-  rule. The first successful match is memoised for the rest of the request,
-  keeping filters fast even when multiple rules reference them.
-- Rule exclusions determine the final verdict (`bypass`, `monitor`, or custom
-  action). Input exclusions prune fields and let the rule produce a normal
-  result using the reduced data.
-
-Use exclusions sparingly and document their intent. They provide fine-grained
-control over rule behaviour, but overly broad entries can hide important
-signals. Start with specific targets and conditions, monitor the effect, and
-expand only when necessary.
diff --git a/docs/overview.md b/docs/overview.md
index ad83ed1b6..6d16b3f65 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -1,6 +1,7 @@
+
 # Understanding libddwaf
 
-libddwaf is Datadog’s embeddable web application firewall engine. It ingests a declarative security configuration (rules, exclusions, processors, actions) and exposes a compact C API that any tracer or agent can use to evaluate inbound requests. At runtime the library:
+libddwaf is Datadog’s embeddable security engine. It ingests a declarative security configuration (rules, exclusions, processors, actions) and exposes a compact C API that any tracer or agent can use to evaluate inbound requests. At runtime the library:
 
 1. Parses one or more configuration documents into an immutable **WAF handle** (`ddwaf_handle`).
 2. Creates per-request **contexts** (`ddwaf_context`) bound to the handle and a memory allocator.
diff --git a/docs/processors.md b/docs/processors.md
deleted file mode 100644
index 72e114820..000000000
--- a/docs/processors.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# Processor Reference
-
-Processors are reusable building blocks that derive new addresses from existing request data. They can run before rule evaluation to enrich the object store (preprocessors) or after evaluation to attach additional attributes to the result payload (postprocessors). Each processor definition lives in the `processors` section of a configuration document and is parsed by `configuration/processor_parser.cpp`.
-
----
-
-## Lifecycle and execution
-
-- **Expression gate:** every processor carries a simplified expression (`conditions`) evaluated against the current context. If the expression returns `false` the processor is skipped for that evaluation.
-- **Mappings:** for every entry under `parameters.mappings`, the engine resolves the addresses declared in the mapping according to the processor’s `param_names`. Key paths are supported but each parameter currently accepts a single address.
-- **Evaluate flag:** when `evaluate: true`, the generated object is inserted into the context’s object store. Downstream rules can immediately consume the derived address.
-- **Output flag:** when `output: true`, the generated object is added to the attribute collector so that it surfaces in the `attributes` map returned by `ddwaf_context_eval`.
-- **Caching:** `processor_cache` keeps track of outputs that were already produced during the same evaluation (`generated`), optional arguments that have already been resolved (`evaluated`), and processor-specific state (for example fingerprint fragments). This prevents duplicate work when the same context is evaluated repeatedly.
-- **Memory ownership:** preprocessors that feed rule evaluation clone their result into the user-provided allocator before returning it to the caller; otherwise results are stored directly in the default allocator.
-
-A processor configured with `evaluate: true, output: false` behaves like a classic preprocessor. A processor with `evaluate: false, output: true` acts as a pure postprocessor. Many rule packs use `waf.context.processor` to gate expensive postprocessors so that agents can opt-in address by address.
-
----
-
-## Configuration fields
-
-Each entry in the `processors` array supports:
-
-| Field | Description |
-| --- | --- |
-| `id` | Unique identifier for the processor definition. |
-| `generator` | The processor type (see the list below). |
-| `conditions` | Optional simplified expression that must evaluate to `true` before the processor runs. |
-| `parameters.mappings` | Array of mappings. Every mapping defines the required inputs (per `param_names`) and an `output` address. |
-| `parameters.scanners` | Optional include/exclude list of scanners (only used by `extract_schema`). |
-| `min_version` / `max_version` | Optional semantic-version bounds for libddwaf compatibility. |
-| `evaluate` | Boolean, defaults to `true`. Controls whether the output is inserted into the object store. |
-| `output` | Boolean, defaults to `false`. Controls whether the output is exported via the attribute collector. |
-
-If neither `evaluate` nor `output` is set, the processor is rejected during parsing.
-
----
-
-## Scanners
-
-`extract_schema` can depend on scanners (see `src/scanner.hpp`) to annotate or filter parts of the generated schema. Scanners can be referenced by ID or by tags. The builder resolves references with the following precedence:
-
-1. Exclusions by ID (apply to everything).
-2. Inclusions by ID.
-3. Exclusions by tags.
-4. Inclusions by tags.
-
-The resulting set of `scanner*` pointers is passed to the processor instance.
-
----
-
-## Supported generators
-
-### `extract_schema`
-- **Inputs:** `inputs` (variadic). Each mapping typically targets a request container such as `server.request.body`.
-- **Usage:** Commonly configured with `evaluate: true` to materialise `{address}.schema` maps consumed by rules; optional `output: true` exposes the schema in WAF results.
-- **Behaviour:** Walks complex objects up to a bounded depth (`max_container_depth`), summarises value types (null, boolean, integer, real, string), and records array shapes. The result is a compact JSON-like structure (see integration tests for examples). Scanners can tag or prune fields based on custom logic.
-
-### `jwt_decode`
-- **Inputs:** `inputs` (single address), often pointing to `server.request.headers.no_cookies["authorization"]`.
-- **Usage:**  
-  - `evaluate: true, output: false` (preprocessor) populates `server.request.jwt` so rules can inspect JWT header/payload claims.  
-  - `evaluate: false, output: true` (postprocessor) exports the decoded token in results.
-- **Behaviour:** Looks for `"Bearer "` prefixes, splits the token into header/payload/signature segments, base64url-decodes header and payload, and emits a map such as:  
-  `{"header": {...}, "payload": {...}, "signature": {"available": true}}`.
-
-### `uri_parse`
-- **Inputs:** `inputs` (single string address, for example `server.request.uri.raw`).
-- **Usage:** Usually configured as a postprocessor (`evaluate: false, output: true`) to expose structured URI data. With `evaluate: true` it can populate derived addresses for rules.
-- **Behaviour:** Parses the URI into scheme, user info, host, port, path, fragment, and a map of query parameters where repeated keys are promoted to arrays. Outputs a map with keys `scheme`, `userinfo`, `host`, `port`, `path`, `query`, and `fragment`.
-
-### Fingerprint processors
-
-These generators emit deterministic strings (fragments) prefixed with the fingerprint family. The fragments follow the `<prefix>-<normalized components…>` convention.
-
-- **`http_endpoint_fingerprint`**  
-  - **Inputs:** `method`, `uri_raw`, optional `query`, optional `body`.  
-  - **Output address:** `_dd.appsec.fp.http.endpoint`.  
-  - **Behaviour:** Normalises the method, strips queries from the raw URI, hashes selected parameters, and caches fragments per context to avoid recomputation when optional inputs arrive late.
-
-- **`http_header_fingerprint`**  
-  - **Inputs:** `headers` (map).  
-  - **Output address:** `_dd.appsec.fp.http.header`.  
-  - **Behaviour:** Records which well-known headers are present, normalises unknown headers, and includes a lowercase hash of the User-Agent.
-
-- **`http_network_fingerprint`**  
-  - **Inputs:** `headers` (map).  
-  - **Output address:** `_dd.appsec.fp.http.network`.  
-  - **Behaviour:** Tracks which forwarding headers carry client IP information and counts comma-separated IPs in the highest precedence header.
-
-- **`session_fingerprint`**  
-  - **Inputs:** optional `cookies`, optional `session_id`, optional `user_id`.  
-  - **Output address:** `_dd.appsec.fp.session`.  
-  - **Behaviour:** Hashes user/session identifiers and the cookie map to build a session fingerprint. Optional inputs trigger re-evaluation only when new data appears thanks to `processor_cache.evaluated`.
-
-Fingerprints are usually configured as postprocessors (`evaluate: false, output: true`) and gated by the `waf.context.processor["fingerprint"]` address.
-
----
-
-## Practical tips
-
-- **Opt-in toggles:** use `waf.context.processor` flags in rule packs so agents can enable expensive processors selectively.
-- **Key paths:** mappings accept `key_path`, but the current parser only consumes the first address per parameter. If you need multiple inputs, define multiple mappings targeting different outputs.
-- **Preprocessor vs postprocessor:** remember that preprocessors mutate the context store. Postprocessors never affect rule evaluation—only the result payload.
-- **Timeouts:** processors honour the evaluation deadline; long-running logic should handle `ddwaf::timeout_exception`.
-
-Refer to `tests/integration/processors/*` for concrete configuration examples and expected outputs.
diff --git a/docs/rules.md b/docs/rules.md
deleted file mode 100644
index 6cb394f2c..000000000
--- a/docs/rules.md
+++ /dev/null
@@ -1,125 +0,0 @@
-# Rule Definitions
-
-Rules describe the detections performed by libddwaf. They live inside either the
-`rules` array (Datadog-maintained content) or `custom_rules` (user-supplied
-additions) within a configuration document. Each entry declares the conditions
-to inspect in the request, the metadata attached to any matches, and the
-actions that should follow.
-
-## Required structure
-
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `id` | string | yes | Stable identifier. Must be unique across all rules (base and custom). |
-| `name` | string | yes | Human-readable label shown in diagnostics. |
-| `tags` | object | yes | Metadata used for grouping, routing, and overrides. Must include a `type` key (for example `"type": "lfi"`). Optionally include `category`, `module`, or any other taxonomy keys you rely on. |
-| `conditions` | array | yes | List of condition objects describing the match logic. See the [Operator Reference](configuration/common/operators.md) for supported operators and parameter schemas. |
-
-## Optional common fields
-
-| Field | Type | Default | Notes |
-| --- | --- | --- | --- |
-| `enabled` | boolean | `true` | Disable a rule without removing it from the document. |
-| `min_version`, `max_version` | semantic version | unrestricted | Restrict the rule to specific libddwaf versions. |
-| `transformers` | array | empty | Sequence of transformer identifiers applied to all inputs referenced by the rule before conditions run. See the [Transformer Reference](configuration/common/transformers.md). At most 10 entries are accepted. |
-| `on_match` | array of strings | empty | Ordered list of action identifiers to emit when the rule matches. Actions are resolved at runtime through the ruleset's action catalogue. |
-| `output` | object | implicit event+keep | Fine-tune the generated event and attributes. Details below. |
-
-### Tags and modules
-
-- `tags.type` is required and typically mirrors the threat category (for example
-  `sql_injection`, `lfi`, or `grpc_request_blocking`).
-- `tags.module` is optional. When present it controls rule grouping inside the
-  engine. Recognised values include `network-acl`, `authentication-acl`,
-  `custom-acl`, `configuration`, `business-logic`, `rasp`, and `waf` (default).
-- Additional tags are free-form and can be used to express application, service,
-  or platform metadata. They are emitted in rule events and are also available
-  to rule overrides or filters via tag-based selectors.
-
-## Output controls
-
-The `output` object lets you shape the payload returned when a rule matches:
-
-| Key | Type | Default | Description |
-| --- | --- | --- | --- |
-| `event` | boolean | `true` | When `false`, the rule does not generate an event. Combine with attributes to create silent annotation rules. |
-| `keep` | boolean | `true` | When `false`, the rule outcome may be dropped during sampling. Leave enabled when the match should always be preserved. |
-| `attributes` | object | `{}` | Map of additional fields attached to the rule result. Each entry accepts either a static `value` or a reference to request data via `address`/`key_path`. |
-
-Attribute entries support two shapes:
-
-```json
-{
-  "attributes": {
-    "static-example": { "value": "constant value" },
-    "copied-field": {
-      "address": "server.request.query",
-      "key_path": ["user_id"]
-    }
-  }
-}
-```
-
-- `value` accepts strings, integers, floats, and booleans.
-- Referencing request data requires an `address` and an optional `key_path`.
-  Each element in `key_path` is either a string (map key) or an integer (array
-  index). Omit `key_path` to copy the entire address.
-
-Rules must generate at least one event or attribute. A rule with
-`output.event = false` and an empty `attributes` object is rejected during
-parsing.
-
-## Rule evaluation overview
-
-- Conditions operate on the request `values` data source. Each condition
-  contributes matches that are collected in the rule's event payload.
-- Transformers listed at the rule level run before the operator chain and apply
-  to every input reference in the rule.
-- `on_match` actions fire in the order provided. Combine them with
-  [exclusion filters](exclusions.md) to tune the eventual verdict
-  (`monitor`, `block`, or custom actions).
-- Disabled rules, rules gated by incompatible versions, or rules filtered out by
-  exclusions are skipped without evaluating their conditions.
-
-## Example rule
-
-```json
-{
-  "id": "my-app-login-bruteforce",
-  "name": "Login brute force detector",
-  "tags": {
-    "type": "security_scanner",
-    "category": "misc_checks",
-    "module": "waf",
-    "service": "frontend"
-  },
-  "transformers": ["remove_nulls"],
-  "conditions": [
-    {
-      "operator": "match_regex",
-      "parameters": {
-        "regex": "(?i)login failed",
-        "inputs": [
-          { "address": "server.response.body" }
-        ]
-      }
-    }
-  ],
-  "on_match": ["block_request"],
-  "output": {
-    "event": true,
-    "keep": true,
-    "attributes": {
-      "response_body": {
-        "address": "server.response.body",
-        "key_path": []
-      }
-    }
-  }
-}
-```
-
-This example inspects the response body for an authentication failure pattern,
-ensures the match is always kept, and attaches the full response body to the
-generated event while instructing the engine to trigger the `block_request`
-action.

From 6a34099b11ce8a265c9f6ae6bcb54351a57cf532 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Mon, 24 Nov 2025 15:20:47 +0000
Subject: [PATCH 05/32] Add more documentation

---
 docs/README.md                                | 13 ++--
 docs/actions.md                               | 59 ++++++++++++++++++
 docs/{configuration/common => }/conditions.md |  0
 docs/configuration/actions.md                 | 32 ----------
 docs/evaluation.md                            | 61 +++++++++++++++++++
 docs/{configuration => }/exclusions.md        |  4 +-
 docs/{configuration/common => }/operators.md  |  0
 docs/overview.md                              |  2 +-
 docs/{configuration => }/processors.md        |  4 +-
 docs/{configuration => }/rules.md             |  6 +-
 .../common => }/transformers.md               |  0
 docs/upgrading/UPGRADING-v2.0.md              |  8 +--
 12 files changed, 139 insertions(+), 50 deletions(-)
 create mode 100644 docs/actions.md
 rename docs/{configuration/common => }/conditions.md (100%)
 delete mode 100644 docs/configuration/actions.md
 create mode 100644 docs/evaluation.md
 rename docs/{configuration => }/exclusions.md (94%)
 rename docs/{configuration/common => }/operators.md (100%)
 rename docs/{configuration => }/processors.md (98%)
 rename docs/{configuration => }/rules.md (93%)
 rename docs/{configuration/common => }/transformers.md (100%)

diff --git a/docs/README.md b/docs/README.md
index ba89bdce2..07505b8c2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,12 +4,13 @@ The documents below describe libddwaf’s public API and internal primitives. Us
 
 - [Overview](overview.md) – Architectural summary and execution pipeline.
 - [Address Reference](addresses.md) – List of supported ASM addresses and their expected value types.
-- [Operator Reference](configuration/common/operators.md) – Scalar and detector operators with parameters and version notes.
-- [Transformer Reference](configuration/common/transformers.md) – Input transformation utilities available to rules.
-- [Processor Reference](configuration/processors.md) – Built-in preprocessors/postprocessors and configuration options.
-- [Actions](configuration/actions.md) – Top-level action catalogue referenced by rules.
-- [Rules Configuration](configuration/rules.md) – Schema, metadata, and placement of `rules` and `custom_rules` entries in configuration payloads.
-- [Exclusion Filters](configuration/exclusions.md) – Configure rule and input exclusions in configuration documents.
+- [Operator Reference](operators.md) – Scalar and detector operators with parameters and version notes.
+- [Transformer Reference](transformers.md) – Input transformation utilities available to rules.
+- [Processor Reference](processors.md) – Built-in preprocessors/postprocessors and configuration options.
+- [Actions](actions.md) – Top-level action catalogue referenced by rules.
+- [Rules Configuration](rules.md) – Schema, metadata, and placement of `rules` and `custom_rules` entries in configuration payloads.
+- [Exclusion Filters](exclusions.md) – Configure rule and input exclusions in configurations.
+- [Evaluation Flow](evaluation.md) – Runtime ordering of processors, filters, modules, and WAF collections.
 - [C API Reference](c-api/api.md) – Comprehensive description of all exported functions, structs, and macros.
 
 For migration guidance, start with [Upgrading to 2.0](upgrading/UPGRADING-v2.0.md) or consult the versioned guides in [`docs/upgrading/`](upgrading/).
diff --git a/docs/actions.md b/docs/actions.md
new file mode 100644
index 000000000..862212f31
--- /dev/null
+++ b/docs/actions.md
@@ -0,0 +1,59 @@
+# Actions Catalogue
+
+Actions describe what the host should do when a rule matches. They are defined in the optional top-level `actions` array of a configuration and are referenced by rules via their `on_match` field.
+
+## Action schema
+
+Each entry in `actions` uses this shape:
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `id` | string | yes | Identifier referenced by `on_match`. Must be unique across the document. |
+| `type` | string | yes | One of `block_request`, `redirect_request`, `monitor`, `generate_stack`, `generate_schema`, or a custom type understood by the host application. |
+| `parameters` | object | yes | Free-form parameters passed through to the action mapper and on to the host/caller. |
+
+## Built-in defaults
+
+libddwaf always exposes a baseline catalogue, even if the `actions` array is omitted:
+
+- `block` (alias of `block_request`) with defaults: `status_code=403`, `grpc_status_code=10`, `type=auto`.
+- `monitor` (no parameters).
+- `stack_trace` (`generate_stack`).
+- `extract_schema` (`generate_schema`).
+
+You can override these by redefining their IDs in `actions`, or add new entries for custom behaviour.
+
+## Action types
+
+### `block_request`
+
+Signals that the request should be blocked. Parameters:
+
+- `status_code` (optional): HTTP status to emit; any 3-digit code is accepted. Defaults to `403` if missing or invalid.
+- `grpc_status_code` (optional): gRPC status (unsigned) to emit; defaults to `10` if missing or invalid.
+- `type` (optional): transport hint (for example `auto`).
+
+Missing parameters are populated from the built-in `block` defaults. Reserved parameters `security_response_id` and `stack_id` are stripped.
+
+### `redirect_request`
+
+Instructs the caller to respond with an HTTP redirect. Parameters:
+
+- `location` (string, required): absolute or root-anchored URL to redirect to.
+- `status_code` (optional): one of `301`, `302`, `303`, or `307`. Defaults to `303` if absent or invalid.
+
+The parser validates the URL scheme (`http`/`https`) and ensures relative redirects start with `/`. When validation fails, the action is replaced by the default `block_request`. Reserved parameters `security_response_id` and `stack_id` are stripped.
+
+### `monitor`
+
+Instructs the caller to log/monitor without blocking. Parameters: none. Always emits the `monitor` action ID. Reserved parameters are stripped.
+
+### `generate_stack`
+
+Requests a stack trace capture. Parameters:
+
+- `stack_id` (string, optional): identifier for the captured stack. Other parameters are ignored. Reserved parameters are stripped.
+
+### `generate_schema`
+
+Requests schema generation for the current request data. Parameters: none; any provided values are passed through to the host. Reserved parameters are stripped.
diff --git a/docs/configuration/common/conditions.md b/docs/conditions.md
similarity index 100%
rename from docs/configuration/common/conditions.md
rename to docs/conditions.md
diff --git a/docs/configuration/actions.md b/docs/configuration/actions.md
deleted file mode 100644
index f499760a2..000000000
--- a/docs/configuration/actions.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# Actions Catalogue
-
-Actions describe what the host should do when a rule matches. They are defined in the optional top-level `actions` array of a configuration document and are referenced by rules via their `on_match` field.
-
-## Action schema
-
-Each entry in `actions` uses this shape:
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `id` | string | yes | Identifier referenced by `on_match`. Must be unique across the document. |
-| `type` | string | yes | One of `block_request`, `redirect_request`, `monitor`, `generate_stack`, `generate_schema`, or a custom type understood by the host application. |
-| `parameters` | object | yes | Free-form parameters passed through to the action mapper. |
-
-## Built-in defaults
-
-libddwaf always exposes a baseline catalogue, even if the `actions` array is omitted:
-
-- `block` (alias of `block_request`) with defaults: `status_code=403`, `grpc_status_code=10`, `type=auto`.
-- `monitor` (no parameters).
-- `stack_trace` (`generate_stack`).
-- `extract_schema` (`generate_schema`).
-
-You can override these by redefining their IDs in `actions`, or add new entries for custom behaviour.
-
-## Validation rules
-
-- `block_request` accepts `status_code`, `grpc_status_code`, and `type` (transport hint). Missing fields are filled from the default block action.
-- `redirect_request` requires a non-empty `location` URL and an HTTP status code in `{301,302,303,307}` (default 303). Invalid redirects are downgraded to `block_request`.
-- Reserved parameters `security_response_id` and `stack_id` are stripped for safety.
-
-All other types are passed through as-is; the host integration is responsible for interpreting custom action types.
diff --git a/docs/evaluation.md b/docs/evaluation.md
new file mode 100644
index 000000000..014914792
--- /dev/null
+++ b/docs/evaluation.md
@@ -0,0 +1,61 @@
+# Evaluation Flow
+
+How `evaluation_engine` runs processors, exclusions, and rules during `ddwaf_context_eval`, based on `evaluation_engine.cpp`, `module.cpp`, and the module builder.
+
+## Pipeline overview
+
+1. **Skip if no new inputs**: if the `object_store` has no new targets, return immediately.
+2. **Preprocessors**: run in configured order, populating derived addresses. Each processor has a per-instance cache keyed by its pointer.
+3. **Filters**: evaluate rule filters then input filters. Matches populate an `exclusion_policy` (bypass/monitor/custom action, plus input pruning) used by rules.
+4. **Rules**: walk modules in fixed order (below). Blocking verdicts short-circuit the rest of the module set; monitor verdicts allow continued evaluation.
+5. **Postprocessors**: always run after rules; they may add attributes but never affect matching.
+6. **Serialize**: gather events, actions, attributes, and obfuscation into the result. If any rule fired, the engine injects `waf.context.event` so postprocessors can gate on it.
+
+Processor, filter, and rule caches persist across evaluations so repeated data does not trigger repeated work.
+
+## Processor execution
+
+- **Preprocessors** (`evaluate: true`) run before filters/rules and write outputs into the object store (cloned into the caller allocator as needed).
+- **Postprocessors** (`output: true`) run after rules and only affect serialized attributes.
+- Processor expressions gate execution; optional inputs trigger re-evaluation only when new data appears. The deadline is honoured; a timeout aborts remaining processors in that phase.
+
+## Filters and exclusions
+
+- **Rule filters** can bypass a rule, force monitor, or override the action to a custom value. Results are cached per filter instance.
+- **Input filters** prune addresses (with optional key paths) for selected rules. Pruned inputs are invisible to matching and transformers.
+- The combined `exclusion_policy` is consulted for every rule before evaluation to apply bypass/monitor/custom verdicts and input pruning.
+
+## Module ordering and deadlines
+
+Modules run in this fixed sequence (`module_category.hpp`). Each module sorts rules by verdict first (`block` before `monitor`) and then by source (Datadog vs. user) according to the policy below. A blocking rule stops the module; a monitor rule records a monitor verdict and lets evaluation continue.
+
+1. **`network-acl`** *(non-expiring)*  
+   - Ordering: Datadog before user.  
+   - Deadline: ignored; always runs to completion.
+2. **`authentication-acl`** *(non-expiring)*  
+   - Ordering: Datadog before user.  
+   - Deadline: ignored; always runs to completion.
+3. **`custom-acl`**  
+   - Ordering: user before Datadog.  
+   - Deadline: enforced.
+4. **`configuration`**  
+   - Ordering: user before Datadog.  
+   - Deadline: enforced.
+5. **`business-logic`**  
+   - Ordering: user before Datadog.  
+   - Deadline: enforced.
+6. **`rasp`**  
+   - Ordering: Datadog before user.  
+   - Deadline: enforced.
+7. **`waf`** *(collection-based)*  
+   - Collections: grouped by `tags.type`, verdict, and source in this order: user `block`, Datadog `block`, user `monitor`, Datadog `monitor`.  
+   - Caching: each collection caches its verdict; collections already satisfied at the same or higher verdict are skipped on later evaluations.  
+   - Execution: within a collection, rules run sequentially until one matches or the deadline expires. A `block` result stops remaining collections and modules; a `monitor` result records the verdict and moves to the next collection to gather more context.  
+   - Deadline: enforced.
+
+## Practical notes
+
+- Only addresses seen as new trigger work; unchanged inputs can skip processors, filters, and rules.
+- Non-expiring modules (`network-acl`, `authentication-acl`) ignore deadlines; all others honour them.
+- Postprocessors still run after a rule-timeout so existing data can surface in attributes.
+- Exclusions apply per rule right before condition evaluation, enabling fine-grained bypass/monitor/action overrides without editing rules.
diff --git a/docs/configuration/exclusions.md b/docs/exclusions.md
similarity index 94%
rename from docs/configuration/exclusions.md
rename to docs/exclusions.md
index 1982c49bd..5a928ed1e 100644
--- a/docs/configuration/exclusions.md
+++ b/docs/exclusions.md
@@ -5,7 +5,7 @@ Exclusions refine how rules respond to specific traffic without editing the rule
 - **Rule exclusions** change the verdict of matching rules.
 - **Input exclusions** remove request fields from rule evaluation while leaving the rule active.
 
-Both live in the `exclusions` array of a configuration document and share the same top-level shape.
+Both live in the `exclusions` array of a configuration and share the same top-level shape.
 
 ## Shared schema
 
@@ -13,7 +13,7 @@ Both live in the `exclusions` array of a configuration document and share the sa
 | --- | --- | --- | --- |
 | `id` | string | yes | Unique identifier for diagnostics and deduplication. |
 | `min_version`, `max_version` | semantic version | no | Restrict the exclusion to specific libddwaf versions. |
-| `conditions` | array | no | Expression evaluated against request data. See the [Condition schema](common/conditions.md). Omit for unconditional exclusions. |
+| `conditions` | array | no | Expression evaluated against request data. See the [Condition schema](conditions.md). Omit for unconditional exclusions. |
 | `rules_target` | array | no | List of rules to affect. Entries may include `rule_id`/`id` (exact match) or `tags` for tag-based selection. Omit to target all rules. |
 
 At least one of `conditions`, `rules_target`, or `inputs` (for input exclusions) must be provided; otherwise the entry is rejected.
diff --git a/docs/configuration/common/operators.md b/docs/operators.md
similarity index 100%
rename from docs/configuration/common/operators.md
rename to docs/operators.md
diff --git a/docs/overview.md b/docs/overview.md
index 6d16b3f65..3197f19fc 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -3,7 +3,7 @@
 
 libddwaf is Datadog’s embeddable security engine. It ingests a declarative security configuration (rules, exclusions, processors, actions) and exposes a compact C API that any tracer or agent can use to evaluate inbound requests. At runtime the library:
 
-1. Parses one or more configuration documents into an immutable **WAF handle** (`ddwaf_handle`).
+1. Parses one or more configurations into an immutable **WAF handle** (`ddwaf_handle`).
 2. Creates per-request **contexts** (`ddwaf_context`) bound to the handle and a memory allocator.
 3. Accepts request metadata as a tree of `ddwaf_object` values keyed by semantic **addresses** such as `server.request.body` or `http.client_ip`.
 4. Produces structured matches, derived attributes, and actions when rules trigger.
diff --git a/docs/configuration/processors.md b/docs/processors.md
similarity index 98%
rename from docs/configuration/processors.md
rename to docs/processors.md
index 6953c6008..29a8466b4 100644
--- a/docs/configuration/processors.md
+++ b/docs/processors.md
@@ -1,6 +1,6 @@
 # Processors
 
-Processors are reusable transformations that derive new addresses from request data. They can run before rule evaluation (preprocessors) or after rule evaluation to enrich result attributes (postprocessors). Each processor lives in the `processors` array of a configuration document.
+Processors are reusable transformations that derive new addresses from request data. They can run before rule evaluation (preprocessors) or after rule evaluation to enrich result attributes (postprocessors). Each processor lives in the `processors` array of a configuration.
 
 ## Processor schema
 
@@ -15,7 +15,7 @@ Optional fields:
 
 | Field | Type | Default | Notes |
 | --- | --- | --- | --- |
-| `conditions` | array | `[]` | Simplified expression that must evaluate to `true` before the processor runs. See [conditions](common/conditions.md). |
+| `conditions` | array | `[]` | Simplified expression that must evaluate to `true` before the processor runs. See [conditions](conditions.md). |
 | `parameters.mappings` | array | `[]` | Input/output bindings; see below. |
 | `parameters.scanners` | array | `[]` | Scanner include/exclude filters (only for `extract_schema`). |
 | `min_version`, `max_version` | semantic version | unrestricted | Restrict the processor to specific libddwaf versions. |
diff --git a/docs/configuration/rules.md b/docs/rules.md
similarity index 93%
rename from docs/configuration/rules.md
rename to docs/rules.md
index 0cc0edd69..3b161e1af 100644
--- a/docs/configuration/rules.md
+++ b/docs/rules.md
@@ -17,7 +17,7 @@ Required fields:
 | `id` | string | Stable identifier. Must not collide with any other rule in the document set. |
 | `name` | string | Human-readable label for diagnostics. |
 | `tags` | object | Metadata emitted in events and used for grouping/overrides. Must include a `type` key; may include `module`, `category`, or any custom taxonomy. |
-| `conditions` | array | Expression evaluated against request data. See the [Condition schema](common/conditions.md). |
+| `conditions` | array | Expression evaluated against request data. See the [Condition schema](conditions.md). |
 
 Optional fields:
 
@@ -25,7 +25,7 @@ Optional fields:
 | --- | --- | --- | --- |
 | `enabled` | boolean | `true` | Disable the rule without removing it. |
 | `min_version`, `max_version` | semantic version | unrestricted | Load the rule only when the running libddwaf version falls within the range. |
-| `transformers` | array | `[]` | Up to 10 identifiers applied to every input in the rule. See the [Transformer Reference](common/transformers.md). |
+| `transformers` | array | `[]` | Up to 10 identifiers applied to every input in the rule. See the [Transformer Reference](transformers.md). |
 | `on_match` | array of strings | `[]` | Ordered list of action IDs to emit when the rule matches. See [Actions](actions.md) for the catalogue schema. |
 | `output` | object | `{ event: true, keep: true, attributes: {} }` | Shape the emitted event; see below. |
 
@@ -79,7 +79,7 @@ Example:
 
 ### Conditions and operators
 
-Conditions use the shared expression schema documented in [conditions.md](common/conditions.md) and can reference any operator from the [Operator Reference](common/operators.md). Rule-level transformers apply to every input unless an input overrides them with its own `transformers` list.
+Conditions use the shared expression schema documented in [conditions.md](conditions.md) and can reference any operator from the [Operator Reference](operators.md). Rule-level transformers apply to every input unless an input overrides them with its own `transformers` list.
 
 ### Evaluation notes
 
diff --git a/docs/configuration/common/transformers.md b/docs/transformers.md
similarity index 100%
rename from docs/configuration/common/transformers.md
rename to docs/transformers.md
diff --git a/docs/upgrading/UPGRADING-v2.0.md b/docs/upgrading/UPGRADING-v2.0.md
index c29fa5bcc..f819c3d09 100644
--- a/docs/upgrading/UPGRADING-v2.0.md
+++ b/docs/upgrading/UPGRADING-v2.0.md
@@ -3,14 +3,14 @@
 This guide helps you migrate call sites of the C API from libddwaf 1.30.x to 2.0.0. It captures the high-impact breaking changes and illustrates them with snippets lifted from the integration tests that ship with 2.0.
 
 ## Migration Overview
-- Evaluation limits, obfuscator regexes and the result free hook inside `ddwaf_config` have been removed. The core now enforces internal limits; only the obfuscator survives and must be supplied inside configuration documents when needed. All memory ownership should switch to the allocator API.
+- Evaluation limits, obfuscator regexes and the result free hook inside `ddwaf_config` have been removed. The core now enforces internal limits; only the obfuscator survives and must be supplied inside configurations when needed. All memory ownership should switch to the allocator API.
 - `ddwaf_run` has been replaced by `ddwaf_context_eval`. Persistent and ephemeral maps are merged into a single input object, and every evaluation needs an allocator handle.
 - `ddwaf_object_*` constructors now accept the allocator that owns the storage. Container insertion helpers were renamed, and getters migrated to a namespaced family (for example `ddwaf_object_get_type`).
 - Context cloning exposed through `ddwaf_subcontext` and the allocator factories enable safe parallel use. Builders no longer take a `ddwaf_config*` argument.
 
 ## 1. Remove legacy runtime configuration
 
-`ddwaf_config` and the macros `DDWAF_MAX_STRING_LENGTH`, `DDWAF_MAX_CONTAINER_DEPTH`, `DDWAF_MAX_CONTAINER_SIZE` and `DDWAF_RUN_TIMEOUT` disappeared. Evaluation limits are no longer user-configurable: libddwaf 2.0 ships with built-in safeguards and rejects oversized inputs internally. If you depended on the obfuscator settings, provide them through the configuration documents you load via `ddwaf_init` or `ddwaf_builder_add_or_update_config` (see `src/configuration/configuration_manager.cpp` for the supported `obfuscator` section). There is no replacement for the removed limits hooks.
+`ddwaf_config` and the macros `DDWAF_MAX_STRING_LENGTH`, `DDWAF_MAX_CONTAINER_DEPTH`, `DDWAF_MAX_CONTAINER_SIZE` and `DDWAF_RUN_TIMEOUT` disappeared. Evaluation limits are no longer user-configurable: libddwaf 2.0 ships with built-in safeguards and rejects oversized inputs internally. If you depended on the obfuscator settings, provide them through the configurations you load via `ddwaf_init` or `ddwaf_builder_add_or_update_config` (see `src/configuration/configuration_manager.cpp` for the supported `obfuscator` section). There is no replacement for the removed limits hooks.
 
 ## 2. Update initialization and evaluation
 
@@ -120,7 +120,7 @@ Additional tips:
 
 ## 5. Builder workflow updates
 
-`ddwaf_builder_init` no longer accepts a `ddwaf_config*`. Instantiate it without arguments and pass configuration documents that already carry optional obfuscator settings. Inputs still need to be destroyed with `ddwaf_object_destroy`. The integration test at `tests/integration/interface/builder/test.cpp` reflects the new pattern:
+`ddwaf_builder_init` no longer accepts a `ddwaf_config*`. Instantiate it without arguments and pass configurations that already carry optional obfuscator settings. Inputs still need to be destroyed with `ddwaf_object_destroy`. The integration test at `tests/integration/interface/builder/test.cpp` reflects the new pattern:
 
 ```c
 ddwaf_builder builder = ddwaf_builder_init();
@@ -162,7 +162,7 @@ ddwaf_builder_destroy(builder);
 ## Migration checklist
 
 - [ ] Drop any attempt to configure evaluation limits; they are no longer exposed.
-- [ ] If you rely on custom obfuscator patterns, embed them in the configuration documents you load.
+- [ ] If you rely on custom obfuscator patterns, embed them in the configurations you load.
 - [ ] Update every `ddwaf_context_init` call to pass an allocator and replace `ddwaf_run` with `ddwaf_context_eval`.
 - [ ] Swap out deprecated `ddwaf_object_*` constructors for the allocator-aware setters and ensure destruction happens through `ddwaf_object_destroy`.
 - [ ] Review result-handling code for the new getter helpers and the unified request payload.

From a1168577f94feda65d4d0f72a2e16ea017315668 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Mon, 24 Nov 2025 16:04:11 +0000
Subject: [PATCH 06/32] Add more documentation

---
 docs/README.md   | 21 ++++++++++++-------
 docs/actions.md  |  2 +-
 docs/overview.md |  2 +-
 docs/rules.md    |  6 +++---
 docs/scanners.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 72 insertions(+), 13 deletions(-)
 create mode 100644 docs/scanners.md

diff --git a/docs/README.md b/docs/README.md
index 07505b8c2..6a570a665 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -3,14 +3,19 @@
 The documents below describe libddwaf’s public API and internal primitives. Use them as entry points when integrating or upgrading the engine.
 
 - [Overview](overview.md) – Architectural summary and execution pipeline.
-- [Address Reference](addresses.md) – List of supported ASM addresses and their expected value types.
-- [Operator Reference](operators.md) – Scalar and detector operators with parameters and version notes.
-- [Transformer Reference](transformers.md) – Input transformation utilities available to rules.
-- [Processor Reference](processors.md) – Built-in preprocessors/postprocessors and configuration options.
-- [Actions](actions.md) – Top-level action catalogue referenced by rules.
-- [Rules Configuration](rules.md) – Schema, metadata, and placement of `rules` and `custom_rules` entries in configuration payloads.
-- [Exclusion Filters](exclusions.md) – Configure rule and input exclusions in configurations.
-- [Evaluation Flow](evaluation.md) – Runtime ordering of processors, filters, modules, and WAF collections.
+- [Evaluation](evaluation.md) – Runtime ordering of processors, filters, modules, and WAF collections.
+- Primitives:
+    - [Rules](rules.md) – Schema, metadata, and placement of `rules` and `custom_rules` entries in configuration payloads.
+    - [Processors](processors.md) – Built-in preprocessors/postprocessors and configuration options.
+    - [Exclusion Filters](exclusions.md) – Configure rule and input exclusions in configurations.
+    - [Actions](actions.md) – Top-level action catalogue referenced by rules.
+    - [Scanners](scanners.md) – Include/exclude controls used by processors such as `extract_schema`.
+    - [Conditions](conditions.md) – Shared expression syntax used by rules, processors, and exclusions.
+    - [Addresses](addresses.md) – List of supported and / or commonly used addresses and their expected value types.
+    - [Operators](operators.md) – Scalar and detector operators with parameters and version notes.
+    - [Transformers](transformers.md) – Input transformation utilities available to rules.
 - [C API Reference](c-api/api.md) – Comprehensive description of all exported functions, structs, and macros.
+- [Binding Integration Guide](c-api/binding-integration-guide.md) – Guidance for language bindings embedding libddwaf.
+- [Latest Changelog](changelog/CHANGELOG-latest.md) – Release notes for the current major version; see `docs/changelog/` for history.
 
 For migration guidance, start with [Upgrading to 2.0](upgrading/UPGRADING-v2.0.md) or consult the versioned guides in [`docs/upgrading/`](upgrading/).
diff --git a/docs/actions.md b/docs/actions.md
index 862212f31..ea1e9c955 100644
--- a/docs/actions.md
+++ b/docs/actions.md
@@ -8,7 +8,7 @@ Each entry in `actions` uses this shape:
 
 | Field | Type | Required | Notes |
 | --- | --- | --- | --- |
-| `id` | string | yes | Identifier referenced by `on_match`. Must be unique across the document. |
+| `id` | string | yes | Identifier referenced by `on_match`. Must be unique across the configuration. |
 | `type` | string | yes | One of `block_request`, `redirect_request`, `monitor`, `generate_stack`, `generate_schema`, or a custom type understood by the host application. |
 | `parameters` | object | yes | Free-form parameters passed through to the action mapper and on to the host/caller. |
 
diff --git a/docs/overview.md b/docs/overview.md
index 3197f19fc..73560f648 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -108,7 +108,7 @@ Although postprocessors are defined alongside preprocessors, it is worth calling
 
 A minimal integration typically follows these steps:
 
-1. **Load configuration**: parse the JSON/YAML documents describing rules, processors, exclusions, and overrides into `ddwaf_object` instances, then call `ddwaf_init` (or drive the builder API for multi-document workflows).
+1. **Load configuration**: parse the JSON/YAML configurations describing rules, processors, exclusions, and overrides into `ddwaf_object` instances, then call `ddwaf_init` (or drive the builder API for multi-configuration workflows).
 2. **Create a context per request**: obtain an allocator (`ddwaf_get_default_allocator` or a custom one) and call `ddwaf_context_init`.
 3. **Populate addresses**: build a map of request data (`ddwaf_object_set_map` plus insertion helpers) covering the addresses referenced by your rules and preprocessors.
 4. **Evaluate**: call `ddwaf_context_eval` with the map, allocator, an optional result object, and a timeout. Inspect `DDWAF_MATCH` or `DDWAF_OK`, along with the populated `events`, `actions`, and `attributes`.
diff --git a/docs/rules.md b/docs/rules.md
index 3b161e1af..f9045c086 100644
--- a/docs/rules.md
+++ b/docs/rules.md
@@ -1,12 +1,12 @@
 # Rules and Custom Rules
 
-Configuration documents declare detections under two top-level arrays:
+Configurations declare detections under two top-level arrays:
 
 - `rules`: Datadog-supplied content shipped with the ruleset.
 - `custom_rules`: Tenant- or agent-supplied additions.
 
 Both arrays share the same schema. Entries are merged by ID; IDs must be unique across both arrays or the duplicate is rejected.
-Rule actions referenced via `on_match` are resolved against the document’s action catalogue; see [Actions](actions.md).
+Rule actions referenced via `on_match` are resolved against the configuration’s action catalogue; see [Actions](actions.md).
 
 ## Rule schema
 
@@ -14,7 +14,7 @@ Required fields:
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `id` | string | Stable identifier. Must not collide with any other rule in the document set. |
+| `id` | string | Stable identifier. Must not collide with any other rule in the configuration set. |
 | `name` | string | Human-readable label for diagnostics. |
 | `tags` | object | Metadata emitted in events and used for grouping/overrides. Must include a `type` key; may include `module`, `category`, or any custom taxonomy. |
 | `conditions` | array | Expression evaluated against request data. See the [Condition schema](conditions.md). |
diff --git a/docs/scanners.md b/docs/scanners.md
new file mode 100644
index 000000000..5788827c5
--- /dev/null
+++ b/docs/scanners.md
@@ -0,0 +1,54 @@
+# Scanners
+
+Scanners provide optional annotations and filtering for processors that inspect structured data. They are primarily used by the `extract_schema` processor to tag or prune parts of a generated schema based on predefined logic.
+
+## Where scanners are used
+
+- **`extract_schema`**: accepts a `parameters.scanners` list of includes/excludes by ID or tags. The resolved set of scanner implementations is passed to the processor to influence how fields are marked or trimmed in the generated schema maps (`{address}.schema`).
+
+No other built-in processors currently consume scanners, but the mechanism is extensible for new generators.
+
+## Selection rules
+
+When resolving the scanner set, references are applied in this precedence order (`src/processor/extract_schema.*`):
+
+1. Exclusions by ID.
+2. Inclusions by ID.
+3. Exclusions by tags.
+4. Inclusions by tags.
+
+This ordering ensures explicit IDs win over tag-based selectors, and exclusions win over inclusions.
+
+## Configuration shape
+
+Within a processor definition:
+
+```json
+{
+  "id": "schema-extractor",
+  "generator": "extract_schema",
+  "parameters": {
+    "scanners": {
+      "include": ["trusted-scanner-id"],
+      "exclude": [{ "tags": ["experimental"] }]
+    },
+    "mappings": [
+      { "inputs": [{ "address": "server.request.body" }], "output": "server.request.body.schema" }
+    ]
+  },
+  "evaluate": true
+}
+```
+
+- `include` / `exclude` accept a mix of IDs (strings) and tag selectors (`{ "tags": [...] }`).
+- If neither include nor exclude is provided, all scanners are available to the processor.
+
+## Runtime behaviour
+
+Each selected scanner can:
+
+- Annotate schema nodes (for example mark sensitive fields).
+- Suppress nodes that match pruning criteria.
+- Leave the node untouched.
+
+The processor applies scanners to every visited node during schema extraction, respecting the include/exclude set resolved at configuration load time.

From e7a125ecdb1deffcb4016dde83a0547f2eb5c43a Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Mon, 24 Nov 2025 16:43:55 +0000
Subject: [PATCH 07/32] Add more documentation

---
 docs/README.md                     |  3 ++
 docs/changelog/CHANGELOG-v2.0.0.md | 30 +++++++++++++++++++
 docs/processor_overrides.md        | 47 ++++++++++++++++++++++++++++++
 docs/rule_data.md                  | 36 +++++++++++++++++++++++
 docs/rule_overrides.md             | 47 ++++++++++++++++++++++++++++++
 5 files changed, 163 insertions(+)
 create mode 100644 docs/processor_overrides.md
 create mode 100644 docs/rule_data.md
 create mode 100644 docs/rule_overrides.md

diff --git a/docs/README.md b/docs/README.md
index 6a570a665..4535846f2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -10,6 +10,9 @@ The documents below describe libddwaf’s public API and internal primitives. Us
     - [Exclusion Filters](exclusions.md) – Configure rule and input exclusions in configurations.
     - [Actions](actions.md) – Top-level action catalogue referenced by rules.
     - [Scanners](scanners.md) – Include/exclude controls used by processors such as `extract_schema`.
+    - [Rule Overrides](rule_overrides.md) – Adjust rule behaviour without redefining rules.
+    - [Processor Overrides](processor_overrides.md) – Incrementally include/exclude scanners on processors.
+    - [Rules Data](rule_data.md) – External datasets referenced by operators.
     - [Conditions](conditions.md) – Shared expression syntax used by rules, processors, and exclusions.
     - [Addresses](addresses.md) – List of supported and / or commonly used addresses and their expected value types.
     - [Operators](operators.md) – Scalar and detector operators with parameters and version notes.
diff --git a/docs/changelog/CHANGELOG-v2.0.0.md b/docs/changelog/CHANGELOG-v2.0.0.md
index e69de29bb..a41d04502 100644
--- a/docs/changelog/CHANGELOG-v2.0.0.md
+++ b/docs/changelog/CHANGELOG-v2.0.0.md
@@ -0,0 +1,30 @@
+## v2.0.0-alpha0
+
+### Changes
+
+- Object model overhaul: immutable `object_view`, owned/borrowed writable objects, raw configuration on `object_view`, container view types, and updated unit tests ([#341](https://github.com/DataDog/libddwaf/pull/341), [#378](https://github.com/DataDog/libddwaf/pull/378), [#382](https://github.com/DataDog/libddwaf/pull/382), [#387](https://github.com/DataDog/libddwaf/pull/387), [#390](https://github.com/DataDog/libddwaf/pull/390), [#391](https://github.com/DataDog/libddwaf/pull/391), [#394](https://github.com/DataDog/libddwaf/pull/394), [#408](https://github.com/DataDog/libddwaf/pull/408), [#413](https://github.com/DataDog/libddwaf/pull/413)), ([#476](https://github.com/DataDog/libddwaf/pull/476)).
+- Allocator API: propagate allocators through contexts/subcontexts, expose allocator-aware interfaces, and stop generating zero-terminated strings ([#418](https://github.com/DataDog/libddwaf/pull/418), [#420](https://github.com/DataDog/libddwaf/pull/420), [#427](https://github.com/DataDog/libddwaf/pull/427), [#452](https://github.com/DataDog/libddwaf/pull/452)).
+- Refactored evaluation lifecycle: separated data insertion from evaluation and lifted evaluation stages out of the context ([#407](https://github.com/DataDog/libddwaf/pull/407), [#442](https://github.com/DataDog/libddwaf/pull/442)).
+- Subcontexts with user-defined lifetimes and validator support for subcontexts/attributes ([#443](https://github.com/DataDog/libddwaf/pull/443), [#451](https://github.com/DataDog/libddwaf/pull/451)), ([#468](https://github.com/DataDog/libddwaf/pull/468)).
+- Array indexing on key paths ([#458](https://github.com/DataDog/libddwaf/pull/458)).
+- Instantiate obfuscator through configuration and remove `ddwaf_config` ([#464](https://github.com/DataDog/libddwaf/pull/464)).
+- Return `DDWAF_MATCH` when events, attributes, or actions are present ([#455](https://github.com/DataDog/libddwaf/pull/455)).
+
+### Miscellaneous
+
+- Upgrade fmt dependency and use as header-only ([#478](https://github.com/DataDog/libddwaf/pull/478)).
+- Increase macOS target to 14.2.1 ([#477](https://github.com/DataDog/libddwaf/pull/477)).
+- Add option to build on valgrind to avoid RE2 UB noise ([#480](https://github.com/DataDog/libddwaf/pull/480)).
+- Lint all headers and add tests ([#474](https://github.com/DataDog/libddwaf/pull/474)).
+- Intertwine context and subcontext calls within benchmark ([#469](https://github.com/DataDog/libddwaf/pull/469)).
+- Disable unreliable GCC / Clang benchmarks ([#470](https://github.com/DataDog/libddwaf/pull/470)).
+- Upload coverage reports to Datadog ([#471](https://github.com/DataDog/libddwaf/pull/471)).
+- Remove mingw builds ([#381](https://github.com/DataDog/libddwaf/pull/381)).
+- Cleanup exclusion namespace and redundant references ([#456](https://github.com/DataDog/libddwaf/pull/456)).
+- Expanded fingerprint and object-view tests ([#414](https://github.com/DataDog/libddwaf/pull/414)).
+- Add fuzzer v2 ([#465](https://github.com/DataDog/libddwaf/pull/465)).
+- Update logger to avoid dependencies on `ddwaf.h` ([#453](https://github.com/DataDog/libddwaf/pull/453)).
+
+### Documentation
+
+- Consolidated configuration docs (rules, actions, processors, exclusions, conditions) and added evaluation and scanners references.
diff --git a/docs/processor_overrides.md b/docs/processor_overrides.md
new file mode 100644
index 000000000..f5033a55f
--- /dev/null
+++ b/docs/processor_overrides.md
@@ -0,0 +1,47 @@
+# Processor Overrides
+
+Processor overrides tweak processor definitions without redefining them. They live in the top-level `processor_overrides` array and currently control scanner selection for `extract_schema`.
+
+## Schema
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `target` | array | yes | Identifies processors by `id` or `tags`. |
+| `scanners.include` | array | no | Scanners to add (by `id` or `tags`). |
+| `scanners.exclude` | array | no | Scanners to remove (by `id` or `tags`). |
+
+At least one of `scanners.include` or `scanners.exclude` must be provided.
+
+### Targets
+
+Each entry in `target` accepts:
+
+- `id`: processor identifier.
+- `tags`: processor tags (all key/value pairs must match).
+
+### Scanner merging
+
+Overrides are incremental: includes add scanners, excludes remove scanners from the processor’s configured set. The resolution order matches scanner selection precedence:
+
+1. Exclude by ID.
+2. Include by ID.
+3. Exclude by tags.
+4. Include by tags.
+
+Multiple overrides against the same processor are applied in sequence; later changes win when conflicting.
+
+## Example
+
+```json
+{
+  "processor_overrides": [
+    {
+      "target": [{ "id": "extract_schema_body" }],
+      "scanners": {
+        "include": [{ "id": "scanner-allowlist" }],
+        "exclude": [{ "tags": { "type": "experimental" } }]
+      }
+    }
+  ]
+}
+```
diff --git a/docs/rule_data.md b/docs/rule_data.md
new file mode 100644
index 000000000..3976cfbff
--- /dev/null
+++ b/docs/rule_data.md
@@ -0,0 +1,36 @@
+# Rules Data
+
+Rules data supplies external datasets consumed by operators such as `ip_match` and `exact_match`. It lives in the top-level `rules_data` map keyed by dataset identifier.
+
+## Schema
+
+`rules_data` is a map of entries:
+
+| Key | Value type | Description |
+| --- | --- | --- |
+| `<data_id>` | array | List of values for the dataset (strings for regex/phrase data, IP/CIDR strings for `ip_match`, etc.). |
+
+Datasets can be shared across base and custom rules as long as the `data` field in the rule’s operator points to the same `<data_id>`.
+
+## Example
+
+```json
+{
+  "rules_data": {
+    "trusted-ips": [
+      "10.0.0.0/8",
+      "192.168.0.0/16"
+    ],
+    "blocked-usernames": [
+      "admin",
+      "root"
+    ]
+  }
+}
+```
+
+A rule using `ip_match` may reference `"data": "trusted-ips"`; a rule using `exact_match` can reference `"data": "blocked-usernames"`.
+
+## Diagnostics
+
+During parsing, datasets are validated for type correctness per operator. Parsing diagnostics report missing datasets or invalid entries, and rules that reference invalid data are rejected.
diff --git a/docs/rule_overrides.md b/docs/rule_overrides.md
new file mode 100644
index 000000000..759ef9675
--- /dev/null
+++ b/docs/rule_overrides.md
@@ -0,0 +1,47 @@
+# Rule Overrides
+
+Rule overrides adjust existing rules without redefining them. They live in the top-level `rules_override` array and are applied after rules/custom_rules are loaded.
+
+## Schema
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `rules_target` | array | yes | Targets selected rules by `id`/`rule_id` or `tags`. |
+| `enabled` | boolean | no | Forces enabled/disabled state. |
+| `on_match` | string | no | Overrides the action to emit (for example `monitor` or a custom action ID). |
+| `tags` | object | no | Additional tags to merge into the rule’s metadata. |
+| `transformers` | array | no | Overrides the rule-level transformer list. |
+
+An override must specify at least one mutating field (`enabled`, `on_match`, `tags`, or `transformers`).
+
+### Targets
+
+Each entry in `rules_target` accepts:
+
+- `id` / `rule_id`: exact rule identifier.
+- `tags`: object of tags to match (all key/value pairs must match).
+
+### Behaviour
+
+- Overrides are applied in order; later overrides replace earlier ones for the same rule attributes.
+- Tag additions merge into the existing tag set.
+- Providing `transformers` replaces the rule’s transformer list entirely.
+- `on_match` replaces the rule’s action list; use exclusions for conditional bypass/monitor.
+
+## Example
+
+```json
+{
+  "rules_override": [
+    {
+      "rules_target": [{ "tags": { "type": "lfi" } }],
+      "enabled": false
+    },
+    {
+      "rules_target": [{ "rule_id": "crs-930-120" }],
+      "on_match": "monitor",
+      "tags": { "policy": "allowlist" }
+    }
+  ]
+}
+```

From 12f421ba99343fa26771463823a70585b5d4f4e9 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 3 Dec 2025 21:05:49 +0000
Subject: [PATCH 08/32] WIP

---
 docs/README.md     |  21 +-------
 docs/evaluation.md |  61 ----------------------
 docs/overview.md   | 125 ++++++++++++++++++++++++++++-----------------
 3 files changed, 81 insertions(+), 126 deletions(-)
 delete mode 100644 docs/evaluation.md

diff --git a/docs/README.md b/docs/README.md
index 4535846f2..d0a7785ce 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,24 +1,7 @@
 # Documentation Index
 
-The documents below describe libddwaf’s public API and internal primitives. Use them as entry points when integrating or upgrading the engine.
-
 - [Overview](overview.md) – Architectural summary and execution pipeline.
-- [Evaluation](evaluation.md) – Runtime ordering of processors, filters, modules, and WAF collections.
-- Primitives:
-    - [Rules](rules.md) – Schema, metadata, and placement of `rules` and `custom_rules` entries in configuration payloads.
-    - [Processors](processors.md) – Built-in preprocessors/postprocessors and configuration options.
-    - [Exclusion Filters](exclusions.md) – Configure rule and input exclusions in configurations.
-    - [Actions](actions.md) – Top-level action catalogue referenced by rules.
-    - [Scanners](scanners.md) – Include/exclude controls used by processors such as `extract_schema`.
-    - [Rule Overrides](rule_overrides.md) – Adjust rule behaviour without redefining rules.
-    - [Processor Overrides](processor_overrides.md) – Incrementally include/exclude scanners on processors.
-    - [Rules Data](rule_data.md) – External datasets referenced by operators.
-    - [Conditions](conditions.md) – Shared expression syntax used by rules, processors, and exclusions.
-    - [Addresses](addresses.md) – List of supported and / or commonly used addresses and their expected value types.
-    - [Operators](operators.md) – Scalar and detector operators with parameters and version notes.
-    - [Transformers](transformers.md) – Input transformation utilities available to rules.
 - [C API Reference](c-api/api.md) – Comprehensive description of all exported functions, structs, and macros.
 - [Binding Integration Guide](c-api/binding-integration-guide.md) – Guidance for language bindings embedding libddwaf.
-- [Latest Changelog](changelog/CHANGELOG-latest.md) – Release notes for the current major version; see `docs/changelog/` for history.
-
-For migration guidance, start with [Upgrading to 2.0](upgrading/UPGRADING-v2.0.md) or consult the versioned guides in [`docs/upgrading/`](upgrading/).
+- [Latest Changelog](changelog/CHANGELOG-latest.md) – Release notes for the current version; see the [changelog](changelog/) directory for previous versions.
+- [Upgrading Guides](upgrading/) - Upgrading guides for all versions with relevant and / or breaking changes.
\ No newline at end of file
diff --git a/docs/evaluation.md b/docs/evaluation.md
deleted file mode 100644
index 014914792..000000000
--- a/docs/evaluation.md
+++ /dev/null
@@ -1,61 +0,0 @@
-# Evaluation Flow
-
-How `evaluation_engine` runs processors, exclusions, and rules during `ddwaf_context_eval`, based on `evaluation_engine.cpp`, `module.cpp`, and the module builder.
-
-## Pipeline overview
-
-1. **Skip if no new inputs**: if the `object_store` has no new targets, return immediately.
-2. **Preprocessors**: run in configured order, populating derived addresses. Each processor has a per-instance cache keyed by its pointer.
-3. **Filters**: evaluate rule filters then input filters. Matches populate an `exclusion_policy` (bypass/monitor/custom action, plus input pruning) used by rules.
-4. **Rules**: walk modules in fixed order (below). Blocking verdicts short-circuit the rest of the module set; monitor verdicts allow continued evaluation.
-5. **Postprocessors**: always run after rules; they may add attributes but never affect matching.
-6. **Serialize**: gather events, actions, attributes, and obfuscation into the result. If any rule fired, the engine injects `waf.context.event` so postprocessors can gate on it.
-
-Processor, filter, and rule caches persist across evaluations so repeated data does not trigger repeated work.
-
-## Processor execution
-
-- **Preprocessors** (`evaluate: true`) run before filters/rules and write outputs into the object store (cloned into the caller allocator as needed).
-- **Postprocessors** (`output: true`) run after rules and only affect serialized attributes.
-- Processor expressions gate execution; optional inputs trigger re-evaluation only when new data appears. The deadline is honoured; a timeout aborts remaining processors in that phase.
-
-## Filters and exclusions
-
-- **Rule filters** can bypass a rule, force monitor, or override the action to a custom value. Results are cached per filter instance.
-- **Input filters** prune addresses (with optional key paths) for selected rules. Pruned inputs are invisible to matching and transformers.
-- The combined `exclusion_policy` is consulted for every rule before evaluation to apply bypass/monitor/custom verdicts and input pruning.
-
-## Module ordering and deadlines
-
-Modules run in this fixed sequence (`module_category.hpp`). Each module sorts rules by verdict first (`block` before `monitor`) and then by source (Datadog vs. user) according to the policy below. A blocking rule stops the module; a monitor rule records a monitor verdict and lets evaluation continue.
-
-1. **`network-acl`** *(non-expiring)*  
-   - Ordering: Datadog before user.  
-   - Deadline: ignored; always runs to completion.
-2. **`authentication-acl`** *(non-expiring)*  
-   - Ordering: Datadog before user.  
-   - Deadline: ignored; always runs to completion.
-3. **`custom-acl`**  
-   - Ordering: user before Datadog.  
-   - Deadline: enforced.
-4. **`configuration`**  
-   - Ordering: user before Datadog.  
-   - Deadline: enforced.
-5. **`business-logic`**  
-   - Ordering: user before Datadog.  
-   - Deadline: enforced.
-6. **`rasp`**  
-   - Ordering: Datadog before user.  
-   - Deadline: enforced.
-7. **`waf`** *(collection-based)*  
-   - Collections: grouped by `tags.type`, verdict, and source in this order: user `block`, Datadog `block`, user `monitor`, Datadog `monitor`.  
-   - Caching: each collection caches its verdict; collections already satisfied at the same or higher verdict are skipped on later evaluations.  
-   - Execution: within a collection, rules run sequentially until one matches or the deadline expires. A `block` result stops remaining collections and modules; a `monitor` result records the verdict and moves to the next collection to gather more context.  
-   - Deadline: enforced.
-
-## Practical notes
-
-- Only addresses seen as new trigger work; unchanged inputs can skip processors, filters, and rules.
-- Non-expiring modules (`network-acl`, `authentication-acl`) ignore deadlines; all others honour them.
-- Postprocessors still run after a rule-timeout so existing data can surface in attributes.
-- Exclusions apply per rule right before condition evaluation, enabling fine-grained bypass/monitor/action overrides without editing rules.
diff --git a/docs/overview.md b/docs/overview.md
index 73560f648..516437806 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -1,7 +1,15 @@
+Libddwaf is Datadog's security data analysis engine, used to evaluate request, response and arbitrary instrumentation data in order to identify events of different security categories, such as WAF, RASP, API Security, Business logic, etc.
 
-# Understanding libddwaf
+Primitives
 
-libddwaf is Datadog’s embeddable security engine. It ingests a declarative security configuration (rules, exclusions, processors, actions) and exposes a compact C API that any tracer or agent can use to evaluate inbound requests. At runtime the library:
+Execution Pipeline
+
+Configuration
+
+
+
+
+libddwaf is Datadog's embeddable security engine. It ingests a declarative security configuration (rules, exclusions, processors, actions) and exposes a compact C API that any tracer or agent can use to evaluate inbound requests. At runtime the library:
 
 1. Parses one or more configurations into an immutable **WAF handle** (`ddwaf_handle`).
 2. Creates per-request **contexts** (`ddwaf_context`) bound to the handle and a memory allocator.
@@ -22,7 +30,7 @@ When a context receives new data, libddwaf processes it in a fixed order:
 4. **Postprocessors** run after rule evaluation to augment the result payload—typically by calculating additional attributes or serialising payloads for downstream systems.
 5. The serializer aggregates matches, actions, derived attributes, and timeout information into the `result` object returned by `ddwaf_context_eval`.
 
-Any step can terminate early if the caller’s timeout elapses; in that case the engine short-circuits remaining work while preserving as much partial state as possible.
+Any step can terminate early if the caller's timeout elapses; in that case the engine short-circuits remaining work while preserving as much partial state as possible.
 
 ---
 
@@ -36,71 +44,87 @@ Rules define the core detection logic. Each rule carries:
 - One or more **conditions**, each of which applies an operator (such as `match_regex`, `phrase_match`, or `validate_schema`) to a set of addresses. Conditions may also specify key paths and transformers.
 - Optional **actions** or overrides that tell integrating products how to respond when the rule matches.
 
-Rules are grouped by **module** internally (for example `network-acl`, `business-logic`, `waf`). Modules isolate specialised detection logic and let the engine maintain separate matcher caches. Each module sorts its rules first by the verdict they can emit (`block` before `monitor`), then by the rule **source** (user vs. Datadog) according to the precedence defined for that module (see *Module ordering and short-circuiting* below), and finally by the rule “type” string when applicable. If a rule returns a blocking verdict the module stops evaluating further rules, avoiding duplicate work once a decisive outcome is known. Monitor-level matches still allow evaluation to continue so other informative events can be collected.
+Rules are grouped by **module** internally (for example `network-acl`, `business-logic`, `waf`). Modules isolate specialised detection logic and let the engine maintain separate matcher caches. Each module sorts its rules first by the verdict they can emit (`block` before `monitor`), then by the rule **source** (user vs. Datadog) according to the precedence defined for that module (see *Module ordering and deadlines* below), and finally by the rule "type" string when applicable. If a rule returns a blocking verdict the module stops evaluating further rules, avoiding duplicate work once a decisive outcome is known. Monitor-level matches still allow evaluation to continue so other informative events can be collected.
 
-#### Module ordering and short-circuiting
+### Processors: Preprocessors and Postprocessors
 
-`src/builder/module_builder.cpp` assigns every rule to one of seven categories:
+Processors are reusable pieces of logic that transform request data. Each entry in the `processors` section of the configuration specifies a `generator` (for example `uri_parse`, `extract_schema`, `jwt_decode`, or `fingerprint`), optional conditions, and a set of input/output mappings.
 
-1. `network-acl`
-2. `authentication-acl`
-3. `custom-acl`
-4. `configuration`
-5. `business-logic`
-6. `rasp`
-7. `waf`
+Two booleans determine when a processor runs:
 
-The engine evaluates modules in that exact order every time `ddwaf_context_eval` runs. The first two categories are marked as *non-expiring* in `module_builder.hpp`, so `network-acl` and `authentication-acl` always run to completion even if the caller-provided timeout expires. Modules `custom-acl` through `waf` propagate the deadline and will abort early once the budget is exhausted.
+- `evaluate: true` marks a **preprocessor**. It runs before exclusions and rules, and any derived addresses are available to matchers in the same evaluation. Typical use cases include decomposing URLs, parsing JWTs, or generating request fingerprints.
+- `output: true` marks a **postprocessor**. It runs after rules complete and can emit additional attributes into the result object—for example to expose the parsed URI or schema extraction summaries to telemetry pipelines.
 
-Within each module, rule precedence differs:
+A single processor can act as both a pre- and postprocessor by setting both flags.
 
-- `network-acl`, `authentication-acl`, and `rasp` examine Datadog-supplied rules before user-defined ones. These guardrails are meant to fire reliably even when custom rules are misconfigured.
-- `custom-acl`, `configuration`, `business-logic`, and `waf` prioritise user rules so that tenant-specific logic can take precedence over built-in defaults.
+Processors are cached per context so expensive computations are only repeated when their inputs change. They can also depend on **scanners**, which provide auxiliary data (for example known good fingerprints) to generator implementations.
 
-The `waf` module groups rules by their `type` tag. For each type, user blocking rules run first, followed by Datadog blocking rules, then user monitor rules, and finally Datadog monitor rules. A blocking verdict inside any collection short-circuits the remaining collections and modules. This layering ensures user logic can override defaults where appropriate without sacrificing baseline coverage from Datadog’s managed rules. When a module produces a blocking verdict, remaining modules are skipped and the pipeline advances directly to postprocessors.
+Processor expressions gate execution; optional inputs trigger re-evaluation only when new data appears. The deadline is honoured; a timeout aborts remaining processors in that phase.
+
+### Exclusion Filters
+
+Exclusion filters allow operators to silence noisy rules or drop inputs that should not be considered during evaluation. The configuration distinguishes two flavours:
+
+- **Rule filters** decide whether entire rules (or groups of rules identified by tags) should be skipped. They can bypass a rule, force monitor, or override the action to a custom value. They often key off request metadata such as the current service, endpoint, or environment.
+- **Input filters** remove or redact specific addresses (with optional key paths) before rules see them. Pruned inputs are invisible to matching and transformers. They are useful to shield sensitive fields from inspection or to ignore known benign payloads that would otherwise trigger false positives.
+
+Both filter types execute before rule evaluation, and their decisions are cached so later calls within the same context remain consistent. The combined `exclusion_policy` is consulted for every rule before evaluation to apply bypass/monitor/custom verdicts and input pruning.
 
 ---
 
 ## Evaluation Flow
 
-The diagram below summarises how the primitives interact during a single call to `ddwaf_context_eval`:
+This section provides implementation-level detail on how `evaluation_engine` runs processors, exclusions, and rules during `ddwaf_context_eval`, based on `evaluation_engine.cpp`, `module.cpp`, and the module builder.
 
-During a single `ddwaf_context_eval` call:
+### Pipeline Overview
+
+1. **Skip if no new inputs**: if the `object_store` has no new targets, return immediately.
+2. **Preprocessors**: run in configured order, populating derived addresses. Each processor has a per-instance cache keyed by its pointer.
+3. **Filters**: evaluate rule filters then input filters. Matches populate an `exclusion_policy` (bypass/monitor/custom action, plus input pruning) used by rules.
+4. **Rules**: walk modules in fixed order (below). Blocking verdicts short-circuit the rest of the module set; monitor verdicts allow continued evaluation.
+5. **Postprocessors**: always run after rules; they may add attributes but never affect matching.
+6. **Serialize**: gather events, actions, attributes, and obfuscation into the result. If any rule fired, the engine injects `waf.context.event` so postprocessors can gate on it.
+
+Processor, filter, and rule caches persist across evaluations so repeated data does not trigger repeated work.
+
+### During a Single Evaluation
 
 - The incoming `ddwaf_object` map is handed to preprocessors (`evaluate: true` processors) which can create or rewrite addresses. Their outputs become part of the context store.
 - Rule and input exclusion filters run next, pruning the address set or muting matching rules before any detection logic executes.
-- The engine iterates through the modules in fixed order (`network-acl`, `authentication-acl`, `custom-acl`, `configuration`, `business-logic`, `rasp`, `waf`). The first two modules are non-expiring and always run to completion; the remaining modules respect the caller’s timeout.
+- The engine iterates through the modules in fixed order (`network-acl`, `authentication-acl`, `custom-acl`, `configuration`, `business-logic`, `rasp`, `waf`). The first two modules are non-expiring and always run to completion; the remaining modules respect the caller's timeout.
 - Inside each module, rules are ordered by verdict, source precedence (user vs. Datadog), and optionally type. If a rule returns a blocking verdict the module stops and subsequent modules are skipped; monitor verdicts allow evaluation to continue.
 - Once the module loop finishes (or short-circuits), postprocessors (`output: true` processors) enrich the collector with derived attributes that will appear in the result payload.
 - The serializer produces the final `result` object: matches, actions, derived attributes, execution metadata, and the `DDWAF_OK`/`DDWAF_MATCH` status that the caller receives.
 
 This sequencing keeps the evaluation deterministic while allowing preprocessors, filters, and postprocessors to cooperate around the shared context state.
 
-### Processors: Preprocessors and Postprocessors
-
-Processors are reusable pieces of logic that transform request data. Each entry in the `processors` section of the configuration specifies a `generator` (for example `uri_parse`, `extract_schema`, `jwt_decode`, or `fingerprint`), optional conditions, and a set of input/output mappings.
-
-Two booleans determine when a processor runs:
-
-- `evaluate: true` marks a **preprocessor**. It runs before exclusions and rules, and any derived addresses are available to matchers in the same evaluation. Typical use cases include decomposing URLs, parsing JWTs, or generating request fingerprints.
-- `output: true` marks a **postprocessor**. It runs after rules complete and can emit additional attributes into the result object—for example to expose the parsed URI or schema extraction summaries to telemetry pipelines.
-
-A single processor can act as both a pre- and postprocessor by setting both flags.
-
-Processors are cached per context so expensive computations are only repeated when their inputs change. They can also depend on **scanners**, which provide auxiliary data (for example known good fingerprints) to generator implementations.
-
-### Exclusion Filters
-
-Exclusion filters allow operators to silence noisy rules or drop inputs that should not be considered during evaluation. The configuration distinguishes two flavours:
-
-- **Rule filters** decide whether entire rules (or groups of rules identified by tags) should be skipped. They often key off request metadata such as the current service, endpoint, or environment.
-- **Input filters** remove or redact specific addresses before rules see them. They are useful to shield sensitive fields from inspection or to ignore known benign payloads that would otherwise trigger false positives.
-
-Both filter types execute before rule evaluation, and their decisions are cached so later calls within the same context remain consistent.
-
-### Postprocessors (Result Enrichment)
-
-Although postprocessors are defined alongside preprocessors, it is worth calling them out separately: a postprocessor (`output: true`) runs after all rules have evaluated and has access to the request store, the intermediate collector, and the actions selected by the rules. Its job is to attach derived attributes—such as structured URI fields, schema summaries, or decoded tokens—to the `attributes` section of the result returned by `ddwaf_context_eval`. Those attributes help downstream systems present rich diagnostics without recomputing heavy transformations.
+### Module Ordering and Deadlines
+
+Modules run in this fixed sequence (`module_category.hpp`). Each module sorts rules by verdict first (`block` before `monitor`) and then by source (Datadog vs. user) according to the policy below. A blocking rule stops the module; a monitor rule records a monitor verdict and lets evaluation continue.
+
+1. **`network-acl`** *(non-expiring)*  
+   - Ordering: Datadog before user.  
+   - Deadline: ignored; always runs to completion.
+2. **`authentication-acl`** *(non-expiring)*  
+   - Ordering: Datadog before user.  
+   - Deadline: ignored; always runs to completion.
+3. **`custom-acl`**  
+   - Ordering: user before Datadog.  
+   - Deadline: enforced.
+4. **`configuration`**  
+   - Ordering: user before Datadog.  
+   - Deadline: enforced.
+5. **`business-logic`**  
+   - Ordering: user before Datadog.  
+   - Deadline: enforced.
+6. **`rasp`**  
+   - Ordering: Datadog before user.  
+   - Deadline: enforced.
+7. **`waf`** *(collection-based)*  
+   - Collections: grouped by `tags.type`, verdict, and source in this order: user `block`, Datadog `block`, user `monitor`, Datadog `monitor`.  
+   - Caching: each collection caches its verdict; collections already satisfied at the same or higher verdict are skipped on later evaluations.  
+   - Execution: within a collection, rules run sequentially until one matches or the deadline expires. A `block` result stops remaining collections and modules; a `monitor` result records the verdict and moves to the next collection to gather more context.  
+   - Deadline: enforced.
 
 ---
 
@@ -115,3 +139,12 @@ A minimal integration typically follows these steps:
 5. **Clean up**: destroy the result with `ddwaf_object_destroy`, then destroy the context (and allocator if you created a custom one).
 
 Because preprocessors, exclusion filters, and postprocessors all operate deterministically on the same address store, their combined effect keeps the rule execution focused on actionable signals while still surfacing rich telemetry to downstream pipelines.
+
+---
+
+## Practical Notes
+
+- Only addresses seen as new trigger work; unchanged inputs can skip processors, filters, and rules.
+- Non-expiring modules (`network-acl`, `authentication-acl`) ignore deadlines; all others honour them.
+- Postprocessors still run after a rule-timeout so existing data can surface in attributes.
+- Exclusions apply per rule right before condition evaluation, enabling fine-grained bypass/monitor/action overrides without editing rules.

From 3c5d5ec68b6ac542576e85084279a180a2fe00cd Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Fri, 12 Dec 2025 16:58:01 +0000
Subject: [PATCH 09/32] Update UPGRADING-v2.0.md

---
 docs/upgrading/UPGRADING-v2.0.md | 184 +++++++------------------------
 1 file changed, 39 insertions(+), 145 deletions(-)

diff --git a/docs/upgrading/UPGRADING-v2.0.md b/docs/upgrading/UPGRADING-v2.0.md
index f819c3d09..201441798 100644
--- a/docs/upgrading/UPGRADING-v2.0.md
+++ b/docs/upgrading/UPGRADING-v2.0.md
@@ -1,170 +1,64 @@
 # Upgrading libddwaf
 
-This guide helps you migrate call sites of the C API from libddwaf 1.30.x to 2.0.0. It captures the high-impact breaking changes and illustrates them with snippets lifted from the integration tests that ship with 2.0.
+The C API in libddwaf v2 has experienced a large number of changes, primarily around the creation and use of ddwaf_object. This guide aims to provide an overview of the changes required to upgrade from v1.x to v2.x, however it is recommended that the reader carefully reads the [C API Reference](c-api/api.md) and [ddwaf.h](../../include/ddwaf.h).
 
-## Migration Overview
-- Evaluation limits, obfuscator regexes and the result free hook inside `ddwaf_config` have been removed. The core now enforces internal limits; only the obfuscator survives and must be supplied inside configurations when needed. All memory ownership should switch to the allocator API.
-- `ddwaf_run` has been replaced by `ddwaf_context_eval`. Persistent and ephemeral maps are merged into a single input object, and every evaluation needs an allocator handle.
-- `ddwaf_object_*` constructors now accept the allocator that owns the storage. Container insertion helpers were renamed, and getters migrated to a namespaced family (for example `ddwaf_object_get_type`).
-- Context cloning exposed through `ddwaf_subcontext` and the allocator factories enable safe parallel use. Builders no longer take a `ddwaf_config*` argument.
+## Summary
+- Allocators have been introduced to all relevant API functions.
+- The layout of `ddwaf_object` has dramatically changed to reduce the amount of memory required for a single object, which now only requires 16 bytes.
+- Two new string types have been introduced:
+  - Small string: a string of 14 bytes or less, stored within the object memory itself without extra allocations.
+  - Literal string: a c-string which should be treated as read-only and never freed.
+- Object creation and access functions have been changed significantly, primarily to avoid the need for intermediate objects.
+- `ddwaf_run` has been renamed to `ddwaf_context_eval`.
+- Subcontexts have been introduced to replace ephemerals, their lifecycle and use is equivalent to that of the context.
+- `ddwaf_config` has been removed:
+  - Evaluation limits have been entirely removed, the caller must now enforce any relevant limits during serialisation.
+  - Obfuscator regexes must now be provided through configuration: `{obfuscator: {key_regex: <value>, value_regex: <value>}}`.
+  - The free function is no longer needed due to the introduction of allocators.
 
-## 1. Remove legacy runtime configuration
+## Note on Allocators
+The ownership of any allocated memory crossing the API boundary was one of the pain points of libddwaf v1. To fix this, v2 introduces allocators, which can be used to define the explicit ownership of the allocated memory.
 
-`ddwaf_config` and the macros `DDWAF_MAX_STRING_LENGTH`, `DDWAF_MAX_CONTAINER_DEPTH`, `DDWAF_MAX_CONTAINER_SIZE` and `DDWAF_RUN_TIMEOUT` disappeared. Evaluation limits are no longer user-configurable: libddwaf 2.0 ships with built-in safeguards and rejects oversized inputs internally. If you depended on the obfuscator settings, provide them through the configurations you load via `ddwaf_init` or `ddwaf_builder_add_or_update_config` (see `src/configuration/configuration_manager.cpp` for the supported `obfuscator` section). There is no replacement for the removed limits hooks.
+Since the use of allocators is now required on many of the API functions, the migration examples will use the default allocator and will also include allocator destruction for illustrative purposes, as the destruction of the default allocator is a no-op.
 
-## 2. Update initialization and evaluation
+See the [allocators document](../allocators.md) for more information on the different types of allocators available.
 
-`ddwaf_init` now only expects the ruleset and an optional diagnostics object. Context creation requires an allocator, and the evaluation call takes a single request payload. The following example shows the common migration (compare `tests/integration/context/test.cpp` with its `1.30.0` counterpart):
+## 1. WAF instantiation: removal of `ddwaf_config`
 
-```c
-/* libddwaf 1.30.x */
-ddwaf_config cfg{
-    {.max_container_size = 256, .max_container_depth = 20, .max_string_length = 4096},
-    {.key_regex = nullptr, .value_regex = nullptr},
-    ddwaf_object_free
-};
-
-ddwaf_handle handle = ddwaf_init(&ruleset, &cfg, /*diagnostics=*/nullptr);
-ddwaf_context ctx = ddwaf_context_init(handle);
-
-ddwaf_object args = DDWAF_OBJECT_MAP;
-ddwaf_object tmp;
-ddwaf_object_map_add(&args, "value", ddwaf_object_string(&tmp, "rule2"));
-
-ddwaf_object result;
-DDWAF_RET_CODE rc = ddwaf_run(ctx, &args, /*ephemeral=*/nullptr, &result, timeout);
-ddwaf_object_free(&result);
-ddwaf_context_destroy(ctx);
-ddwaf_destroy(handle);
-```
+The main changes pertaining to WAF initialisation is the removal of `ddwaf_config`, as the evaluation limits have been entirely removed in favour of user-controlled truncation and the free function is no longer required due to the explicit memory ownership defined through allocators. As a consequence, instantiation through `ddwaf_init` has changed as follows:
 
+**v1.x:**
 ```c
-/* libddwaf 2.0.0 */
-ddwaf_allocator alloc = ddwaf_get_default_allocator();
-ddwaf_handle handle = ddwaf_init(&ruleset, /*diagnostics=*/nullptr);
-ddwaf_context ctx = ddwaf_context_init(handle, alloc);
-
-ddwaf_object args;
-ddwaf_object_set_map(&args, 1, alloc);
-ddwaf_object_set_string(
-    ddwaf_object_insert_key(&args, "value", sizeof("value") - 1, alloc),
-    "rule2", sizeof("rule2") - 1, alloc);
-
-ddwaf_object result;
-DDWAF_RET_CODE rc = ddwaf_context_eval(ctx, &args, alloc, &result, timeout);
-ddwaf_object_destroy(&result, alloc);
-ddwaf_context_destroy(ctx);
-ddwaf_destroy(handle);
-```
-
-Key points:
-
-- The request data passed to `ddwaf_context_eval` must remain valid until the context (or any subcontext) is destroyed because libddwaf can hold references to the objects you insert.
-- You can create lightweight clones with `ddwaf_subcontext_init` when you need concurrent evaluations that share the same persistent state (see `tests/integration/context/test.cpp:508` for usage). Subcontexts reuse the allocator you gave to the parent.
+ddwaf_object ruleset = ...;
+ddwaf_config config = ...;
 
-## 3. Manage allocators explicitly
-
-Memory ownership is now routed through `ddwaf_allocator`. Every object that can allocate memory has an overload that accepts an allocator, and any destruction (objects, contexts, results) must receive the same allocator.
-
-- The default allocator is returned by `ddwaf_get_default_allocator()` and is used throughout the integration tests (`tests/integration/context/test.cpp`). The pointer is owned by libddwaf; do not pass it to `ddwaf_allocator_destroy`.
-- Pool and monotonic allocators (`ddwaf_{synchronized,unsynchronized}_pool_allocator_init`, `ddwaf_monotonic_allocator_init`) reduce per-request allocations (`tests/integration/interface/allocator/test.cpp:16`).
-- Provide your own hooks with `ddwaf_user_allocator_init`. The snippet below is adapted from `tests/integration/interface/allocator/test.cpp:539`:
+ddwaf_object diagnostics;
+ddwaf_handle handle = ddwaf_init(&ruleset, &config, &diagnostics);
+```
 
+**v2.x:**
 ```c
-static void *counting_alloc(void *udata, size_t bytes, size_t alignment) { /* ... */ }
-static void counting_free(void *udata, void *p, size_t bytes, size_t alignment) { /* ... */ }
+ddwaf_object ruleset = ...;
 
-counting_allocator state{};
-ddwaf_allocator alloc =
-    ddwaf_user_allocator_init(&counting_alloc, &counting_free, &state, /*udata_dtor=*/nullptr);
-
-ddwaf_context ctx = ddwaf_context_init(handle, alloc);
-/* ... build inputs and call ddwaf_context_eval ... */
-ddwaf_context_destroy(ctx);
-ddwaf_allocator_destroy(alloc);
+ddwaf_object diagnostics;
+ddwaf_handle handle = ddwaf_init(&ruleset, &diagnostics);
 ```
 
-Whenever you clone or destroy `ddwaf_object` instances (for instance via `ddwaf_object_clone`, `ddwaf_object_destroy`), pass the allocator that owns their memory.
-
-## 4. Refactor `ddwaf_object` helpers
-
-`ddwaf_object` changed from macro-based initialisers to allocator-aware setters and insertion helpers. The example below mirrors the change implemented in `tests/integration/context/test.cpp`.
-
+When instantiating through the builder, the deprecation of `ddwaf_config` only affects `ddwaf_builder_init`:
+**v1.x:**
 ```c
-/* libddwaf 1.30.x */
-ddwaf_object root = DDWAF_OBJECT_MAP;
-ddwaf_object tmp, nested = DDWAF_OBJECT_MAP;
-ddwaf_object_map_add(&nested, "key", ddwaf_object_string(&tmp, "rule3"));
-ddwaf_object_map_add(&root, "value2", &nested);
+ddwaf_config config = ...;
+ddwaf_builder builder = ddwaf_builder_init(&config);
 ```
 
+**v2.x:**
 ```c
-/* libddwaf 2.0.0 */
-ddwaf_object root;
-ddwaf_object_set_map(&root, 1, alloc);
-ddwaf_object *nested = ddwaf_object_insert_key(&root, "value2", sizeof("value2") - 1, alloc);
-ddwaf_object_set_map(nested, 1, alloc);
-ddwaf_object_set_string(
-    ddwaf_object_insert_key(nested, "key", sizeof("key") - 1, alloc),
-    "rule3", sizeof("rule3") - 1, alloc);
+ddwaf_builder builder = ddwaf_builder_init();
 ```
 
-Additional tips:
-
-- Choose the string setter that matches your ownership model:
-  - `ddwaf_object_set_string` copies the buffer.
-  - `ddwaf_object_set_string_literal` marks the storage as caller-owned and never frees it.
-  - `ddwaf_object_set_string_nocopy` keeps a pointer you manage.
-- Arrays and maps are sized up-front (`ddwaf_object_set_array`, `ddwaf_object_set_map`) and filled with `ddwaf_object_insert` / `ddwaf_object_insert_key*`.
-- Use the new getters (`ddwaf_object_get_type`, `ddwaf_object_get_size`, `ddwaf_object_get_string`, `ddwaf_object_get_bool`, etc.) together with `ddwaf_object_at_key` / `ddwaf_object_at_value` for iteration.
-
-## 5. Builder workflow updates
+## 2. Context Lifecycle
 
-`ddwaf_builder_init` no longer accepts a `ddwaf_config*`. Instantiate it without arguments and pass configurations that already carry optional obfuscator settings. Inputs still need to be destroyed with `ddwaf_object_destroy`. The integration test at `tests/integration/interface/builder/test.cpp` reflects the new pattern:
 
-```c
-ddwaf_builder builder = ddwaf_builder_init();
-ddwaf_object config = yaml_to_object<ddwaf_object>(...);
-
-ddwaf_builder_add_or_update_config(builder, "default", sizeof("default") - 1, &config, nullptr);
-ddwaf_object_destroy(&config, alloc);
-
-ddwaf_handle handle = ddwaf_builder_build_instance(builder);
-/* ... */
-ddwaf_builder_destroy(builder);
-```
+### Subcontexts
+## 3. Object Creation
 
-## 6. Quick reference for renamed helpers
-
-- Initialisation and teardown:
-  - `ddwaf_run` → `ddwaf_context_eval`
-  - `ddwaf_object_free` → `ddwaf_object_destroy`
-  - `ddwaf_context_init(handle)` → `ddwaf_context_init(handle, alloc)`
-- Primitive setters:
-  - `ddwaf_object_invalid/null` → `ddwaf_object_set_invalid/null`
-  - `ddwaf_object_string*` → `ddwaf_object_set_string` / `*_literal` / `*_nocopy`
-  - `ddwaf_object_unsigned/signed/float/bool` → `ddwaf_object_set_unsigned/signed/float/bool`
-- Containers:
-  - `ddwaf_object_array` / `ddwaf_object_map` → `ddwaf_object_set_array` / `ddwaf_object_set_map`
-  - `ddwaf_object_array_add` → `ddwaf_object_insert`
-  - `ddwaf_object_map_add*` → `ddwaf_object_insert_key`, `_insert_literal_key`, `_insert_key_nocopy`
-- Accessors:
-  - `ddwaf_object_type` / `size` / `length` → `ddwaf_object_get_type` / `get_size` / `get_length`
-  - `ddwaf_object_get_key` / `get_index` → `ddwaf_object_at_key` / `ddwaf_object_at_value`
-
-## 7. Reference examples in this repository
-
-- `tests/integration/context/test.cpp` showcases context creation, evaluation, subcontexts and result handling with the new API.
-- `tests/integration/interface/waf/test.cpp` exercises error handling, subcontexts and edge cases around `ddwaf_context_eval`.
-- `tests/integration/interface/allocator/test.cpp` demonstrates the allocator factories and how to integrate a custom allocator.
-- `tests/integration/interface/builder/test.cpp` covers the builder flow without `ddwaf_config`.
-
-## Migration checklist
-
-- [ ] Drop any attempt to configure evaluation limits; they are no longer exposed.
-- [ ] If you rely on custom obfuscator patterns, embed them in the configurations you load.
-- [ ] Update every `ddwaf_context_init` call to pass an allocator and replace `ddwaf_run` with `ddwaf_context_eval`.
-- [ ] Swap out deprecated `ddwaf_object_*` constructors for the allocator-aware setters and ensure destruction happens through `ddwaf_object_destroy`.
-- [ ] Review result-handling code for the new getter helpers and the unified request payload.
-- [ ] If you provide custom allocators, migrate the hook to `ddwaf_user_allocator_init` and pair it with `ddwaf_allocator_destroy`.
-- [ ] Drop the `ddwaf_config` argument when using the builder and ensure configurations are destroyed with the correct allocator.

From fc2300d86d23f689d3c29f6ecde608c80eaa6bb9 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Fri, 12 Dec 2025 17:04:49 +0000
Subject: [PATCH 10/32] Update UPGRADING-v2.0.md

---
 docs/upgrading/UPGRADING-v2.0.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/upgrading/UPGRADING-v2.0.md b/docs/upgrading/UPGRADING-v2.0.md
index 201441798..782d0714a 100644
--- a/docs/upgrading/UPGRADING-v2.0.md
+++ b/docs/upgrading/UPGRADING-v2.0.md
@@ -23,7 +23,7 @@ Since the use of allocators is now required on many of the API functions, the mi
 
 See the [allocators document](../allocators.md) for more information on the different types of allocators available.
 
-## 1. WAF instantiation: removal of `ddwaf_config`
+## 1. WAF instantiation: Removal of `ddwaf_config`
 
 The main changes pertaining to WAF initialisation is the removal of `ddwaf_config`, as the evaluation limits have been entirely removed in favour of user-controlled truncation and the free function is no longer required due to the explicit memory ownership defined through allocators. As a consequence, instantiation through `ddwaf_init` has changed as follows:
 
@@ -56,9 +56,11 @@ ddwaf_builder builder = ddwaf_builder_init(&config);
 ddwaf_builder builder = ddwaf_builder_init();
 ```
 
-## 2. Context Lifecycle
+## 2. WAF Context: Input & Output Allocators and Removal of Ephemerals
 
 
-### Subcontexts
-## 3. Object Creation
+### 3. WAF Subcontext: Replacement of Ephemerals
+
+## 3. Object Creation: New API & Allocator support
+
 

From 272c523b9ebeeebd54b98a108d9d0294893fae6c Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Fri, 12 Dec 2025 17:08:30 +0000
Subject: [PATCH 11/32] Add allocators.md, fix headers

---
 docs/allocators.md               | 12 ++++++++++++
 docs/upgrading/UPGRADING-v2.0.md |  4 ++--
 2 files changed, 14 insertions(+), 2 deletions(-)
 create mode 100644 docs/allocators.md

diff --git a/docs/allocators.md b/docs/allocators.md
new file mode 100644
index 000000000..4d9444429
--- /dev/null
+++ b/docs/allocators.md
@@ -0,0 +1,12 @@
+# Allocators
+
+The ownership of memory crossing the API boundary was one of the pain points of libddwaf v1. To fix this, v2 introduces allocators, which can be used to define the explicit ownership of the allocated memory. 
+
+Four different allocator options are provided:
+- **Default allocator**: obtained through `ddwaf_get_default_allocator`, this is the default allocator used by the standard library and it's typically relies directly on `new` / `delete`. When unsure, this is the recommended allocator. The underlying memory resource is [std::pmr::new_delete_resource](https://en.cppreference.com/w/cpp/memory/new_delete_resource.html).
+- **Unsynchronized pool allocator**: obtained through `ddwaf_unsynchronized_pool_allocator_init`, this is a thread-unsafe pool allocator. The underlying memory resource is [std::pmr::unsynchronized_pool_resource](https://en.cppreference.com/w/cpp/memory/unsynchronized_pool_resource.html).
+- **Synchronized pool allocator**: obtained through `ddwaf_synchronized_pool_allocator_init`, this is a thread-safe version of the previous pool allocator. The underlying memory resource is [std::pmr::synchronized_pool_resource](https://en.cppreference.com/w/cpp/memory/synchronized_pool_resource.html).
+- **Monotonic allocator**: obtained through `ddwaf_monotonic_allocator_init`, this is a special allocator which releases all of the allocated memory once destroyed. This allocator is not recommended as a general purpose allocator and should be used with care. The underlying memory resource is [std::pmr::monotonic_buffer_resource](https://en.cppreference.com/w/cpp/memory/monotonic_buffer_resource.html).
+
+
+Allocators are destroyed using `ddwaf_allocator_destroy`, note that for safety, this must only be done once all of the allocated memory has been freed. Additionally, the default allocator need not be destroyed, as destruction results in a no-op.
diff --git a/docs/upgrading/UPGRADING-v2.0.md b/docs/upgrading/UPGRADING-v2.0.md
index 782d0714a..945ce51ea 100644
--- a/docs/upgrading/UPGRADING-v2.0.md
+++ b/docs/upgrading/UPGRADING-v2.0.md
@@ -59,8 +59,8 @@ ddwaf_builder builder = ddwaf_builder_init();
 ## 2. WAF Context: Input & Output Allocators and Removal of Ephemerals
 
 
-### 3. WAF Subcontext: Replacement of Ephemerals
+## 3. WAF Subcontext: Replacement of Ephemerals
 
-## 3. Object Creation: New API & Allocator support
+## 4. Object Creation: New API & Allocator support
 
 

From 8e9f30c819c73f72625b413d4642aa1fb02cb015 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Fri, 12 Dec 2025 17:39:41 +0000
Subject: [PATCH 12/32] Update allocators.md

---
 docs/allocators.md | 65 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 62 insertions(+), 3 deletions(-)

diff --git a/docs/allocators.md b/docs/allocators.md
index 4d9444429..5c3c17a38 100644
--- a/docs/allocators.md
+++ b/docs/allocators.md
@@ -1,12 +1,71 @@
 # Allocators
 
-The ownership of memory crossing the API boundary was one of the pain points of libddwaf v1. To fix this, v2 introduces allocators, which can be used to define the explicit ownership of the allocated memory. 
+As the name suggests, allocators are used for the purpose of memory management, providing functionality for allocating and deallocating memory as needed. Different allocators may follow specific memory management strategies to reduce the amount of memory that needs to be requested to the global allocators or to minimise the cost of allocation or deallocation. 
 
-Four different allocator options are provided:
+The allocators provided by `libddwaf` are, under the hood, C++ memory resources, therefore the four different allocator options are provided:
 - **Default allocator**: obtained through `ddwaf_get_default_allocator`, this is the default allocator used by the standard library and it's typically relies directly on `new` / `delete`. When unsure, this is the recommended allocator. The underlying memory resource is [std::pmr::new_delete_resource](https://en.cppreference.com/w/cpp/memory/new_delete_resource.html).
 - **Unsynchronized pool allocator**: obtained through `ddwaf_unsynchronized_pool_allocator_init`, this is a thread-unsafe pool allocator. The underlying memory resource is [std::pmr::unsynchronized_pool_resource](https://en.cppreference.com/w/cpp/memory/unsynchronized_pool_resource.html).
 - **Synchronized pool allocator**: obtained through `ddwaf_synchronized_pool_allocator_init`, this is a thread-safe version of the previous pool allocator. The underlying memory resource is [std::pmr::synchronized_pool_resource](https://en.cppreference.com/w/cpp/memory/synchronized_pool_resource.html).
 - **Monotonic allocator**: obtained through `ddwaf_monotonic_allocator_init`, this is a special allocator which releases all of the allocated memory once destroyed. This allocator is not recommended as a general purpose allocator and should be used with care. The underlying memory resource is [std::pmr::monotonic_buffer_resource](https://en.cppreference.com/w/cpp/memory/monotonic_buffer_resource.html).
 
-
 Allocators are destroyed using `ddwaf_allocator_destroy`, note that for safety, this must only be done once all of the allocated memory has been freed. Additionally, the default allocator need not be destroyed, as destruction results in a no-op.
+
+## User Allocators
+
+In addition to the available allocators, custom memory management strategies are supported through the use of user allocators. A user allocator has four main components:
+- A function to allocate memory (alloc) based on the required size and an alignment.
+- A function to deallocate memory (dealloc) based on the allocated size and alignment.
+- Optional user data, which may typically correspond to the required structures used to store and manage the allocated memory.
+- An optional free function for user data.
+
+As an example, consider the case of a counting allocator, using the default allocator as its upstream allocator. This may be defined through the following structure, which corresponds to the aforementioned user data.
+
+```c
+struct counting_allocator {
+    unsigned alloc_count{0};
+    unsigned free_count{0};
+    ddwaf_allocator upstream{ddwaf_get_default_allocator()};
+};
+```
+
+The allocation function can then be the following:
+
+```c
+void *counting_allocator_alloc(void *udata, std::size_t bytes, std::size_t alignment)
+{
+    counting_allocator *alloc = (counting_allocator *)udata;
+    alloc->alloc_count++;
+    return ddwaf_allocator_alloc(alloc->upstream, bytes, alignment);
+}
+```
+
+Where the user data is provided as the first field, followed by the number of bytes (size) and their expected alignment. The function increases the allocation count and calls the upstream allocator.
+
+The deallocation function can then be the following:
+
+```c
+void counting_allocator_free(void *udata, void *p, std::size_t bytes, std::size_t alignment)
+{
+    counting_allocator *alloc = (counting_allocator *)udata;
+    alloc->free_count++;
+    ddwaf_allocator_free(alloc->upstream, p, bytes, alignment);
+}
+```
+
+Which requires the user data as the first field, followed by the pointer to deallocate and both the number of bytes and alignment.
+
+This particular allocator doesn't allocate memory for its own use, therefore a free function is not needed, however for illustration purposes, the following would be suitable:
+
+```c
+void counting_allocator_udata_free(void *udata)
+{
+  // noop
+}
+```
+
+Finally, the user allocator to provide to libddwaf can be instantiated as follows:
+
+```c
+counting_allocator udata;
+ddwaf_allocator alloc = ddwaf_user_allocator_init(&counting_allocator_alloc, &counting_allocator_free, &udata, &counting_allocator_udata_free);
+```

From 8b66fb5b0db7a5a12c1fb893eefffb3cf00b4294 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Mon, 19 Jan 2026 22:08:57 +0000
Subject: [PATCH 13/32] Claude/Codex assisted upgrading guide changes

---
 docs/upgrading/UPGRADING-v2.0.md | 486 +++++++++++++++++++++++++++++++
 1 file changed, 486 insertions(+)

diff --git a/docs/upgrading/UPGRADING-v2.0.md b/docs/upgrading/UPGRADING-v2.0.md
index 945ce51ea..f72b63c93 100644
--- a/docs/upgrading/UPGRADING-v2.0.md
+++ b/docs/upgrading/UPGRADING-v2.0.md
@@ -11,16 +11,28 @@ The C API in libddwaf v2 has experienced a large number of changes, primarily ar
 - Object creation and access functions have been changed significantly, primarily to avoid the need for intermediate objects.
 - `ddwaf_run` has been renamed to `ddwaf_context_eval`.
 - Subcontexts have been introduced to replace ephemerals, their lifecycle and use is equivalent to that of the context.
+- `ddwaf_object_free` and `ddwaf_result_free` are replaced by `ddwaf_object_destroy`, which requires the allocator used for the object's allocations.
 - `ddwaf_config` has been removed:
   - Evaluation limits have been entirely removed, the caller must now enforce any relevant limits during serialisation.
   - Obfuscator regexes must now be provided through configuration: `{obfuscator: {key_regex: <value>, value_regex: <value>}}`.
   - The free function is no longer needed due to the introduction of allocators.
 
+## Checklist for bindings maintainers
+
+- Replace `ddwaf_init(ruleset, config, diagnostics)` with `ddwaf_init(ruleset, diagnostics)` and destroy `diagnostics` with the default allocator.
+- Pass an output allocator to `ddwaf_context_init()` and destroy results with `ddwaf_object_destroy(result, output_alloc)`.
+- Update `ddwaf_run()` usages to `ddwaf_context_eval()` and consolidate persistent/ephemeral data into a single `data` argument.
+- If you relied on ephemerals, introduce subcontexts and destroy them with `ddwaf_subcontext_destroy()`.
+- Replace `ddwaf_object_free`/`ddwaf_result_free` with `ddwaf_object_destroy` and ensure the allocator used for allocation is available at destruction time.
+- Update object builders to `ddwaf_object_set_*` plus `ddwaf_object_insert_*` APIs; prefer literal/no-copy variants only when ownership rules are clear.
+
 ## Note on Allocators
 The ownership of any allocated memory crossing the API boundary was one of the pain points of libddwaf v1. To fix this, v2 introduces allocators, which can be used to define the explicit ownership of the allocated memory.
 
 Since the use of allocators is now required on many of the API functions, the migration examples will use the default allocator and will also include allocator destruction for illustrative purposes, as the destruction of the default allocator is a no-op.
 
+The allocator API now includes default, pool, monotonic, and user-defined allocators via `ddwaf_*_allocator_init()` plus `ddwaf_allocator_destroy()` for cleanup. The default allocator is process-wide and `ddwaf_allocator_destroy()` is a no-op for it.
+
 See the [allocators document](../allocators.md) for more information on the different types of allocators available.
 
 ## 1. WAF instantiation: Removal of `ddwaf_config`
@@ -43,6 +55,7 @@ ddwaf_object ruleset = ...;
 ddwaf_object diagnostics;
 ddwaf_handle handle = ddwaf_init(&ruleset, &diagnostics);
 ```
+The `diagnostics` object is allocated with the default allocator and must be destroyed with `ddwaf_object_destroy(&diagnostics, ddwaf_get_default_allocator())`.
 
 When instantiating through the builder, the deprecation of `ddwaf_config` only affects `ddwaf_builder_init`:
 **v1.x:**
@@ -58,9 +71,482 @@ ddwaf_builder builder = ddwaf_builder_init();
 
 ## 2. WAF Context: Input & Output Allocators and Removal of Ephemerals
 
+The WAF context lifecycle has changed significantly in v2 with the introduction of allocators and the consolidation of persistent and ephemeral data into a single parameter. In v1.x, `ddwaf_run` accepted separate persistent and ephemeral data parameters, while v2.x uses `ddwaf_context_eval` with a unified data parameter.
+
+### Context Initialization
+
+**v1.x:**
+```c
+ddwaf_handle handle = ...;
+
+// Create context without allocator
+ddwaf_context context = ddwaf_context_init(handle);
+```
+
+**v2.x:**
+```c
+ddwaf_handle handle = ...;
+
+// Get allocator for output objects (result, diagnostics, etc.)
+ddwaf_allocator output_alloc = ddwaf_get_default_allocator();
+
+// Create context with output allocator
+ddwaf_context context = ddwaf_context_init(handle, output_alloc);
+```
+
+The output allocator (`output_alloc`) is used by the WAF to allocate memory for the result object returned by `ddwaf_context_eval`. This allocator must remain valid for the lifetime of the context.
+
+### Context Evaluation
+
+**v1.x:**
+```c
+ddwaf_object persistent_data = ...;
+ddwaf_object ephemeral_data = ...;
+ddwaf_result result;
+
+// Separate persistent and ephemeral parameters
+DDWAF_RET_CODE code = ddwaf_run(context, &persistent_data, &ephemeral_data, &result, timeout);
+
+// Process result
+if (code == DDWAF_MATCH) {
+    // Handle match...
+}
+
+// Free result (v1 used internal memory management)
+ddwaf_result_free(&result);
+```
+
+**v2.x:**
+```c
+ddwaf_allocator input_alloc = ddwaf_get_default_allocator();
+
+ddwaf_object data = ...;  // All data in single parameter
+ddwaf_object result;
+
+// Single data parameter, with allocator for input data
+DDWAF_RET_CODE code = ddwaf_context_eval(context, &data, input_alloc, &result, timeout);
+
+// Process result
+if (code == DDWAF_MATCH) {
+    // Handle match...
+}
+
+// Destroy result using the output allocator from ddwaf_context_init
+ddwaf_object_destroy(&result, output_alloc);
+```
+
+### Key Changes
+
+1. **Allocators Required**: Both context initialization and evaluation now require allocators
+   - Output allocator: Passed to `ddwaf_context_init()`, used for result objects
+   - Input allocator: Passed to `ddwaf_context_eval()`, used to manage input data lifecycle
+   - If the input allocator is NULL, libddwaf will not free the input data; the caller must keep it alive until the context or subcontext is destroyed.
+
+2. **Unified Data Parameter**: The `persistent_data` and `ephemeral_data` split has been removed. All data is passed through the single `data` parameter in `ddwaf_context_eval()`.
+
+3. **Persistent Data Accumulation**: Data passed to `ddwaf_context_eval()` is stored in the context and persists across multiple evaluations. To override a previously provided address, simply pass new data for the same address in a subsequent call.
+
+4. **Result Object Management**: The result object is now a `ddwaf_object` instead of `ddwaf_result`, and must be destroyed with `ddwaf_object_destroy()` using the output allocator.
+
+### Multiple Evaluations Example
+
+**v1.x:**
+```c
+ddwaf_context context = ddwaf_context_init(handle);
+
+// First evaluation with persistent data
+ddwaf_object persistent = ...;
+ddwaf_result result1;
+ddwaf_run(context, &persistent, NULL, &result1, timeout);
+ddwaf_result_free(&result1);
+
+// Second evaluation - persistent data still available
+ddwaf_object more_data = ...;
+ddwaf_result result2;
+ddwaf_run(context, &more_data, NULL, &result2, timeout);
+ddwaf_result_free(&result2);
+```
+
+**v2.x:**
+```c
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+ddwaf_context context = ddwaf_context_init(handle, alloc);
+
+// First evaluation
+ddwaf_object data1 = ...;
+ddwaf_object result1;
+ddwaf_context_eval(context, &data1, alloc, &result1, timeout);
+ddwaf_object_destroy(&result1, alloc);
+
+// Second evaluation - data1 persists automatically
+ddwaf_object data2 = ...;
+ddwaf_object result2;
+ddwaf_context_eval(context, &data2, alloc, &result2, timeout);
+ddwaf_object_destroy(&result2, alloc);
+
+// Both data1 and data2 are available for evaluation
+```
 
 ## 3. WAF Subcontext: Replacement of Ephemerals
 
+Subcontexts are the v2 replacement for ephemeral data. In v1.x, ephemeral data was passed separately to `ddwaf_run()` and was not stored in the context. In v2.x, subcontexts inherit all persistent data from their parent context but can be evaluated with temporary data that doesn't persist beyond the subcontext's lifetime.
+
+### Migration Pattern
+
+**v1.x:**
+```c
+ddwaf_context context = ddwaf_context_init(handle);
+
+// Store persistent data
+ddwaf_object persistent = ...;
+ddwaf_result result1;
+ddwaf_run(context, &persistent, NULL, &result1, timeout);
+ddwaf_result_free(&result1);
+
+// Evaluate with ephemeral data
+ddwaf_object ephemeral = ...;
+ddwaf_result result2;
+ddwaf_run(context, NULL, &ephemeral, &result2, timeout);
+ddwaf_result_free(&result2);
+
+// Ephemeral data is NOT stored, persistent data remains
+```
+
+**v2.x:**
+```c
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+ddwaf_context context = ddwaf_context_init(handle, alloc);
+
+// Store persistent data in context
+ddwaf_object persistent = ...;
+ddwaf_object result1;
+ddwaf_context_eval(context, &persistent, alloc, &result1, timeout);
+ddwaf_object_destroy(&result1, alloc);
+
+// Create subcontext for ephemeral evaluation
+ddwaf_subcontext subctx = ddwaf_subcontext_init(context);
+
+// Evaluate with ephemeral data (inherits persistent data from parent)
+ddwaf_object ephemeral = ...;
+ddwaf_object result2;
+ddwaf_subcontext_eval(subctx, &ephemeral, alloc, &result2, timeout);
+ddwaf_object_destroy(&result2, alloc);
+
+// Clean up subcontext
+ddwaf_subcontext_destroy(subctx);
+
+// Ephemeral data is NOT stored in context, only persistent data remains
+```
+
+### Subcontext Lifecycle
+
+The subcontext follows the same lifecycle pattern as the context:
+
+1. **Initialize**: `ddwaf_subcontext_init(context)` - Creates a subcontext from parent
+2. **Evaluate**: `ddwaf_subcontext_eval(subctx, data, alloc, result, timeout)` - Evaluates with ephemeral data
+3. **Destroy**: `ddwaf_subcontext_destroy(subctx)` - Cleans up subcontext
+
+### Multiple Subcontexts
+
+You can create multiple subcontexts from the same parent context, each with different ephemeral data:
+
+**v2.x:**
+```c
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+ddwaf_context context = ddwaf_context_init(handle, alloc);
+
+// Store persistent data
+ddwaf_object persistent = ...;
+ddwaf_context_eval(context, &persistent, alloc, NULL, timeout);
+
+// First subcontext with ephemeral data
+ddwaf_subcontext subctx1 = ddwaf_subcontext_init(context);
+ddwaf_object ephemeral1 = ...;
+ddwaf_object result1;
+ddwaf_subcontext_eval(subctx1, &ephemeral1, alloc, &result1, timeout);
+ddwaf_object_destroy(&result1, alloc);
+ddwaf_subcontext_destroy(subctx1);
+
+// Second subcontext with different ephemeral data
+ddwaf_subcontext subctx2 = ddwaf_subcontext_init(context);
+ddwaf_object ephemeral2 = ...;
+ddwaf_object result2;
+ddwaf_subcontext_eval(subctx2, &ephemeral2, alloc, &result2, timeout);
+ddwaf_object_destroy(&result2, alloc);
+ddwaf_subcontext_destroy(subctx2);
+
+// Both subcontexts inherited persistent data, but had independent ephemeral data
+```
+
+### Key Points
+
+1. **Inheritance**: Subcontexts inherit all persistent data from their parent context at creation time
+2. **Ephemeral Data**: Data passed to `ddwaf_subcontext_eval()` is temporary and does not persist to the parent context
+3. **Independence**: Multiple subcontexts can coexist, each with different ephemeral data
+4. **Allocator Rules**: The input allocator controls how subcontext data is freed; if NULL, the caller must keep the data alive until the subcontext is destroyed
+5. **Lifecycle**: Subcontexts must be destroyed with `ddwaf_subcontext_destroy()` before or when destroying the parent context
+6. **Use Case**: Use subcontexts when you need to evaluate rules with temporary data (e.g., per-request data that shouldn't persist across multiple requests in the same session)
+
 ## 4. Object Creation: New API & Allocator support
 
+The object creation API has changed extensively in v2 to support allocators and reduce memory overhead. All object creation functions now use the `ddwaf_object_set_*` naming pattern, and most require an allocator parameter.
+
+### String Creation
+
+**v1.x:**
+```c
+// Create string object (library allocates and copies)
+ddwaf_object obj;
+ddwaf_object_stringl(&obj, "hello world", 11);
+
+// Free object
+ddwaf_object_free(&obj);
+```
+
+**v2.x:**
+```c
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+
+// Create string object with allocator
+ddwaf_object obj;
+ddwaf_object_set_string(&obj, "hello world", 11, alloc);
+
+// Destroy object with allocator
+ddwaf_object_destroy(&obj, alloc);
+```
+
+### String Literals (Read-Only Strings)
+
+v2 introduces a new literal string type for read-only strings, which avoids allocation:
+
+**v2.x:**
+```c
+ddwaf_object obj;
+
+// String literal - no allocation, no copy
+ddwaf_object_set_string_literal(&obj, "constant string", 15);
+
+// Must still call destroy, but allocator can be any valid allocator since no memory was allocated
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+ddwaf_object_destroy(&obj, alloc);
+```
+
+**Note**: Small strings (14 bytes or less) are automatically stored inline within the object itself without additional allocation, regardless of whether you use `ddwaf_object_set_string()` or `ddwaf_object_set_string_literal()`.
+
+**No-copy strings**: Use `ddwaf_object_set_string_nocopy()` when the string buffer is already allocated with the same allocator you will pass to `ddwaf_object_destroy()`. This avoids a copy but requires the buffer to remain valid for the lifetime of the object.
+
+### Numeric Types
+
+**v1.x:**
+```c
+ddwaf_object obj;
+ddwaf_object_unsigned(&obj, 42);
+```
+
+**v2.x:**
+```c
+ddwaf_object obj;
+ddwaf_object_set_unsigned(&obj, 42);  // No allocator needed for numeric types
+```
+
+The same pattern applies to other numeric types:
+- `ddwaf_object_signed()` → `ddwaf_object_set_signed()`
+- `ddwaf_object_bool()` → `ddwaf_object_set_bool()`
+- `ddwaf_object_float()` → `ddwaf_object_set_float()`
+
+### Map Creation and Insertion
+
+The map insertion API has changed to return a pointer to the inserted value, eliminating the need for intermediate objects.
+
+**v1.x:**
+```c
+ddwaf_object map;
+ddwaf_object_map(&map);
+
+// Create value object, then add to map
+ddwaf_object value;
+ddwaf_object_string(&value, "username");
+ddwaf_object_map_addl(&map, "user", 4, &value);
+
+// Create another value and add
+ddwaf_object value2;
+ddwaf_object_unsigned(&value2, 12345);
+ddwaf_object_map_addl(&map, "user_id", 7, &value2);
+
+ddwaf_object_free(&map);
+```
+
+**v2.x:**
+```c
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+
+ddwaf_object map;
+ddwaf_object_set_map(&map, 2, alloc);  // Initialize with capacity
+
+// Insert key and get pointer to value, then set value directly
+ddwaf_object_set_string(
+    ddwaf_object_insert_key(&map, "user", 4, alloc),
+    "username", 8, alloc);
+
+// Insert another key-value pair
+ddwaf_object_set_unsigned(
+    ddwaf_object_insert_key(&map, "user_id", 7, alloc),
+    12345);
+
+ddwaf_object_destroy(&map, alloc);
+```
+
+### Array Creation and Insertion
+
+**v1.x:**
+```c
+ddwaf_object array;
+ddwaf_object_array(&array);
+
+// Create value objects and add to array
+ddwaf_object elem1;
+ddwaf_object_string(&elem1, "first");
+ddwaf_object_array_add(&array, &elem1);
+
+ddwaf_object elem2;
+ddwaf_object_string(&elem2, "second");
+ddwaf_object_array_add(&array, &elem2);
+
+ddwaf_object_free(&array);
+```
+
+**v2.x:**
+```c
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+
+ddwaf_object array;
+ddwaf_object_set_array(&array, 2, alloc);  // Initialize with capacity
+
+// Insert and set value in one step
+ddwaf_object_set_string(
+    ddwaf_object_insert(&array, alloc),
+    "first", 5, alloc);
+
+ddwaf_object_set_string(
+    ddwaf_object_insert(&array, alloc),
+    "second", 6, alloc);
+
+ddwaf_object_destroy(&array, alloc);
+```
+
+### Insertion Variants
+
+v2 provides multiple insertion functions for different use cases:
+
+```c
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+ddwaf_object map;
+ddwaf_object_set_map(&map, 3, alloc);
+
+// Standard: copies the key string
+ddwaf_object *val1 = ddwaf_object_insert_key(&map, "key1", 4, alloc);
+ddwaf_object_set_string(val1, "value1", 6, alloc);
+
+// Literal: key is read-only, not copied
+ddwaf_object *val2 = ddwaf_object_insert_literal_key(&map, "key2", 4, alloc);
+ddwaf_object_set_string(val2, "value2", 6, alloc);
+
+// No-copy: key is externally managed (must be allocated with same allocator)
+char *external_key = (char*)ddwaf_allocator_alloc(alloc, 5, 1);
+memcpy(external_key, "key3", 5);
+ddwaf_object *val3 = ddwaf_object_insert_key_nocopy(&map, external_key, 4, alloc);
+ddwaf_object_set_string(val3, "value3", 6, alloc);
+
+ddwaf_object_destroy(&map, alloc);
+```
+
+### Getter Functions
+
+Object getter functions have been renamed for consistency:
+
+**v1.x:**
+```c
+DDWAF_OBJ_TYPE type = ddwaf_object_type(&obj);
+const char *str = ddwaf_object_get_string(&obj, &length);
+uint64_t num = ddwaf_object_get_unsigned(&obj);
+```
+
+**v2.x:**
+```c
+DDWAF_OBJ_TYPE type = ddwaf_object_get_type(&obj);  // Renamed from ddwaf_object_type
+const char *str = ddwaf_object_get_string(&obj, &length);  // Unchanged
+uint64_t num = ddwaf_object_get_unsigned(&obj);  // Unchanged
+```
+
+### JSON Parsing
+
+If you use `ddwaf_object_from_json()`, it now takes an allocator and the resulting object must be destroyed with the same allocator:
+
+**v2.x:**
+```c
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+ddwaf_object obj;
+
+if (ddwaf_object_from_json(&obj, json, json_len, alloc)) {
+    // use obj
+    ddwaf_object_destroy(&obj, alloc);
+}
+```
+
+### Complete Example: Building Request Data
+
+**v1.x:**
+```c
+// Build a request data structure
+ddwaf_object root;
+ddwaf_object_map(&root);
+
+ddwaf_object headers;
+ddwaf_object_map(&headers);
+ddwaf_object header_val;
+ddwaf_object_string(&header_val, "application/json");
+ddwaf_object_map_addl(&headers, "content-type", 12, &header_val);
+ddwaf_object_map_addl(&root, "headers", 7, &headers);
+
+ddwaf_object method;
+ddwaf_object_string(&method, "POST");
+ddwaf_object_map_addl(&root, "method", 6, &method);
+
+ddwaf_object_free(&root);
+```
+
+**v2.x:**
+```c
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+
+// Build a request data structure
+ddwaf_object root;
+ddwaf_object_set_map(&root, 2, alloc);
+
+// Create nested headers map
+ddwaf_object *headers = ddwaf_object_insert_key(&root, "headers", 7, alloc);
+ddwaf_object_set_map(headers, 1, alloc);
+ddwaf_object_set_string(
+    ddwaf_object_insert_key(headers, "content-type", 12, alloc),
+    "application/json", 16, alloc);
+
+// Add method
+ddwaf_object_set_string(
+    ddwaf_object_insert_key(&root, "method", 6, alloc),
+    "POST", 4, alloc);
+
+ddwaf_object_destroy(&root, alloc);
+```
+
+### Key Changes Summary
 
+1. **Allocator Required**: Most creation functions now require an allocator (except numeric types and null/invalid)
+2. **Naming Convention**: `ddwaf_object_*` → `ddwaf_object_set_*` for creation functions
+3. **Insertion Returns Pointer**: `ddwaf_object_insert()` and `ddwaf_object_insert_key()` return a pointer to the inserted object, allowing direct value assignment
+4. **String Variants**: Three string types available:
+   - `ddwaf_object_set_string()`: Allocates and copies (regular string)
+   - `ddwaf_object_set_string_literal()`: Read-only, no allocation (literal string)
+   - Small strings (≤14 bytes): Automatically stored inline
+5. **No-copy Variants**: `ddwaf_object_set_string_nocopy()` and `ddwaf_object_insert_key_nocopy()` avoid copies but require allocator-managed storage
+6. **Destruction**: `ddwaf_object_free(&obj)` → `ddwaf_object_destroy(&obj, alloc)`
+7. **Literal Keys**: Use `ddwaf_object_insert_literal_key()` for constant string keys to avoid allocation

From 117c081f695fb5e9b39d29a1fec5801c058f8c78 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Tue, 20 Jan 2026 17:25:38 +0000
Subject: [PATCH 14/32] Human-powered fixes and improvements

---
 docs/upgrading/UPGRADING-v2.0.md | 54 +++++++++++---------------------
 1 file changed, 18 insertions(+), 36 deletions(-)

diff --git a/docs/upgrading/UPGRADING-v2.0.md b/docs/upgrading/UPGRADING-v2.0.md
index f72b63c93..5db6a7132 100644
--- a/docs/upgrading/UPGRADING-v2.0.md
+++ b/docs/upgrading/UPGRADING-v2.0.md
@@ -8,36 +8,24 @@ The C API in libddwaf v2 has experienced a large number of changes, primarily ar
 - Two new string types have been introduced:
   - Small string: a string of 14 bytes or less, stored within the object memory itself without extra allocations.
   - Literal string: a c-string which should be treated as read-only and never freed.
-- Object creation and access functions have been changed significantly, primarily to avoid the need for intermediate objects.
-- `ddwaf_run` has been renamed to `ddwaf_context_eval`.
+- Object creation, access and destruction functions have been changed significantly, primarily to avoid the need for intermediate objects and due to the introduction of allocators.
+- For consistency,`ddwaf_run` has been renamed to `ddwaf_context_eval`.
 - Subcontexts have been introduced to replace ephemerals, their lifecycle and use is equivalent to that of the context.
-- `ddwaf_object_free` and `ddwaf_result_free` are replaced by `ddwaf_object_destroy`, which requires the allocator used for the object's allocations.
 - `ddwaf_config` has been removed:
   - Evaluation limits have been entirely removed, the caller must now enforce any relevant limits during serialisation.
   - Obfuscator regexes must now be provided through configuration: `{obfuscator: {key_regex: <value>, value_regex: <value>}}`.
   - The free function is no longer needed due to the introduction of allocators.
 
-## Checklist for bindings maintainers
-
-- Replace `ddwaf_init(ruleset, config, diagnostics)` with `ddwaf_init(ruleset, diagnostics)` and destroy `diagnostics` with the default allocator.
-- Pass an output allocator to `ddwaf_context_init()` and destroy results with `ddwaf_object_destroy(result, output_alloc)`.
-- Update `ddwaf_run()` usages to `ddwaf_context_eval()` and consolidate persistent/ephemeral data into a single `data` argument.
-- If you relied on ephemerals, introduce subcontexts and destroy them with `ddwaf_subcontext_destroy()`.
-- Replace `ddwaf_object_free`/`ddwaf_result_free` with `ddwaf_object_destroy` and ensure the allocator used for allocation is available at destruction time.
-- Update object builders to `ddwaf_object_set_*` plus `ddwaf_object_insert_*` APIs; prefer literal/no-copy variants only when ownership rules are clear.
-
 ## Note on Allocators
 The ownership of any allocated memory crossing the API boundary was one of the pain points of libddwaf v1. To fix this, v2 introduces allocators, which can be used to define the explicit ownership of the allocated memory.
 
-Since the use of allocators is now required on many of the API functions, the migration examples will use the default allocator and will also include allocator destruction for illustrative purposes, as the destruction of the default allocator is a no-op.
+Since the use of allocators is now required on many of the API functions, the migration examples will use the default allocator and will also include allocator destruction for illustrative purposes, as the destruction of the default allocator is a no-op. 
 
-The allocator API now includes default, pool, monotonic, and user-defined allocators via `ddwaf_*_allocator_init()` plus `ddwaf_allocator_destroy()` for cleanup. The default allocator is process-wide and `ddwaf_allocator_destroy()` is a no-op for it.
-
-See the [allocators document](../allocators.md) for more information on the different types of allocators available.
+However, note that other allocators are also available. See the [allocators document](../allocators.md) for more information on the different types of allocators available.
 
 ## 1. WAF instantiation: Removal of `ddwaf_config`
 
-The main changes pertaining to WAF initialisation is the removal of `ddwaf_config`, as the evaluation limits have been entirely removed in favour of user-controlled truncation and the free function is no longer required due to the explicit memory ownership defined through allocators. As a consequence, instantiation through `ddwaf_init` has changed as follows:
+The main changes pertaining to WAF initialisation is the removal of `ddwaf_config`, as the evaluation limits have been entirely removed, in favour of user-controlled truncation, and the free function is no longer required due to the explicit memory ownership defined through allocators. As a consequence, instantiation through `ddwaf_init` has changed as follows:
 
 **v1.x:**
 ```c
@@ -55,9 +43,8 @@ ddwaf_object ruleset = ...;
 ddwaf_object diagnostics;
 ddwaf_handle handle = ddwaf_init(&ruleset, &diagnostics);
 ```
-The `diagnostics` object is allocated with the default allocator and must be destroyed with `ddwaf_object_destroy(&diagnostics, ddwaf_get_default_allocator())`.
+When instantiating through the builder, the deprecation of `ddwaf_config` only affects `ddwaf_builder_init`.
 
-When instantiating through the builder, the deprecation of `ddwaf_config` only affects `ddwaf_builder_init`:
 **v1.x:**
 ```c
 ddwaf_config config = ...;
@@ -69,12 +56,21 @@ ddwaf_builder builder = ddwaf_builder_init(&config);
 ddwaf_builder builder = ddwaf_builder_init();
 ```
 
+Note that the The `diagnostics` object is allocated with the default allocator and must be destroyed as follows:
+
+```c
+ddwaf_object_destroy(&diagnostics, ddwaf_get_default_allocator())
+```
+This applies to both `ddwaf_init` and to relevant `ddwaf_builder_*` functions.
+
 ## 2. WAF Context: Input & Output Allocators and Removal of Ephemerals
 
-The WAF context lifecycle has changed significantly in v2 with the introduction of allocators and the consolidation of persistent and ephemeral data into a single parameter. In v1.x, `ddwaf_run` accepted separate persistent and ephemeral data parameters, while v2.x uses `ddwaf_context_eval` with a unified data parameter.
+The WAF context lifecycle functions have changed significantly in v2 with the introduction of allocators and subcontexts as a replacement for ephemerals. In v1.x, `ddwaf_run` accepted separate persistent and ephemeral data parameters, while v2.x no longer provides ephemeral semantics, therefore only persistent data is provided.
 
 ### Context Initialization
 
+During context initialisation, the caller must provide the output allocator which is used by the WAF to allocate memory for the result object, provided as an output parameter to `ddwaf_context_eval`. This allocator must remain valid for the lifetime of the context.
+
 **v1.x:**
 ```c
 ddwaf_handle handle = ...;
@@ -94,10 +90,10 @@ ddwaf_allocator output_alloc = ddwaf_get_default_allocator();
 ddwaf_context context = ddwaf_context_init(handle, output_alloc);
 ```
 
-The output allocator (`output_alloc`) is used by the WAF to allocate memory for the result object returned by `ddwaf_context_eval`. This allocator must remain valid for the lifetime of the context.
-
 ### Context Evaluation
 
+As mentioned, context evaluation no longer supports ephemeral data, consequently the main difference between v1.x and v2.x is the removal from `ddwaf_run`, which has been renamed to `ddwaf_context_eval`. Additionally, the allocator used to generate the input data must also be provided. Note that this allocator may be the same as the output allocator provided through `ddwaf_context_init` and it must also remain valid for the lifetime of the context.
+
 **v1.x:**
 ```c
 ddwaf_object persistent_data = ...;
@@ -134,20 +130,6 @@ if (code == DDWAF_MATCH) {
 // Destroy result using the output allocator from ddwaf_context_init
 ddwaf_object_destroy(&result, output_alloc);
 ```
-
-### Key Changes
-
-1. **Allocators Required**: Both context initialization and evaluation now require allocators
-   - Output allocator: Passed to `ddwaf_context_init()`, used for result objects
-   - Input allocator: Passed to `ddwaf_context_eval()`, used to manage input data lifecycle
-   - If the input allocator is NULL, libddwaf will not free the input data; the caller must keep it alive until the context or subcontext is destroyed.
-
-2. **Unified Data Parameter**: The `persistent_data` and `ephemeral_data` split has been removed. All data is passed through the single `data` parameter in `ddwaf_context_eval()`.
-
-3. **Persistent Data Accumulation**: Data passed to `ddwaf_context_eval()` is stored in the context and persists across multiple evaluations. To override a previously provided address, simply pass new data for the same address in a subsequent call.
-
-4. **Result Object Management**: The result object is now a `ddwaf_object` instead of `ddwaf_result`, and must be destroyed with `ddwaf_object_destroy()` using the output allocator.
-
 ### Multiple Evaluations Example
 
 **v1.x:**

From fee47deb5c9a5f3d6e8399b584041e9400b19868 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Tue, 20 Jan 2026 17:25:38 +0000
Subject: [PATCH 15/32] Human-powered fixes and improvements

---
 docs/upgrading/UPGRADING-v2.0.md | 137 ++++++++++++++++---------------
 1 file changed, 73 insertions(+), 64 deletions(-)

diff --git a/docs/upgrading/UPGRADING-v2.0.md b/docs/upgrading/UPGRADING-v2.0.md
index 5db6a7132..999e4132c 100644
--- a/docs/upgrading/UPGRADING-v2.0.md
+++ b/docs/upgrading/UPGRADING-v2.0.md
@@ -275,6 +275,7 @@ The object creation API has changed extensively in v2 to support allocators and
 
 ### String Creation
 
+The creation of a string object typically involves an allocation, therefore the allocator parameter is now required. Additionally, the string length is now always required to avoid potential issues with nul characters.
 **v1.x:**
 ```c
 // Create string object (library allocates and copies)
@@ -297,25 +298,40 @@ ddwaf_object_set_string(&obj, "hello world", 11, alloc);
 ddwaf_object_destroy(&obj, alloc);
 ```
 
-### String Literals (Read-Only Strings)
+**Note**: Small strings (14 bytes or less) are automatically stored inline within the object itself without additional allocation.
 
-v2 introduces a new literal string type for read-only strings, which avoids allocation:
+#### Literal Strings
+
+This new version introduces a new literal string type which are never freed, this makes it easier to provide literals or interned strings. The associated memory must be managed by the caller:
 
-**v2.x:**
 ```c
 ddwaf_object obj;
 
 // String literal - no allocation, no copy
 ddwaf_object_set_string_literal(&obj, "constant string", 15);
+```
+
+#### No-Copy Strings
+
+It is still possible to create freeable strings by providing a preallocated/preinitialised buffer using the `ddwaf_object_set_string_nocopy`, however note that the memory of the provided buffer must have been allocated with the same allocator used for object destruction, e.g. using `ddwaf_allocator_alloc`.
+
+```c
+ddwaf_object obj;
 
-// Must still call destroy, but allocator can be any valid allocator since no memory was allocated
 ddwaf_allocator alloc = ddwaf_get_default_allocator();
-ddwaf_object_destroy(&obj, alloc);
-```
 
-**Note**: Small strings (14 bytes or less) are automatically stored inline within the object itself without additional allocation, regardless of whether you use `ddwaf_object_set_string()` or `ddwaf_object_set_string_literal()`.
+// Preallocated and preinitialised
+char *str = (char*)ddwaf_allocator_alloc(alloc, 16, 1);
 
-**No-copy strings**: Use `ddwaf_object_set_string_nocopy()` when the string buffer is already allocated with the same allocator you will pass to `ddwaf_object_destroy()`. This avoids a copy but requires the buffer to remain valid for the lifetime of the object.
+// Initialise string
+...
+
+// String literal - no allocation, no copy
+ddwaf_object_set_string_nocopy(&obj, str, strlen(str));
+
+// Destroy using the correct allocator
+ddwaf_object_destroy(&obj, alloc);
+```
 
 ### Numeric Types
 
@@ -336,9 +352,53 @@ The same pattern applies to other numeric types:
 - `ddwaf_object_bool()` → `ddwaf_object_set_bool()`
 - `ddwaf_object_float()` → `ddwaf_object_set_float()`
 
+
+### Array Creation and Insertion
+
+The array insertion API has changed to return a pointer to the inserted value, eliminating the need for intermediate objects.
+
+**v1.x:**
+```c
+ddwaf_object array;
+ddwaf_object_array(&array);
+
+// Create value objects and add to array
+ddwaf_object elem1;
+ddwaf_object_string(&elem1, "first");
+ddwaf_object_array_add(&array, &elem1);
+
+ddwaf_object elem2;
+ddwaf_object_string(&elem2, "second");
+ddwaf_object_array_add(&array, &elem2);
+
+ddwaf_object_free(&array);
+```
+
+**v2.x:**
+```c
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+
+ddwaf_object array;
+ddwaf_object_set_array(&array, 2, alloc);  // Initialize with capacity
+
+// Insert and set value in one step
+ddwaf_object_set_string(
+    ddwaf_object_insert(&array, alloc),
+    "first", 5, alloc);
+
+ddwaf_object_set_string(
+    ddwaf_object_insert(&array, alloc),
+    "second", 6, alloc);
+
+ddwaf_object_destroy(&array, alloc);
+```
+
+
 ### Map Creation and Insertion
 
-The map insertion API has changed to return a pointer to the inserted value, eliminating the need for intermediate objects.
+The map creation now requires both the expected size of the map (which may be 0) and a suitable allocator. Note that if the size of the map is incorrect, the container will still grow dynamically.
+
+Additionally, the insertion API has changed to return a pointer to the inserted value, eliminating the need for intermediate objects.
 
 **v1.x:**
 ```c
@@ -377,48 +437,9 @@ ddwaf_object_set_unsigned(
 
 ddwaf_object_destroy(&map, alloc);
 ```
+#### Insertion Variants
 
-### Array Creation and Insertion
-
-**v1.x:**
-```c
-ddwaf_object array;
-ddwaf_object_array(&array);
-
-// Create value objects and add to array
-ddwaf_object elem1;
-ddwaf_object_string(&elem1, "first");
-ddwaf_object_array_add(&array, &elem1);
-
-ddwaf_object elem2;
-ddwaf_object_string(&elem2, "second");
-ddwaf_object_array_add(&array, &elem2);
-
-ddwaf_object_free(&array);
-```
-
-**v2.x:**
-```c
-ddwaf_allocator alloc = ddwaf_get_default_allocator();
-
-ddwaf_object array;
-ddwaf_object_set_array(&array, 2, alloc);  // Initialize with capacity
-
-// Insert and set value in one step
-ddwaf_object_set_string(
-    ddwaf_object_insert(&array, alloc),
-    "first", 5, alloc);
-
-ddwaf_object_set_string(
-    ddwaf_object_insert(&array, alloc),
-    "second", 6, alloc);
-
-ddwaf_object_destroy(&array, alloc);
-```
-
-### Insertion Variants
-
-v2 provides multiple insertion functions for different use cases:
+To cover different allocation and / or string management strategies, v2 provides multiple insertion functions for different use cases:
 
 ```c
 ddwaf_allocator alloc = ddwaf_get_default_allocator();
@@ -460,11 +481,12 @@ const char *str = ddwaf_object_get_string(&obj, &length);  // Unchanged
 uint64_t num = ddwaf_object_get_unsigned(&obj);  // Unchanged
 ```
 
+The same pattern applies to all other getters.
+
 ### JSON Parsing
 
 If you use `ddwaf_object_from_json()`, it now takes an allocator and the resulting object must be destroyed with the same allocator:
 
-**v2.x:**
 ```c
 ddwaf_allocator alloc = ddwaf_get_default_allocator();
 ddwaf_object obj;
@@ -519,16 +541,3 @@ ddwaf_object_set_string(
 
 ddwaf_object_destroy(&root, alloc);
 ```
-
-### Key Changes Summary
-
-1. **Allocator Required**: Most creation functions now require an allocator (except numeric types and null/invalid)
-2. **Naming Convention**: `ddwaf_object_*` → `ddwaf_object_set_*` for creation functions
-3. **Insertion Returns Pointer**: `ddwaf_object_insert()` and `ddwaf_object_insert_key()` return a pointer to the inserted object, allowing direct value assignment
-4. **String Variants**: Three string types available:
-   - `ddwaf_object_set_string()`: Allocates and copies (regular string)
-   - `ddwaf_object_set_string_literal()`: Read-only, no allocation (literal string)
-   - Small strings (≤14 bytes): Automatically stored inline
-5. **No-copy Variants**: `ddwaf_object_set_string_nocopy()` and `ddwaf_object_insert_key_nocopy()` avoid copies but require allocator-managed storage
-6. **Destruction**: `ddwaf_object_free(&obj)` → `ddwaf_object_destroy(&obj, alloc)`
-7. **Literal Keys**: Use `ddwaf_object_insert_literal_key()` for constant string keys to avoid allocation

From d7e448727ea0ac7f4b3c846cea01370c9af04646 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Tue, 20 Jan 2026 17:25:38 +0000
Subject: [PATCH 16/32] Human-powered fixes and improvements

---
 docs/upgrading/UPGRADING-v2.0.md | 64 +++++++++++++++-----------------
 1 file changed, 29 insertions(+), 35 deletions(-)

diff --git a/docs/upgrading/UPGRADING-v2.0.md b/docs/upgrading/UPGRADING-v2.0.md
index 999e4132c..92202e60d 100644
--- a/docs/upgrading/UPGRADING-v2.0.md
+++ b/docs/upgrading/UPGRADING-v2.0.md
@@ -1,16 +1,16 @@
 # Upgrading libddwaf
 
-The C API in libddwaf v2 has experienced a large number of changes, primarily around the creation and use of ddwaf_object. This guide aims to provide an overview of the changes required to upgrade from v1.x to v2.x, however it is recommended that the reader carefully reads the [C API Reference](c-api/api.md) and [ddwaf.h](../../include/ddwaf.h).
+The C API in libddwaf v2 has experienced a large number of changes, primarily around the creation and use of ddwaf_object. This guide aims to provide an overview of the changes required to upgrade from v1.x to v2.x; however it is recommended that the reader carefully read the [C API Reference](c-api/api.md) and [ddwaf.h](../../include/ddwaf.h).
 
 ## Summary
 - Allocators have been introduced to all relevant API functions.
 - The layout of `ddwaf_object` has dramatically changed to reduce the amount of memory required for a single object, which now only requires 16 bytes.
 - Two new string types have been introduced:
   - Small string: a string of 14 bytes or less, stored within the object memory itself without extra allocations.
-  - Literal string: a c-string which should be treated as read-only and never freed.
+  - Literal string: a C string which should be treated as read-only and never freed.
 - Object creation, access and destruction functions have been changed significantly, primarily to avoid the need for intermediate objects and due to the introduction of allocators.
-- For consistency,`ddwaf_run` has been renamed to `ddwaf_context_eval`.
-- Subcontexts have been introduced to replace ephemerals, their lifecycle and use is equivalent to that of the context.
+- For consistency, `ddwaf_run` has been renamed to `ddwaf_context_eval`.
+- Subcontexts have been introduced to replace ephemerals, their lifecycle and use are equivalent to that of the context.
 - `ddwaf_config` has been removed:
   - Evaluation limits have been entirely removed, the caller must now enforce any relevant limits during serialisation.
   - Obfuscator regexes must now be provided through configuration: `{obfuscator: {key_regex: <value>, value_regex: <value>}}`.
@@ -19,13 +19,13 @@ The C API in libddwaf v2 has experienced a large number of changes, primarily ar
 ## Note on Allocators
 The ownership of any allocated memory crossing the API boundary was one of the pain points of libddwaf v1. To fix this, v2 introduces allocators, which can be used to define the explicit ownership of the allocated memory.
 
-Since the use of allocators is now required on many of the API functions, the migration examples will use the default allocator and will also include allocator destruction for illustrative purposes, as the destruction of the default allocator is a no-op. 
+Since the use of allocators is now required on many of the API functions, the migration examples will use the default allocator and will also include allocator destruction for illustrative purposes, as the destruction of the default allocator is a no-op.
 
 However, note that other allocators are also available. See the [allocators document](../allocators.md) for more information on the different types of allocators available.
 
 ## 1. WAF instantiation: Removal of `ddwaf_config`
 
-The main changes pertaining to WAF initialisation is the removal of `ddwaf_config`, as the evaluation limits have been entirely removed, in favour of user-controlled truncation, and the free function is no longer required due to the explicit memory ownership defined through allocators. As a consequence, instantiation through `ddwaf_init` has changed as follows:
+The main changes pertaining to WAF initialisation are the removal of `ddwaf_config`, as the evaluation limits have been entirely removed, in favour of user-controlled truncation, and the free function is no longer required due to the explicit memory ownership defined through allocators. As a consequence, instantiation through `ddwaf_init` has changed as follows:
 
 **v1.x:**
 ```c
@@ -56,10 +56,10 @@ ddwaf_builder builder = ddwaf_builder_init(&config);
 ddwaf_builder builder = ddwaf_builder_init();
 ```
 
-Note that the The `diagnostics` object is allocated with the default allocator and must be destroyed as follows:
+Note that the `diagnostics` object is allocated with the default allocator and must be destroyed as follows:
 
 ```c
-ddwaf_object_destroy(&diagnostics, ddwaf_get_default_allocator())
+ddwaf_object_destroy(&diagnostics, ddwaf_get_default_allocator());
 ```
 This applies to both `ddwaf_init` and to relevant `ddwaf_builder_*` functions.
 
@@ -92,7 +92,7 @@ ddwaf_context context = ddwaf_context_init(handle, output_alloc);
 
 ### Context Evaluation
 
-As mentioned, context evaluation no longer supports ephemeral data, consequently the main difference between v1.x and v2.x is the removal from `ddwaf_run`, which has been renamed to `ddwaf_context_eval`. Additionally, the allocator used to generate the input data must also be provided. Note that this allocator may be the same as the output allocator provided through `ddwaf_context_init` and it must also remain valid for the lifetime of the context.
+As mentioned, context evaluation no longer supports ephemeral data, consequently the main difference between v1.x and v2.x is the removal of `ddwaf_run`, which has been renamed to `ddwaf_context_eval`. Additionally, the allocator used to generate the input data must also be provided. Note that this allocator may be the same as the output allocator provided through `ddwaf_context_init` and it must also remain valid for the lifetime of the context.
 
 **v1.x:**
 ```c
@@ -171,9 +171,9 @@ ddwaf_object_destroy(&result2, alloc);
 
 ## 3. WAF Subcontext: Replacement of Ephemerals
 
-Subcontexts are the v2 replacement for ephemeral data. In v1.x, ephemeral data was passed separately to `ddwaf_run()` and was not stored in the context. In v2.x, subcontexts inherit all persistent data from their parent context but can be evaluated with temporary data that doesn't persist beyond the subcontext's lifetime.
+Subcontexts are the v2 replacement for ephemeral data. In v1.x, ephemeral data was passed separately to `ddwaf_run()` and was not stored in the context. In v2.x, subcontexts inherit all persistent data from their parent context but can be evaluated with data that doesn't persist beyond the subcontext's lifetime.
 
-### Migration Pattern
+Note that in the current version, any context-related side-effects within the subcontext are not visible within the parent context.
 
 **v1.x:**
 ```c
@@ -208,7 +208,7 @@ ddwaf_object_destroy(&result1, alloc);
 // Create subcontext for ephemeral evaluation
 ddwaf_subcontext subctx = ddwaf_subcontext_init(context);
 
-// Evaluate with ephemeral data (inherits persistent data from parent)
+// Evaluate with "ephemeral" data (inherits persistent data from parent)
 ddwaf_object ephemeral = ...;
 ddwaf_object result2;
 ddwaf_subcontext_eval(subctx, &ephemeral, alloc, &result2, timeout);
@@ -217,20 +217,22 @@ ddwaf_object_destroy(&result2, alloc);
 // Clean up subcontext
 ddwaf_subcontext_destroy(subctx);
 
-// Ephemeral data is NOT stored in context, only persistent data remains
+// No side-effects are visible to the context
 ```
 
 ### Subcontext Lifecycle
 
 The subcontext follows the same lifecycle pattern as the context:
 
-1. **Initialize**: `ddwaf_subcontext_init(context)` - Creates a subcontext from parent
-2. **Evaluate**: `ddwaf_subcontext_eval(subctx, data, alloc, result, timeout)` - Evaluates with ephemeral data
-3. **Destroy**: `ddwaf_subcontext_destroy(subctx)` - Cleans up subcontext
+1. **Initialize**: `ddwaf_subcontext_init(context)` - Creates a subcontext from parent.
+2. **Evaluate**: `ddwaf_subcontext_eval(subctx, data, alloc, result, timeout)` - Evaluates data which must be valid during the lifecycle of the subcontext.
+3. **Destroy**: `ddwaf_subcontext_destroy(subctx)` - Cleans up subcontext.
+
+Note that the subcontext inherits the output allocator of the parent context.
 
 ### Multiple Subcontexts
 
-You can create multiple subcontexts from the same parent context, each with different ephemeral data:
+Multiple concurrent subcontexts may also be created from the same parent context, each of which defines the scope and lifecycle of the provided data:
 
 **v2.x:**
 ```c
@@ -260,22 +262,14 @@ ddwaf_subcontext_destroy(subctx2);
 // Both subcontexts inherited persistent data, but had independent ephemeral data
 ```
 
-### Key Points
-
-1. **Inheritance**: Subcontexts inherit all persistent data from their parent context at creation time
-2. **Ephemeral Data**: Data passed to `ddwaf_subcontext_eval()` is temporary and does not persist to the parent context
-3. **Independence**: Multiple subcontexts can coexist, each with different ephemeral data
-4. **Allocator Rules**: The input allocator controls how subcontext data is freed; if NULL, the caller must keep the data alive until the subcontext is destroyed
-5. **Lifecycle**: Subcontexts must be destroyed with `ddwaf_subcontext_destroy()` before or when destroying the parent context
-6. **Use Case**: Use subcontexts when you need to evaluate rules with temporary data (e.g., per-request data that shouldn't persist across multiple requests in the same session)
-
 ## 4. Object Creation: New API & Allocator support
 
 The object creation API has changed extensively in v2 to support allocators and reduce memory overhead. All object creation functions now use the `ddwaf_object_set_*` naming pattern, and most require an allocator parameter.
 
 ### String Creation
 
-The creation of a string object typically involves an allocation, therefore the allocator parameter is now required. Additionally, the string length is now always required to avoid potential issues with nul characters.
+The creation of a string object typically involves an allocation, therefore the allocator parameter is now required. Additionally, the string length is now always required to avoid potential issues with NUL characters.
+
 **v1.x:**
 ```c
 // Create string object (library allocates and copies)
@@ -302,7 +296,7 @@ ddwaf_object_destroy(&obj, alloc);
 
 #### Literal Strings
 
-This new version introduces a new literal string type which are never freed, this makes it easier to provide literals or interned strings. The associated memory must be managed by the caller:
+To address some existing use cases, v2 introduces a new literal string type which, upon destruction, never frees the associated buffer. This makes it easier to provide literals or interned strings as part of an object. The associated memory must be managed by the caller:
 
 ```c
 ddwaf_object obj;
@@ -313,7 +307,7 @@ ddwaf_object_set_string_literal(&obj, "constant string", 15);
 
 #### No-Copy Strings
 
-It is still possible to create freeable strings by providing a preallocated/preinitialised buffer using the `ddwaf_object_set_string_nocopy`, however note that the memory of the provided buffer must have been allocated with the same allocator used for object destruction, e.g. using `ddwaf_allocator_alloc`.
+It is still possible to create freeable strings by providing a pre-allocated/pre-initialised buffer, however note that the memory of the provided buffer must have been allocated with the same allocator used for object destruction, e.g. using `ddwaf_allocator_alloc`.
 
 ```c
 ddwaf_object obj;
@@ -322,11 +316,9 @@ ddwaf_allocator alloc = ddwaf_get_default_allocator();
 
 // Preallocated and preinitialised
 char *str = (char*)ddwaf_allocator_alloc(alloc, 16, 1);
+memcpy(str, "constant string", sizeof("constant string"));
 
-// Initialise string
-...
-
-// String literal - no allocation, no copy
+// No-copy string - no allocation, no copy
 ddwaf_object_set_string_nocopy(&obj, str, strlen(str));
 
 // Destroy using the correct allocator
@@ -355,7 +347,9 @@ The same pattern applies to other numeric types:
 
 ### Array Creation and Insertion
 
-The array insertion API has changed to return a pointer to the inserted value, eliminating the need for intermediate objects.
+The array creation now requires both the expected size of the array (which may be 0) and a suitable allocator. Note that if the size of the array is incorrect, the container will still grow dynamically.
+
+Additionally, the insertion API has changed to return a pointer to the inserted value, eliminating the need for intermediate objects.
 
 **v1.x:**
 ```c
@@ -439,7 +433,7 @@ ddwaf_object_destroy(&map, alloc);
 ```
 #### Insertion Variants
 
-To cover different allocation and / or string management strategies, v2 provides multiple insertion functions for different use cases:
+To cover different allocation and/or string management strategies, v2 provides multiple insertion functions for different use cases:
 
 ```c
 ddwaf_allocator alloc = ddwaf_get_default_allocator();

From 1df9f4396d245a2ff6e7edd3c7ab5cb9c6a9e61e Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 09:00:42 +0000
Subject: [PATCH 17/32] Split coverage upload into separate jobs

Refactored the upload-coverage job into three distinct jobs:
- generate-coverage: merges coverage data and creates artifacts
- upload-to-codecov: uploads coverage to CodeCov (runs on all branches)
- upload-to-datadog: uploads coverage to DataDog (master branch only)

This separation allows parallel uploads and restricts DataDog uploads to production deployments.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .github/workflows/test.yml | 66 +++++++++++++++++++++++++++++---------
 1 file changed, 51 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 0fc547ac1..d49804e34 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -209,11 +209,9 @@ jobs:
           name: coverage_${{ matrix.suffix }}_${{ matrix.arch }}
           path: ${{ github.workspace }}/Debug/coverage-${{ matrix.suffix }}-${{ matrix.arch }}.json
 
-  upload-coverage:
+  generate-coverage:
     needs: [ coverage ]
     runs-on: ubuntu-24.04
-    environment:
-      name: dd-protected-coverage
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
         with:
@@ -223,10 +221,6 @@ jobs:
         with:
           path: artifacts
 
-      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903
-        with:
-          node-version: 24
-
       - name: Install dependencies
         run: |
           sudo apt update
@@ -234,7 +228,7 @@ jobs:
           python3 -m venv .venv
           source .venv/bin/activate
           pip install gcovr==7.2
-          npm install -g @datadog/datadog-ci
+
       - name: Generate coverage
         run: |
           source .venv/bin/activate
@@ -243,10 +237,28 @@ jobs:
           mkdir -p coverage
           gcovr --merge-mode-functions merge-use-line-0 --json-add-tracefile "artifacts/*/coverage-*.json" --html-details coverage/coverage.html
 
-      - name: Submit coverage (DataDog)
-        run: datadog-ci coverage upload coverage.xml
-        env:
-          DD_API_KEY: ${{ secrets.DD_API_KEY }}
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: coverage
+          path: ${{ github.workspace }}/coverage/
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: coverage-xml
+          path: ${{ github.workspace }}/coverage.xml
+
+  upload-to-codecov:
+    needs: [ generate-coverage ]
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          submodules: recursive
+
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0
+        with:
+          name: coverage-xml
+          path: .
 
       - name: Submit coverage (CodeCov)
         uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7
@@ -255,10 +267,34 @@ jobs:
           flags: waf_test
           verbose: true
           files: coverage.xml
-      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+
+  upload-to-datadog:
+    needs: [ generate-coverage ]
+    runs-on: ubuntu-24.04
+    if: github.ref == 'refs/heads/master'
+    environment:
+      name: dd-protected-coverage
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
         with:
-          name: coverage
-          path: ${{ github.workspace }}/coverage/
+          submodules: recursive
+
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0
+        with:
+          name: coverage-xml
+          path: .
+
+      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903
+        with:
+          node-version: 24
+
+      - name: Install datadog-ci
+        run: npm install -g @datadog/datadog-ci
+
+      - name: Submit coverage (DataDog)
+        run: datadog-ci coverage upload coverage.xml
+        env:
+          DD_API_KEY: ${{ secrets.DD_API_KEY }}
 
   lint:
     runs-on: ubuntu-24.04

From 749b7a2d7d75302a45c5075c479310f98c06326d Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 10:20:37 +0000
Subject: [PATCH 18/32] Update binding integration guide for v2.0 API

- Replace ddwaf_init/ddwaf_update with ddwaf_builder API
- Fix function signatures (add allocator parameters)
- Add ddwaf_builder lifecycle documentation
- Add note about ddwaf_subcontext thread safety
- Remove outdated allocator and diagnostics sections
- Fix grammar: "put in other words" -> "or in other words"

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 docs/c-api/binding-integration-guide.md | 189 +++++++++++++++---------
 1 file changed, 121 insertions(+), 68 deletions(-)

diff --git a/docs/c-api/binding-integration-guide.md b/docs/c-api/binding-integration-guide.md
index 9761cc1c3..e88043eb7 100644
--- a/docs/c-api/binding-integration-guide.md
+++ b/docs/c-api/binding-integration-guide.md
@@ -1,37 +1,46 @@
-# libddwaf binding integration guide
+# Implementation notes for bindings
 
-This guide complements the API reference in `docs/c-api/api.md`. It focuses on
-the concurrency and lifecycle concerns that most native bindings must handle to
-provide a safe libddwaf integration.
 
-## `ddwaf_handle` lifecycle
+## `ddwaf_handle`
 
-`ddwaf_handle` represents the compiled ruleset, related data providers, and
-exclusions. Handles are built through `ddwaf_init` and updated in place through
-`ddwaf_update`. Only one instance is typically kept by a tracer or agent.
+`ddwaf_handle` represents a rule set, with associated rule data, exclusions,
+and so on. It is created through the `ddwaf_builder` API.
 
-The two operations that observe a handle are `ddwaf_context_init` and
-`ddwaf_update`. Neither mutates the handle content, but callers must ensure that
-other threads only observe a fully initialised pointer. A release/acquire pair
-is enough for this requirement:
+A tracer will want to keep only one live `ddwaf_handle`. The first one will be
+created through `ddwaf_builder_build_instance`, and then it will replace it by
+updating the builder and building a new instance as it gets new configurations
+through remote config.
+
+The relevant read operations on `ddwaf_handle` are `ddwaf_context_init`,
+`ddwaf_known_addresses`, and `ddwaf_known_actions`. None of these operations
+modify the `ddwaf_handle`. So, at this point, it is sufficient to ensure that
+threads calling these functions see a fully constructed `ddwaf_handle` — or in
+other words, it is sufficient that the write to the pointer/reference happens
+after `ddwaf_builder_build_instance` is called (as seen by other threads). For
+this, a release-acquire operation suffices:
 
 ```c++
 std::atomic<ddwaf_handle> cur_ddwaf_handle; // global variable; the live handle
 
 // Initialization thread
-void initialize_handle(
-    const ddwaf_object *ruleset, const ddwaf_config *config, ddwaf_object *diagnostics)
+void initialize_handle(const ddwaf_object *ruleset, ddwaf_object *diagnostics)
 {
-    ddwaf_handle new_handle = ddwaf_init(ruleset, config, diagnostics);
-    if (new_handle == nullptr) { /* handle error */}
+    ddwaf_builder builder = ddwaf_builder_init();
+    if (builder == nullptr) { /* handle error */ }
+
+    ddwaf_builder_add_or_update_config(builder, "main", 4, ruleset, diagnostics);
+    ddwaf_handle new_handle = ddwaf_builder_build_instance(builder);
+    ddwaf_builder_destroy(builder);
+
+    if (new_handle == nullptr) { /* handle error */ }
     cur_ddwaf_handle.store(new_handle, std::memory_order_release);
 }
 
 // Request thread
-ddwaf_context create_context() {
+ddwaf_context create_context(ddwaf_allocator output_alloc) {
     ddwaf_handle handle = cur_ddwaf_handle.load(std::memory_order_acquire);
     if (handle == nullptr) { /* handle error */ }
-    return ddwaf_context_init(handle);
+    return ddwaf_context_init(handle, output_alloc);
 }
 ```
 
@@ -42,10 +51,14 @@ prevent a use-after-free in this situation:
 
 ```c++
 // Remote config thread
-void update_handle(const ddwaf_object *ruleset, ddwaf_object *diagnostics)
+void update_handle(ddwaf_builder builder, const ddwaf_object *ruleset, ddwaf_object *diagnostics)
 {
     ddwaf_handle old_handle = cur_ddwaf_handle.load(std::memory_order_acquire);
-    ddwaf_handle new_handle = ddwaf_update(old_handle, ruleset, diagnostics);
+
+    // Update the builder with new configuration
+    ddwaf_builder_add_or_update_config(builder, "main", 4, ruleset, diagnostics);
+    ddwaf_handle new_handle = ddwaf_builder_build_instance(builder);
+
     cur_ddwaf_handle.store(new_handle, std::memory_order_release);
 
     // will free the memory if no ddwaf_contexts are associated with it:
@@ -53,42 +66,51 @@ void update_handle(const ddwaf_object *ruleset, ddwaf_object *diagnostics)
 }
 
 // Request thread
-ddwaf_context create_context() {
+ddwaf_context create_context(ddwaf_allocator output_alloc) {
     ddwaf_handle handle = cur_ddwaf_handle.load(std::memory_order_acquire);
     if (handle == nullptr) { /* handle error */ }
     // XXX: the handle fetched may have been destroyed in the interim
-    return ddwaf_context_init(handle);
+    return ddwaf_context_init(handle, output_alloc);
 }
 ```
 
 That is, the old `ddwaf_handle` can only be destroyed once we can be guaranteed
-that no other thread will try to create a new context from it (or update it
-through `ddwaf_update`, though that is less of a problem because generally the
-tracers will not want to update the global `ddwaf_handle` from several threads
-simultaneously).
-
-There are many ways to guarantee safe reclamation. Two common strategies are
-outlined below.
-
-* Delay `ddwaf_destroy` until your runtime can prove that no other code keeps a
-  reference. Garbage-collected environments can let the wrapper object finalise
-  the native handle, but keep in mind that the collector is blind to the native
-  memory usage.
-
-* Protect access with reader/writer locks so that `ddwaf_destroy` only executes
-  after new contexts can no longer be created:
+that no other thread will try to create a new context from it (or build a new
+handle through the builder, though that is less of a problem because generally
+the tracers will not want to update the global `ddwaf_handle` from several
+threads simultaneously).
+
+There are many possible strategies to deal with this memory reclamation
+problem, but the most straightforward are:
+
+* If the runtime uses garbage collection, we can delay the call to
+  `ddwaf_destroy` until the garbage collector determines the object wrapping
+  the native `ddwaf_handle` has no more references. This is relatively easy to
+  do and doesn't involve extra usage of locks, but the memory used by the
+  `ddwaf_handle` will not be available until the garbage collector decides
+  to reclaim the wrapped object. Because the garbage collector does not see
+  the memory being used by the `ddwaf_handle`, if garbage collection never
+  happens, there is a risk that memory consumption gets too high. This is a
+  rather unlikely scenario though.
+
+* You can use read-write locks:
 
 ```c++
 // global variables
 std::shared_mutex mutex;
-ddwaf_handle cur_ddwaf_handle = nullptr;
+ddwaf_handle cur_ddwaf_handle;
 
 // Initialization thread
-void initialize_handle(
-    const ddwaf_object *ruleset, const ddwaf_config *config, ddwaf_object *diagnostics)
+void initialize_handle(const ddwaf_object *ruleset, ddwaf_object *diagnostics)
 {
-    ddwaf_handle new_handle = ddwaf_init(ruleset, config, diagnostics);
-    if (new_handle == nullptr) { /* handle error */}
+    ddwaf_builder builder = ddwaf_builder_init();
+    if (builder == nullptr) { /* handle error */ }
+
+    ddwaf_builder_add_or_update_config(builder, "main", 4, ruleset, diagnostics);
+    ddwaf_handle new_handle = ddwaf_builder_build_instance(builder);
+    ddwaf_builder_destroy(builder);
+
+    if (new_handle == nullptr) { /* handle error */ }
 
     std::unique_lock lock{mutex}; // acquire write lock
     cur_ddwaf_handle = new_handle;
@@ -96,37 +118,44 @@ void initialize_handle(
 }
 
 // Remote config thread
-void update_handle(const ddwaf_object *ruleset, ddwaf_object *diagnostics)
+void update_handle(ddwaf_builder builder, const ddwaf_object *ruleset, ddwaf_object *diagnostics)
 {
     std::unique_lock lock{mutex}; // acquire write lock
     ddwaf_handle old_handle = cur_ddwaf_handle;
-    ddwaf_handle new_handle = ddwaf_update(old_handle, ruleset, diagnostics);
+
+    ddwaf_builder_add_or_update_config(builder, "main", 4, ruleset, diagnostics);
+    ddwaf_handle new_handle = ddwaf_builder_build_instance(builder);
+
     cur_ddwaf_handle = new_handle;
     ddwaf_destroy(old_handle);
     // write lock released on return
 }
 
 // Request thread
-ddwaf_context create_context() {
+ddwaf_context create_context(ddwaf_allocator output_alloc) {
     std::shared_lock lock{mutex}; // acquire read lock
     if (cur_ddwaf_handle == nullptr) { /* handle error */ }
-    return ddwaf_context_init(cur_ddwaf_handle);
+    return ddwaf_context_init(cur_ddwaf_handle, output_alloc);
     // read lock released on return
 }
 ```
 
-## `ddwaf_context` and `ddwaf_subcontext`
+## `ddwaf_context`
 
-`ddwaf_context` is not thread-safe. If a context can be touched by multiple
-threads (for example, when the web server hands off the same request to another
-thread), guard calls to `ddwaf_context_eval` and `ddwaf_context_destroy`. You
-must also prevent any evaluation after the owning handle has been destroyed.
+On the other hand, `ddwaf_context` is not thread-safe. If a `ddwaf_context` is
+used by multiple threads (in web servers where the processing of the request
+can move between several threads, or happen in several threads simultaneously),
+you need to use locks so that calls to `ddwaf_context_eval` and `ddwaf_context_destroy`
+are not run concurrently, and that changes made to the `ddwaf_context` in one thread
+through `ddwaf_context_eval` are visible to the other threads subsequently running
+`ddwaf_context_eval` on the same context. You also need to ensure that no calls
+to `ddwaf_context_eval` or `ddwaf_context_destroy` happen after `ddwaf_context_destroy`
+is called.
 
-When you only need isolated evaluation state but still share the same handle,
-prefer `ddwaf_context_init` per request. `ddwaf_subcontext_init` (documented in
-the API reference) can provide a cheaper clone when your binding benefits from
-sharing captures between stages. Subcontexts inherit the parent lifetime, so
-they must never outlive the original context.
+**Note**: The same thread-safety considerations apply to `ddwaf_subcontext`. Subcontexts
+are created from a parent context via `ddwaf_subcontext_init` and evaluated with
+`ddwaf_subcontext_eval`. Like contexts, they are not thread-safe and require external
+synchronization if accessed from multiple threads.
 
 ```c++
 // each request will have one of these associated with it
@@ -136,11 +165,12 @@ struct ctx_wrapper {
 };
 
 DDWAF_RET_CODE run_waf(
-    ctx_wrapper &wrapper, ddwaf_object *data, ddwaf_object *result, uint64_t timeout)
+    ctx_wrapper &wrapper, ddwaf_object *data, ddwaf_allocator alloc,
+    ddwaf_object *result, uint64_t timeout)
 {
     std::lock_guard<std::mutex> lock{wrapper.mutex}; // acquire exclusive lock
     if (wrapper.ctx == nullptr) { /* context already destroyed */ }
-    return ddwaf_context_eval(wrapper.ctx, data, result, timeout);
+    return ddwaf_context_eval(wrapper.ctx, data, alloc, result, timeout);
     // lock is released on return
 }
 
@@ -152,15 +182,38 @@ void destroy_ctx(ctx_wrapper &wrapper) {
 }
 ```
 
-## Custom allocators and diagnostics
+## `ddwaf_builder`
+
+The `ddwaf_builder` API manages multiple configuration sources and enables
+configuration updates. This is the recommended way to create `ddwaf_handle`
+instances, especially when dealing with remote configuration updates.
+
+### Builder Lifecycle
+
+```c
+// 1. Initialize builder
+ddwaf_builder builder = ddwaf_builder_init();
+
+// 2. Add configurations with unique paths
+ddwaf_object diagnostics;
+ddwaf_builder_add_or_update_config(builder, "base", 4, base_config, &diagnostics);
+ddwaf_object_destroy(&diagnostics, ddwaf_get_default_allocator());
+
+// 3. Build instance
+ddwaf_handle handle = ddwaf_builder_build_instance(builder);
+
+// 4. Later, update configurations
+ddwaf_builder_add_or_update_config(builder, "remote/prod", 11, remote_config, &diagnostics);
+ddwaf_handle new_handle = ddwaf_builder_build_instance(builder);
+
+// 5. Remove configurations if needed
+ddwaf_builder_remove_config(builder, "remote/prod", 11);
+
+// 6. Destroy builder when no longer needed
+ddwaf_builder_destroy(builder);
+```
 
-Consult `docs/c-api/api.md` for the exact signatures of allocator hooks. Any
-binding that offers native memory tracking should expose `ddwaf_user_allocator_init`
-wrappers and document the ownership of `ddwaf_object`. The documented helpers in
-the header (`ddwaf_object_*`) ensure that objects stay consistent with their
-type tag.
+### Thread Safety
 
-libddwaf can emit logs through `ddwaf_set_log_cb`. Bindings should translate
-the `DDWAF_LOG_LEVEL` levels into their host logging facilities and pay
-attention to thread-safety inside the callback. The callback can run from hot
-paths, so limit the amount of work performed there.
+`ddwaf_builder` operations are not thread-safe. If you need to update configurations
+from multiple threads, use external synchronization (e.g., a mutex).

From 2b9d4d742899462fadd10a3693fff03ca5b15fc9 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 10:28:59 +0000
Subject: [PATCH 19/32] Fix documentation accuracy and spelling consistency
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

API reference (docs/c-api/api.md):
- Clarify that output_alloc is for result objects in eval functions
- Fix critical error: result must be destroyed with output_alloc, not alloc parameter
- Improve thread safety description for WAF handles

Upgrading guide (docs/upgrading/UPGRADING-v2.0.md):
- Use consistent British spelling throughout
- "Context Initialization" → "Context Initialisation"
- "Preallocated and preinitialised" → "Pre-allocated and pre-initialised"

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 docs/c-api/api.md                | 8 ++++----
 docs/upgrading/UPGRADING-v2.0.md | 4 ++--
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/c-api/api.md b/docs/c-api/api.md
index 0cd5f8f99..8694d2b2b 100644
--- a/docs/c-api/api.md
+++ b/docs/c-api/api.md
@@ -163,7 +163,7 @@ Lists the action identifiers that may appear in evaluation results. Ownership ru
 ddwaf_context ddwaf_context_init(const ddwaf_handle handle, ddwaf_allocator output_alloc);
 ```
 
-Creates an evaluation context bound to a WAF instance. The allocator manages any output or cached copies of request data. Returns `NULL` on allocation errors.
+Creates an evaluation context bound to a WAF instance. The `output_alloc` allocator is used to allocate result objects returned by `ddwaf_context_eval` and `ddwaf_subcontext_eval`. Returns `NULL` on allocation errors.
 
 ### `ddwaf_context_eval`
 
@@ -176,7 +176,7 @@ DDWAF_RET_CODE ddwaf_context_eval(
     uint64_t timeout);
 ```
 
-Evaluates a request payload. `data` must be a map keyed by address and built with the same allocator used to destroy it. `alloc` supplies storage for intermediate copies and the optional `result`. When `result` is non-null and the return code is `DDWAF_OK` or `DDWAF_MATCH`, it contains detailed events and metadata which must be released with `ddwaf_object_destroy(result, alloc)`. The function enforces a microsecond timeout.
+Evaluates a request payload. `data` must be a map keyed by address. The `alloc` parameter is the allocator used to free the `data` object after evaluation completes (if non-null). When `result` is non-null and the return code is `DDWAF_OK` or `DDWAF_MATCH`, it contains detailed events and metadata allocated with the `output_alloc` from `ddwaf_context_init`, and must be released with `ddwaf_object_destroy(result, output_alloc)`. The function enforces a microsecond timeout.
 
 ### `ddwaf_context_destroy`
 
@@ -209,7 +209,7 @@ DDWAF_RET_CODE ddwaf_subcontext_eval(
     uint64_t timeout);
 ```
 
-Evaluates request data against a subcontext using the same semantics as `ddwaf_context_eval`. The allocator must be identical to the one used when creating the parent context.
+Evaluates request data against a subcontext using the same semantics as `ddwaf_context_eval`. The `alloc` parameter is used to free the `data` object. The `result` object, when populated, is allocated with the `output_alloc` from the parent context's `ddwaf_context_init` call and must be destroyed with that same allocator.
 
 ### `ddwaf_subcontext_destroy`
 
@@ -433,7 +433,7 @@ Reclaims any memory owned by the object. Always pass the allocator that was used
 
 ## Thread Safety and Lifetime Notes
 
-- WAF handles are thread-safe for evaluation once a context has been created. Builder operations and configuration mutation are not thread-safe.
+- WAF handles are thread-safe for read operations (`ddwaf_context_init`, `ddwaf_known_addresses`, `ddwaf_known_actions`). Builder operations and handle destruction are not thread-safe with respect to these read operations.
 - Allocation routines inherit the thread-safety guarantees of the allocator instance returned by the corresponding factory.
 - Objects created with `_string_literal` or `_insert_literal_key` expect the referenced buffers to outlive the object or to remain immutable.
 - Result objects returned by evaluation functions remain valid until destroyed. Never reuse them across calls without destroying or reinitialising them first.
diff --git a/docs/upgrading/UPGRADING-v2.0.md b/docs/upgrading/UPGRADING-v2.0.md
index 92202e60d..dadd52d9f 100644
--- a/docs/upgrading/UPGRADING-v2.0.md
+++ b/docs/upgrading/UPGRADING-v2.0.md
@@ -67,7 +67,7 @@ This applies to both `ddwaf_init` and to relevant `ddwaf_builder_*` functions.
 
 The WAF context lifecycle functions have changed significantly in v2 with the introduction of allocators and subcontexts as a replacement for ephemerals. In v1.x, `ddwaf_run` accepted separate persistent and ephemeral data parameters, while v2.x no longer provides ephemeral semantics, therefore only persistent data is provided.
 
-### Context Initialization
+### Context Initialisation
 
 During context initialisation, the caller must provide the output allocator which is used by the WAF to allocate memory for the result object, provided as an output parameter to `ddwaf_context_eval`. This allocator must remain valid for the lifetime of the context.
 
@@ -314,7 +314,7 @@ ddwaf_object obj;
 
 ddwaf_allocator alloc = ddwaf_get_default_allocator();
 
-// Preallocated and preinitialised
+// Pre-allocated and pre-initialised
 char *str = (char*)ddwaf_allocator_alloc(alloc, 16, 1);
 memcpy(str, "constant string", sizeof("constant string"));
 

From 7b7beb257c3cfd2978534c76b77a72079eacc927 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 11:04:24 +0000
Subject: [PATCH 20/32] Update changelog

---
 docs/changelog/CHANGELOG-v2.0.0.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/changelog/CHANGELOG-v2.0.0.md b/docs/changelog/CHANGELOG-v2.0.0.md
index a41d04502..29a5d71fc 100644
--- a/docs/changelog/CHANGELOG-v2.0.0.md
+++ b/docs/changelog/CHANGELOG-v2.0.0.md
@@ -9,6 +9,12 @@
 - Array indexing on key paths ([#458](https://github.com/DataDog/libddwaf/pull/458)).
 - Instantiate obfuscator through configuration and remove `ddwaf_config` ([#464](https://github.com/DataDog/libddwaf/pull/464)).
 - Return `DDWAF_MATCH` when events, attributes, or actions are present ([#455](https://github.com/DataDog/libddwaf/pull/455)).
+- Remove legacy configuration schema (v1) support ([#482](https://github.com/DataDog/libddwaf/pull/482)).
+
+### Fixes
+
+- Report input attribute addresses on `ddwaf_known_addresses` ([#485](https://github.com/DataDog/libddwaf/pull/485)).
+- Remove default allocator arguments ([#486](https://github.com/DataDog/libddwaf/pull/486)).
 
 ### Miscellaneous
 
@@ -24,7 +30,5 @@
 - Expanded fingerprint and object-view tests ([#414](https://github.com/DataDog/libddwaf/pull/414)).
 - Add fuzzer v2 ([#465](https://github.com/DataDog/libddwaf/pull/465)).
 - Update logger to avoid dependencies on `ddwaf.h` ([#453](https://github.com/DataDog/libddwaf/pull/453)).
-
-### Documentation
-
-- Consolidated configuration docs (rules, actions, processors, exclusions, conditions) and added evaluation and scanners references.
+- Achieve 100% test coverage for src/utils.cpp ([#481](https://github.com/DataDog/libddwaf/pull/481)).
+- Documentation ([#487](https://github.com/DataDog/libddwaf/pull/487)).

From e8e4879c93bef9829d3347c6b3464045c0ff9e9e Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 11:22:02 +0000
Subject: [PATCH 21/32] Example improvements

---
 README.md                          | 135 +++++++++++++++++++----------
 docs/changelog/CHANGELOG-v2.0.0.md |   3 +-
 examples/example.cpp               |  15 +++-
 3 files changed, 107 insertions(+), 46 deletions(-)

diff --git a/README.md b/README.md
index 29b7ab27c..b0397f9d5 100644
--- a/README.md
+++ b/README.md
@@ -100,28 +100,47 @@ rules:
 
 int main()
 {
+    auto alloc = ddwaf_get_default_allocator();
+
     YAML::Node doc = YAML::Load(waf_rule.data());
 
-    auto rule = doc.as<ddwaf_object>();//= convert_yaml_to_args(doc);
-    ddwaf_handle handle = ddwaf_init(&rule, nullptr, nullptr);
-    ddwaf_object_free(&rule);
+    auto rule = doc.as<ddwaf_object>();
+
+    ddwaf_builder builder = ddwaf_builder_init();
+    ddwaf_object diagnostics;
+    bool success = ddwaf_builder_add_or_update_config(builder, "config", 6, &rule, &diagnostics);
+    ddwaf_object_destroy(&rule, alloc);
+    ddwaf_object_destroy(&diagnostics, alloc);
+
+    if (!success) {
+        ddwaf_builder_destroy(builder);
+        return EXIT_FAILURE;
+    }
+
+    ddwaf_handle handle = ddwaf_builder_build_instance(builder);
+    ddwaf_builder_destroy(builder);
+
     if (handle == nullptr) {
         return EXIT_FAILURE;
     }
 
-    ddwaf_context context = ddwaf_context_init(handle);
+    ddwaf_context context = ddwaf_context_init(handle, alloc);
     if (context == nullptr) {
         ddwaf_destroy(handle);
         return EXIT_FAILURE;
     }
 
-    ddwaf_object root, tmp;
-    ddwaf_object_map(&root);
-    ddwaf_object_map_add(&root, "arg1", ddwaf_object_string(&tmp, "string 1"));
-    ddwaf_object_map_add(&root, "arg2", ddwaf_object_string(&tmp, "string 2"));
+    ddwaf_object root;
+    ddwaf_object_set_map(&root, 2, alloc);
+
+    ddwaf_object *arg1 = ddwaf_object_insert_literal_key(&root, "arg1", 4, alloc);
+    ddwaf_object_set_string_literal(arg1, "string 1", 8);
+
+    ddwaf_object *arg2 = ddwaf_object_insert_literal_key(&root, "arg2", 4, alloc);
+    ddwaf_object_set_string_literal(arg2, "string 2", 8);
 
     ddwaf_object ret;
-    auto code = ddwaf_context_eval(context, &root, nullptr, &ret, 1000000 /* microseconds */);
+    auto code = ddwaf_context_eval(context, &root, alloc, &ret, 1000000 /* microseconds */);
     std::cout << "Output second run: " << code << '\n';
     if (code == DDWAF_MATCH) {
         YAML::Emitter out(std::cout);
@@ -131,7 +150,7 @@ int main()
         out << object_to_yaml(ret);
     }
 
-    ddwaf_object_free(&ret);
+    ddwaf_object_destroy(&ret, alloc);
 
     ddwaf_context_destroy(context);
     ddwaf_destroy(handle);
@@ -151,62 +170,71 @@ struct as_if<ddwaf_object, void>
 {
     explicit as_if(const Node& node_) : node(node_) {}
 
-    static ddwaf_object yaml_to_object_helper(const Node& node)
+    static ddwaf_object yaml_to_object_helper(const Node& node, ddwaf_allocator alloc)
     {
         ddwaf_object arg;
         switch (node.Type())
         {
             case NodeType::Sequence:
-                ddwaf_object_array(&arg);
+                ddwaf_object_set_array(&arg, 0, alloc);
                 break;
             case NodeType::Map:
-                ddwaf_object_map(&arg);
+                ddwaf_object_set_map(&arg, 0, alloc);
                 break;
             case NodeType::Scalar:
-                ddwaf_object_string(&arg, node.Scalar().c_str());
+            {
+                auto scalar = node.Scalar();
+                ddwaf_object_set_string(&arg, scalar.c_str(), scalar.length(), alloc);
                 break;
+            }
             case NodeType::Null:
-                ddwaf_object_null(&arg);
+                ddwaf_object_set_null(&arg);
                 break;
             case NodeType::Undefined:
             default:
-                ddwaf_object_invalid(&arg);
+                ddwaf_object_set_invalid(&arg);
                 break;
         }
         return arg;
     }
 
-    ddwaf_object operator()() const {
-        std::list<std::tuple<ddwaf_object&, YAML::Node, YAML::Node::const_iterator>> stack;
+    ddwaf_object operator()() const
+    {
+        auto alloc = ddwaf_get_default_allocator();
+        std::list<std::tuple<ddwaf_object *, YAML::Node, YAML::Node::const_iterator>> stack;
 
-        ddwaf_object root = yaml_to_object_helper(node);
+        ddwaf_object root = yaml_to_object_helper(node, alloc);
         if (root.type == DDWAF_OBJ_MAP || root.type == DDWAF_OBJ_ARRAY) {
-            stack.emplace_back(root, node, node.begin());
+            stack.emplace_back(&root, node, node.begin());
         }
 
         while (!stack.empty()) {
             auto current_depth = stack.size();
             auto &[parent_obj, parent_node, it] = stack.back();
 
-            for (;it != parent_node.end(); ++it) {
+            for (; it != parent_node.end(); ++it) {
                 YAML::Node child_node = parent_node.IsMap() ? it->second : *it;
-                auto child_obj = yaml_to_object_helper(child_node);
-                if (parent_obj.type == DDWAF_OBJ_MAP) {
+                auto child_obj = yaml_to_object_helper(child_node, alloc);
+                ddwaf_object *child_ptr = nullptr;
+                if (parent_obj->type == DDWAF_OBJ_MAP) {
                     auto key = it->first.as<std::string>();
-                    ddwaf_object_map_add(&parent_obj, key.c_str(), &child_obj);
-                } else if (parent_obj.type == DDWAF_OBJ_ARRAY) {
-                    ddwaf_object_array_add(&parent_obj, &child_obj);
+                    child_ptr = ddwaf_object_insert_key(parent_obj, key.c_str(), key.size(), alloc);
+                    *child_ptr = child_obj;
+                } else if (parent_obj->type == DDWAF_OBJ_ARRAY) {
+                    child_ptr = ddwaf_object_insert(parent_obj, alloc);
+                    *child_ptr = child_obj;
                 }
 
                 if (child_obj.type == DDWAF_OBJ_MAP || child_obj.type == DDWAF_OBJ_ARRAY) {
-                    auto &child_ptr = parent_obj.array[parent_obj.nbEntries - 1];
                     stack.emplace_back(child_ptr, child_node, child_node.begin());
                     ++it;
                     break;
                 }
             }
 
-            if (current_depth == stack.size()) { stack.pop_back(); }
+            if (current_depth == stack.size()) {
+                stack.pop_back();
+            }
         }
         return root;
     }
@@ -228,19 +256,25 @@ YAML::Node object_to_yaml_helper(const ddwaf_object &obj)
     YAML::Node output;
     switch (obj.type) {
     case DDWAF_OBJ_BOOL:
-        output = obj.boolean;
+        output = ddwaf_object_get_bool(&obj);
         break;
     case DDWAF_OBJ_SIGNED:
-        output = obj.intValue;
+        output = ddwaf_object_get_signed(&obj);
         break;
     case DDWAF_OBJ_UNSIGNED:
-        output = obj.uintValue;
+        output = ddwaf_object_get_unsigned(&obj);
         break;
     case DDWAF_OBJ_FLOAT:
-        output = obj.f64;
+        output = ddwaf_object_get_float(&obj);
         break;
     case DDWAF_OBJ_STRING:
-        output = std::string{obj.stringValue, obj.nbEntries};
+    case DDWAF_OBJ_LITERAL_STRING:
+    case DDWAF_OBJ_SMALL_STRING:
+        {
+            size_t length;
+            const char* str = ddwaf_object_get_string(&obj, &length);
+            output = std::string{str, length};
+        }
         break;
     case DDWAF_OBJ_MAP:
         output = YAML::Load("{}");
@@ -260,7 +294,7 @@ YAML::Node object_to_yaml_helper(const ddwaf_object &obj)
 
 YAML::Node object_to_yaml(const ddwaf_object &obj)
 {
-    std::list<std::tuple<const ddwaf_object&, YAML::Node, std::size_t>> stack;
+    std::list<std::tuple<const ddwaf_object &, YAML::Node, std::size_t>> stack;
 
     YAML::Node root = object_to_yaml_helper(obj);
     if (obj.type == DDWAF_OBJ_MAP || obj.type == DDWAF_OBJ_ARRAY) {
@@ -271,21 +305,34 @@ YAML::Node object_to_yaml(const ddwaf_object &obj)
         auto current_depth = stack.size();
         auto &[parent_obj, parent_node, index] = stack.back();
 
-        for (;index <parent_obj.nbEntries; ++index) {
-            auto &child_obj = parent_obj.array[index];
-            auto child_node = object_to_yaml_helper(child_obj);
-
+        size_t size = ddwaf_object_get_size(&parent_obj);
+        for (; index < size; ++index) {
+            const ddwaf_object *child_obj = nullptr;
             if (parent_obj.type == DDWAF_OBJ_MAP) {
-                std::string key{child_obj.parameterName, child_obj.parameterNameLength};
+                child_obj = ddwaf_object_at_value(&parent_obj, index);
+                auto *key_obj = ddwaf_object_at_key(&parent_obj, index);
+                size_t key_len;
+                const char* key_str = ddwaf_object_get_string(key_obj, &key_len);
+                std::string key{key_str, key_len};
+
+                auto child_node = object_to_yaml_helper(*child_obj);
                 parent_node[key] = child_node;
+
+                if (child_obj->type == DDWAF_OBJ_MAP || child_obj->type == DDWAF_OBJ_ARRAY) {
+                    stack.emplace_back(*child_obj, child_node, 0);
+                    ++index;
+                    break;
+                }
             } else if (parent_obj.type == DDWAF_OBJ_ARRAY) {
+                child_obj = ddwaf_object_at_value(&parent_obj, index);
+                auto child_node = object_to_yaml_helper(*child_obj);
                 parent_node.push_back(child_node);
-            }
 
-            if (child_obj.type == DDWAF_OBJ_MAP || child_obj.type == DDWAF_OBJ_ARRAY) {
-                stack.emplace_back(child_obj, child_node, 0);
-                ++index;
-                break;
+                if (child_obj->type == DDWAF_OBJ_MAP || child_obj->type == DDWAF_OBJ_ARRAY) {
+                    stack.emplace_back(*child_obj, child_node, 0);
+                    ++index;
+                    break;
+                }
             }
         }
 
diff --git a/docs/changelog/CHANGELOG-v2.0.0.md b/docs/changelog/CHANGELOG-v2.0.0.md
index 29a5d71fc..feb87b3a7 100644
--- a/docs/changelog/CHANGELOG-v2.0.0.md
+++ b/docs/changelog/CHANGELOG-v2.0.0.md
@@ -1,5 +1,6 @@
-## v2.0.0-alpha0
+# v2.0.0-alpha0
 
+## Release Changelog
 ### Changes
 
 - Object model overhaul: immutable `object_view`, owned/borrowed writable objects, raw configuration on `object_view`, container view types, and updated unit tests ([#341](https://github.com/DataDog/libddwaf/pull/341), [#378](https://github.com/DataDog/libddwaf/pull/378), [#382](https://github.com/DataDog/libddwaf/pull/382), [#387](https://github.com/DataDog/libddwaf/pull/387), [#390](https://github.com/DataDog/libddwaf/pull/390), [#391](https://github.com/DataDog/libddwaf/pull/391), [#394](https://github.com/DataDog/libddwaf/pull/394), [#408](https://github.com/DataDog/libddwaf/pull/408), [#413](https://github.com/DataDog/libddwaf/pull/413)), ([#476](https://github.com/DataDog/libddwaf/pull/476)).
diff --git a/examples/example.cpp b/examples/example.cpp
index 85492fcfa..59804065e 100644
--- a/examples/example.cpp
+++ b/examples/example.cpp
@@ -205,8 +205,21 @@ int main()
     YAML::Node doc = YAML::Load(waf_rule.data());
 
     auto rule = doc.as<ddwaf_object>();
-    ddwaf_handle handle = ddwaf_init(&rule, nullptr);
+
+    ddwaf_builder builder = ddwaf_builder_init();
+    ddwaf_object diagnostics;
+    bool success = ddwaf_builder_add_or_update_config(builder, "config", 6, &rule, &diagnostics);
     ddwaf_object_destroy(&rule, alloc);
+    ddwaf_object_destroy(&diagnostics, alloc);
+
+    if (!success) {
+        ddwaf_builder_destroy(builder);
+        return EXIT_FAILURE;
+    }
+
+    ddwaf_handle handle = ddwaf_builder_build_instance(builder);
+    ddwaf_builder_destroy(builder);
+
     if (handle == nullptr) {
         return EXIT_FAILURE;
     }

From a75dfd4e984b582dd7de193c3ce90c36478a517c Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 11:33:48 +0000
Subject: [PATCH 22/32] Add v2.0.0 release notes

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/changelog/CHANGELOG-v2.0.0.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/changelog/CHANGELOG-v2.0.0.md b/docs/changelog/CHANGELOG-v2.0.0.md
index feb87b3a7..4a321b2f5 100644
--- a/docs/changelog/CHANGELOG-v2.0.0.md
+++ b/docs/changelog/CHANGELOG-v2.0.0.md
@@ -1,5 +1,25 @@
 # v2.0.0-alpha0
 
+libddwaf v2.0.0 represents a significant redesign of the C API, focusing on explicit memory ownership, reduced memory footprint, and a more consistent interface. Beyond the public API, the internals have also been refactored to use safer and more C++-native abstractions. This is an alpha release intended for early adopters and binding library maintainers to begin integration work.
+
+### Memory Ownership and Allocators
+
+The most fundamental change in v2 is the introduction of allocators throughout the API. In v1, memory ownership across the API boundary was often ambiguous, leading to potential issues in complex integration scenarios. The new allocator system makes memory ownership explicit: callers provide an allocator when creating objects and use the same allocator when destroying them. A default allocator is available via `ddwaf_get_default_allocator()` for simple use cases, while custom allocators enable advanced memory management strategies.
+
+### Object Model and Creation API
+
+The `ddwaf_object` structure has been completely redesigned to reduce memory overhead. A single object now requires only 16 bytes, down from a considerably larger footprint in v1. This was achieved through the introduction of small strings, where strings of 14 bytes or fewer are stored directly within the object without additional heap allocation, and literal strings, which reference read-only memory that is never freed by the library.
+
+Object creation functions have been renamed to follow a consistent `ddwaf_object_set_*` pattern and now require an allocator parameter where allocation may occur. Container insertion returns a pointer to the newly inserted element, eliminating the need for intermediate objects. For example, where v1 required creating a value object separately and then adding it to a map, v2 allows direct initialisation: `ddwaf_object_set_string(ddwaf_object_insert_key(&map, "key", 3, alloc), "value", 5, alloc)`. This pattern reduces boilerplate and makes the ownership model clearer.
+
+### Context and Subcontext Lifecycle
+
+The function `ddwaf_run` has been renamed to `ddwaf_context_eval` for consistency with the rest of the API. More significantly, ephemeral data semantics have been replaced with a new subcontext mechanism. In v1, ephemeral data was passed as a separate parameter to each run call and was not retained. In v2, a subcontext is explicitly created from a parent context via `ddwaf_subcontext_init`, evaluated with `ddwaf_subcontext_eval`, and destroyed with `ddwaf_subcontext_destroy`. Subcontexts inherit all persistent data from their parent context but maintain their own isolated evaluation state. Multiple concurrent subcontexts can be created from the same parent context, each defining its own data scope and lifetime.
+
+### Breaking Changes Summary
+
+Binding library maintainers should note that this release is not backwards compatible. Key migration points include: all object creation and destruction requires allocators, `ddwaf_run` is now `ddwaf_context_eval`, ephemeral data is handled through subcontexts rather than a parameter, `ddwaf_config` is removed, and `ddwaf_result_free` is replaced by `ddwaf_object_destroy` with the appropriate allocator. The upgrading guide at `docs/upgrading/UPGRADING-v2.0.md` provides detailed migration examples for each of these changes.
+
 ## Release Changelog
 ### Changes
 

From 7d843e86c3e5dc6d0930b29d9bcdf47f72358849 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 11:40:51 +0000
Subject: [PATCH 23/32] Remove WIP docs

---
 README.md                   |  48 ++++-------
 docs/actions.md             |  59 --------------
 docs/addresses.md           | 100 -----------------------
 docs/conditions.md          |  81 -------------------
 docs/exclusions.md          |  86 --------------------
 docs/operators.md           | 157 ------------------------------------
 docs/overview.md            | 150 ----------------------------------
 docs/processor_overrides.md |  47 -----------
 docs/processors.md          |  92 ---------------------
 docs/rule_data.md           |  36 ---------
 docs/rule_overrides.md      |  47 -----------
 docs/rules.md               | 142 --------------------------------
 docs/scanners.md            |  54 -------------
 docs/transformers.md        |  30 -------
 14 files changed, 17 insertions(+), 1112 deletions(-)
 delete mode 100644 docs/actions.md
 delete mode 100644 docs/addresses.md
 delete mode 100644 docs/conditions.md
 delete mode 100644 docs/exclusions.md
 delete mode 100644 docs/operators.md
 delete mode 100644 docs/overview.md
 delete mode 100644 docs/processor_overrides.md
 delete mode 100644 docs/processors.md
 delete mode 100644 docs/rule_data.md
 delete mode 100644 docs/rule_overrides.md
 delete mode 100644 docs/rules.md
 delete mode 100644 docs/scanners.md
 delete mode 100644 docs/transformers.md

diff --git a/README.md b/README.md
index b0397f9d5..b7658106a 100644
--- a/README.md
+++ b/README.md
@@ -364,37 +364,23 @@ rules:
 ```
 
 applied to the `http.server.query` value `http://localhost/?q=<script>alert() hello world` produces the following result:
-```json
-[
-  {
-    "rule": {
-      "id": "crs-042-001",
-      "name": "Detect a script tag",
-      "tags": {
-        "category": "attack_attempt",
-        "type": "xss"
-      }
-    },
-    "rule_matches": [
-      {
-        "operator": "match_regex",
-        "operator_value": "^<script>",
-        "parameters": [
-          {
-            "address": "http.server.query",
-            "key_path": [
-              "q"
-            ],
-            "value": "<script>alert() hello world",
-            "highlight": [
-              "<script>"
-            ]
-          }
-        ]
-      }
-    ]
-  }
-]
+```yaml
+- rule:
+    id: crs-042-001
+    name: Detect a script tag
+    tags:
+      category: attack_attempt
+      type: xss
+  rule_matches:
+    - operator: match_regex
+      operator_value: ^<script>
+      parameters:
+        - address: http.server.query
+          key_path:
+            - q
+          value: <script>alert() hello world
+          highlight:
+            - <script>
 ```
 
 ## Binding implementation notes
diff --git a/docs/actions.md b/docs/actions.md
deleted file mode 100644
index ea1e9c955..000000000
--- a/docs/actions.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# Actions Catalogue
-
-Actions describe what the host should do when a rule matches. They are defined in the optional top-level `actions` array of a configuration and are referenced by rules via their `on_match` field.
-
-## Action schema
-
-Each entry in `actions` uses this shape:
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `id` | string | yes | Identifier referenced by `on_match`. Must be unique across the configuration. |
-| `type` | string | yes | One of `block_request`, `redirect_request`, `monitor`, `generate_stack`, `generate_schema`, or a custom type understood by the host application. |
-| `parameters` | object | yes | Free-form parameters passed through to the action mapper and on to the host/caller. |
-
-## Built-in defaults
-
-libddwaf always exposes a baseline catalogue, even if the `actions` array is omitted:
-
-- `block` (alias of `block_request`) with defaults: `status_code=403`, `grpc_status_code=10`, `type=auto`.
-- `monitor` (no parameters).
-- `stack_trace` (`generate_stack`).
-- `extract_schema` (`generate_schema`).
-
-You can override these by redefining their IDs in `actions`, or add new entries for custom behaviour.
-
-## Action types
-
-### `block_request`
-
-Signals that the request should be blocked. Parameters:
-
-- `status_code` (optional): HTTP status to emit; any 3-digit code is accepted. Defaults to `403` if missing or invalid.
-- `grpc_status_code` (optional): gRPC status (unsigned) to emit; defaults to `10` if missing or invalid.
-- `type` (optional): transport hint (for example `auto`).
-
-Missing parameters are populated from the built-in `block` defaults. Reserved parameters `security_response_id` and `stack_id` are stripped.
-
-### `redirect_request`
-
-Instructs the caller to respond with an HTTP redirect. Parameters:
-
-- `location` (string, required): absolute or root-anchored URL to redirect to.
-- `status_code` (optional): one of `301`, `302`, `303`, or `307`. Defaults to `303` if absent or invalid.
-
-The parser validates the URL scheme (`http`/`https`) and ensures relative redirects start with `/`. When validation fails, the action is replaced by the default `block_request`. Reserved parameters `security_response_id` and `stack_id` are stripped.
-
-### `monitor`
-
-Instructs the caller to log/monitor without blocking. Parameters: none. Always emits the `monitor` action ID. Reserved parameters are stripped.
-
-### `generate_stack`
-
-Requests a stack trace capture. Parameters:
-
-- `stack_id` (string, optional): identifier for the captured stack. Other parameters are ignored. Reserved parameters are stripped.
-
-### `generate_schema`
-
-Requests schema generation for the current request data. Parameters: none; any provided values are passed through to the host. Reserved parameters are stripped.
diff --git a/docs/addresses.md b/docs/addresses.md
deleted file mode 100644
index 1dd7c8776..000000000
--- a/docs/addresses.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# Address Reference
-
-This page lists the Application Security Management (ASM) addresses that libddwaf understands. Addresses represent the structured inputs that processors, filters, and rules consume. The canonical rule packs that reference these addresses live in [`appsec-event-rules`](https://github.com/DataDog/appsec-event-rules/blob/main/build/recommended.json).
-
----
-
-## HTTP Request & Response Addresses
-
-| Address | Type | Description / Notes | Example |
-| --- | --- | --- | --- |
-| `server.request.body` | Native value (framework-specific) | Parsed HTTP request body as exposed by the framework. See the dedicated `server.request.body` binder documentation for language-specific nuances. | *(varies)* |
-| `server.request.body.filenames` | Array | Filenames supplied through RFC-1867 HTML file uploads. Each entry reflects the original client filename. | `["invoice.pdf", "avatar.png"]` |
-| `server.request.body.files_field_names` | Array | Form field names associated with uploaded files (RFC-1867). | `["attachment", "photo"]` |
-| `server.request.query` | Native value | Framework-parsed query string (can contain duplicate keys). In .NET a query such as `?test&[$slice]` keeps all keys. | `{ "test": "", "[$slice]": "" }` |
-| `server.request.headers.no_cookies` | Headers object | Incoming headers with cookie-related fields removed. Header keys must be lowercase. | `{ "x-forwarded-for": "1.2.3.4", "user-agent": "Moustache" }` |
-| `server.request.trailers` | Headers object | HTTP trailing headers. | `{ "grpc-status": "0" }` |
-| `server.request.uri.raw` | String | Relative URI (path and query, without scheme or authority). | `/path/bla.php?param1=a&param2=b%20c` |
-| `server.request.method` | String | HTTP method. | `"GET"` |
-| `server.request.path_params` | Native value | Framework-parsed path parameters (e.g. `/foo/:id` yields `{ id: 123 }`). | `{ "id": "42" }` |
-| `server.request.cookies` | Cookies map | Cookies parsed by the framework. AppSec obfuscation operates on keys and values as needed. | `{ "password": ["1234"], "foo": ["bar", "baz"] }` |
-| `server.response.status` | String | HTTP response status code. | `"404"` |
-| `server.response.headers.no_cookies` | Headers object | Outgoing headers without any `Set-Cookie` entries. | `{ "content-type": "application/json" }` |
-| `http.client_ip` | String | Client IP determined by the Datadog client IP resolution policy. | `"203.0.113.10"` |
-
----
-
-## Exploit Prevention Addresses
-
-| Address | Type | Description |
-| --- | --- | --- |
-| `server.io.fs.file` | String | File paths analysed by local file inclusion (LFI) rules. |
-| `server.io.net.url` | String | URLs analysed by server-side request forgery (SSRF) rules. |
-| `server.db.statement` | String | SQL statements inspected by SQL injection rules. |
-| `server.db.system` | String | SQL dialect associated with `server.db.statement` (see APM span attribute `db.system`). |
-| `server.sys.shell.cmd` | String or array (≥ v1.20.1) | Shell commands analysed by command/remote code injection rules. |
-
----
-
-## User Monitoring Addresses
-
-| Address | Type | Description |
-| --- | --- | --- |
-| `usr.id` | String | User identifier captured automatically or via the SDK. |
-| `usr.session_id` | String | Session identifier associated with the current request or user. |
-
----
-
-## Business Logic Addresses
-
-| Address | Type | Description |
-| --- | --- | --- |
-| `server.business_logic.users.login.success` | Null | Event marker indicating a successful login. |
-| `server.business_logic.users.login.failure` | Null | Event marker indicating a failed login. |
-
----
-
-## Virtual & Auxiliary Addresses
-
-| Address | Type | Description |
-| --- | --- | --- |
-| `waf.context.event` | Null | Internally generated when an event is triggered; used to gate postprocessors. |
-| `waf.context.processor` | Map | Flags enabling processor-dependent features (for example schema extraction). | `{ "extract-schema": true }` |
-
----
-
-## gRPC Server Addresses
-
-| Address | Type | Description / Notes | Occurrences per RPC | Example |
-| --- | --- | --- | --- | --- |
-| `grpc.server.method` | String | Fully qualified RPC name of the form `/$package.$service/$method`. Must match the APM span tag `rpc.grpc.full_method`. | 1 (all RPC types) | `"/my.package.Greeter/SayHello"` |
-| `grpc.server.request.message` | Native value | Parsed inbound message payload. Provide as ephemeral data per message for streaming RPCs. | Unary: 1<br>Client stream: N<br>Server stream: 1<br>Bidirectional: N | `{ "user": { "id": "42" } }` |
-| `grpc.server.request.metadata` | Native string kv map | Client request metadata (headers). Keys must be lowercase; binary keys (`*-bin`) should be base64 encoded. | 0 or 1 (all RPC types) | `{ "user-agent": ["grpc-go/1.58.0"] }` |
-| `grpc.server.response.message` | Native value | Parsed outbound message payload generated by the server. Provide as ephemeral data per message for streaming RPCs. | Unary: 1<br>Client stream: 1<br>Server stream: N<br>Bidirectional: M | `{ "status": "OK", "score": 0.97 }` |
-| `grpc.server.response.metadata.headers` | Native string kv map | Initial response metadata returned before the first message. | 0 or 1 (all RPC types) | `{ "content-type": ["application/grpc+proto"] }` |
-| `grpc.server.response.metadata.trailers` | Native string kv map | Trailing response metadata sent after the final message. | 0 or 1 (all RPC types) | `{ "grpc-message": ["permission denied"] }` |
-| `grpc.server.response.status` | Number | Canonical gRPC status code (see [grpc/grpc status codes](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md)). | 1 (all RPC types) | `7` |
-
----
-
-## GraphQL Server Addresses
-
-| Address | Type | Description / Notes | Occurrences per Request | Example |
-| --- | --- | --- | --- | --- |
-| `graphql.server.all_resolvers` | Array of resolver objects | Full collection of resolver payloads captured after the GraphQL layer executes. Typically mirrors the HTTP body content but structured per resolver. | 1 aggregated payload | `[{"path":["Query","product"],"arguments":{"id":"123"},"value":"..."}, {"path":["Product","reviews"],"arguments":{},"value":[...] }]` |
-| `graphql.server.resolver` | Native value | Resolver payload emitted as each resolver executes. Shape is instrumentation-specific and usually matches a single entry inside `graphql.server.all_resolvers`. | Number of resolvers executed | `{ "path": ["Query","product"], "arguments": { "id": "123" }, "value": "..." }` |
-
-GraphQL payloads generally arrive as part of the HTTP request body before the GraphQL-specific addresses are emitted. libddwaf deduplicates matches across addresses, so a single attack surface only triggers one event even if it appears in both `server.request.body` and a GraphQL address. In practice, GraphQL rule matches surface on the HTTP body address.
-
----
-
-## Types and Conventions
-
-- **Headers object**: Use the framework’s native header representation as long as keys are lowercased (e.g. `X-Forwarded-For` → `x-forwarded-for`).
-- **Native string kv map**: Map of lowercase string keys to arrays of strings, as used by gRPC metadata. Binary keys ending with `-bin` must use base64-encoded values.
-- **Native value**: A value in the language/framework’s natural representation. The same address may look different across runtimes; the WAF only relies on the logical content (strings, numbers, collections).
-- **Resolver object**: Instrumentation-defined GraphQL resolver payload that usually includes resolver path, arguments, and the resolved value. Resolvers supplied individually and within `graphql.server.all_resolvers` must use the same structure.
-- **Cookies map**: A map of cookie names to their values as parsed by the HTTP framework. Values may be strings or arrays of strings depending on language support.
-- **Sensitive data obfuscation**: Cookie maps and header objects are scanned by the generic AppSec obfuscator. Keys matching sensitive names (for example `Bearer`) will have their values redacted in emitted events.
-
-These conventions ensure libddwaf can evaluate requests consistently across agents and frameworks while still allowing each integration to map its native data structures to the addresses used by Datadog’s managed rules.
diff --git a/docs/conditions.md b/docs/conditions.md
deleted file mode 100644
index 30b3557a8..000000000
--- a/docs/conditions.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# Condition Schema
-
-Conditions are the common building block used by rules, processors, and exclusion filters. Each component embeds a `conditions` array that forms a logical expression evaluated against the current request data. The parser for these expressions lives in `src/configuration/common/expression_parser.cpp` and is shared across configuration types.
-
-## Expression semantics
-
-- The `conditions` array represents a conjunction: entries are evaluated in order until one fails; if all succeed the expression is `true`. An empty array implicitly evaluates to `true`.
-- Results are cached per context. Once a condition has matched a given object, subsequent evaluations in the same request skip the work unless new input appears.
-- All operators documented in the [Operator Reference](operators.md) are valid inside any expression. Processor and exclusion expressions are parsed with the same rules as rule expressions.
-
-## Condition object
-
-Every element in the `conditions` array has the same top-level shape:
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `operator` | string | yes | Name of the matcher to run (for example `match_regex`, `phrase_match`, `exists`). Operators that carry a schema version use the `name@vN` suffix (for example `ssrf_detector@v1`). |
-| `parameters` | object | yes | Operator-specific parameters plus the argument mappings (see below). |
-
-The exact keys inside `parameters` depend on the operator. Scalar matchers such as `equals`, `match_regex`, `ip_match`, `phrase_match`, `greater_than`, and `lower_than` require a `value` and `type` (or a `regex`/`list`/`data` depending on the matcher) in addition to their inputs. Complex detectors such as `ssrf_detector` also accept `options` and `policy` blocks. Refer to the operator documentation for the full list of supported keys per matcher.
-
-## Mapping inputs to a condition
-
-Most operators accept an `inputs` argument under `parameters`. Each entry in `inputs` maps one address from the request (or derived data) into the operator:
-
-| Key | Type | Required | Description |
-| --- | --- | --- | --- |
-| `address` | string | yes | The address to inspect, such as `server.request.query`, `server.request.body`, or `_dd.appsec.fp.http.endpoint`. |
-| `key_path` | array of string/int | no | Optional navigation into nested maps or arrays. Strings address map keys; integers address array indices. Use `"*"` as a wildcard segment. |
-| `transformers` | array of strings | no | Overrides the transformer chain for this input. At most 10 entries. When omitted, the expression-level transformers (rule-level) apply. |
-
-Inputs are ordered; non-variadic operators accept exactly one entry while variadic ones consume every entry in the list. The accepted argument names (`inputs`, `value`, etc.) come from the operator signature; for example the `exists` operator only accepts `inputs` while structured detectors may name their arguments differently.
-
-### Data source and transformers
-
-- By default expressions read **values** from each address. If a rule-level `transformers` array includes the sentinel `keys_only`, the condition walks map keys instead. The sentinel `values_only` restores the default. These sentinels are ignored for processors and exclusions because they do not carry a rule-level transformer list.
-- Per-input `transformers` replace the rule-level chain for that target and always operate on values. When present, the data source for that input is forced back to values even if `keys_only` was declared at the rule level.
-- Transformer identifiers are listed in the [Transformer Reference](transformers.md).
-
-## Putting it together
-
-Rule, processor, and exclusion configurations all embed conditions using the schema above. Examples:
-
-- **Rule condition** that matches a numeric status code:  
-  ```json
-  {
-    "operator": "equals",
-    "parameters": {
-      "inputs": [{ "address": "server.response.status" }],
-      "type": "unsigned",
-      "value": 403
-    }
-  }
-  ```
-- **Processor gate** controlled by a context flag:  
-  ```json
-  {
-    "operator": "equals",
-    "parameters": {
-      "inputs": [
-        { "address": "waf.context.processor", "key_path": ["fingerprint"] }
-      ],
-      "type": "boolean",
-      "value": true
-    }
-  }
-  ```
-- **Exclusion filter** applied when the request path contains `/health`:  
-  ```json
-  {
-    "operator": "match_regex",
-    "parameters": {
-      "inputs": [
-        { "address": "server.request.uri.raw", "transformers": ["lowercase"] }
-      ],
-      "regex": "/health(/|$)"
-    }
-  }
-  ```
-
-Whichever component owns the `conditions` array determines how the expression is used—rules treat it as the match logic for detection, processors as an execution gate, and exclusions as the predicate for muting or pruning. The underlying schema and evaluation semantics remain the same.
diff --git a/docs/exclusions.md b/docs/exclusions.md
deleted file mode 100644
index 5a928ed1e..000000000
--- a/docs/exclusions.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# Exclusion Filters
-
-Exclusions refine how rules respond to specific traffic without editing the rules themselves. Two flavours exist:
-
-- **Rule exclusions** change the verdict of matching rules.
-- **Input exclusions** remove request fields from rule evaluation while leaving the rule active.
-
-Both live in the `exclusions` array of a configuration and share the same top-level shape.
-
-## Shared schema
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `id` | string | yes | Unique identifier for diagnostics and deduplication. |
-| `min_version`, `max_version` | semantic version | no | Restrict the exclusion to specific libddwaf versions. |
-| `conditions` | array | no | Expression evaluated against request data. See the [Condition schema](conditions.md). Omit for unconditional exclusions. |
-| `rules_target` | array | no | List of rules to affect. Entries may include `rule_id`/`id` (exact match) or `tags` for tag-based selection. Omit to target all rules. |
-
-At least one of `conditions`, `rules_target`, or `inputs` (for input exclusions) must be provided; otherwise the entry is rejected.
-
-## Rule exclusions
-
-Additional field:
-
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `on_match` | string | no | Outcome when the exclusion triggers: `bypass` (default, skip rule entirely), `monitor` (force monitor verdict), or a custom action ID from the [action catalogue](actions.md). |
-
-Use rule exclusions to silence noisy rules, force monitoring, or reroute matches to a custom action.
-
-### Example
-
-```json
-{
-  "id": "skip-log4shell-on-backend",
-  "conditions": [
-    {
-      "operator": "match_regex",
-      "parameters": {
-        "inputs": [{ "address": "server.address" }],
-        "regex": "^10\\."
-      }
-    }
-  ],
-  "rules_target": [{ "rule_id": "log4shell" }],
-  "on_match": "bypass"
-}
-```
-
-## Input exclusions
-
-Additional field:
-
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `inputs` | array | yes | Addresses (and optional key paths) to remove from rule evaluation when the exclusion matches. |
-
-Each entry inside `inputs` accepts:
-
-| Key | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `address` | string | yes | Address to prune (for example `server.request.query`). |
-| `key_path` | array of strings | no | Navigate into nested structures; use `"*"` as a wildcard. Omit to remove the entire address. Missing segments are treated as wildcards. |
-
-Input exclusions let rules keep running but with sensitive or noisy fields removed.
-
-### Example
-
-```json
-{
-  "id": "ignore-debug-parameter",
-  "inputs": [
-    { "address": "server.request.query", "key_path": ["debug"] }
-  ],
-  "rules_target": [
-    { "tags": { "type": "security_scanner" } }
-  ]
-}
-```
-
-## Evaluation notes
-
-- Unique `id` values are enforced. Entries with incompatible version bounds are skipped.
-- Exclusions run before rule evaluation. The first match is memoised for the rest of the request to keep lookups fast.
-- Rule exclusions decide the final verdict (`bypass`, `monitor`, or custom action). Input exclusions prune data and allow the rule to produce a normal outcome on the reduced input.
-- Combine exclusions with rule `on_match` actions to tune blocking/monitoring decisions without modifying the rule logic.
diff --git a/docs/operators.md b/docs/operators.md
deleted file mode 100644
index 2b5332793..000000000
--- a/docs/operators.md
+++ /dev/null
@@ -1,157 +0,0 @@
-# Operator Reference
-
-Libddwaf supports a mixture of low-level “scalar” match operators and higher-level detectors that encapsulate complex heuristics. This document enumerates each of the available operators, together with the arguments they expect.
-
----
-
-## Scalar match operators
-
-These operators compare request data against literal values, numerical thresholds, or pattern libraries. They are implemented in `src/matcher/*` and are available both in positive form (`operator`) and negated form (`!operator`) unless noted.
-
-### `equals`
-- **Purpose:** Compare a value to a literal.
-- **Arguments:**  
-  - `type`: `"string"`, `"boolean"`, `"unsigned"`, `"signed"`, or `"float"`.  
-  - `value`: literal to compare against.  
-  - `delta` (optional, floats only): tolerance when comparing floating point numbers.
-- **Notes:** Supports negation (`!equals`) which must be scoped to a single address and / or key path.
-
-### `exact_match`
-- **Purpose:** Match against a list of exact strings.
-- **Arguments:**  
-  - `inputs`.  
-  - Either `list` (array of strings) or `data` (rules-data identifier, mutually exclusive).
-- **Notes:** Works on string inputs only; negated form `!exact_match` is supported.
-
-### `greater_than`
-- **Purpose:** Numeric greater-than comparison.
-- **Arguments:**  
-  - `inputs`.  
-  - `type`: `"unsigned"`, `"signed"`, or `"float"`.  
-  - `value`: comparison threshold.
-- **Notes:** No direct `!greater_than` variant exists; use `lower_than`/`equals` to express the complementary logic.
-
-### `lower_than`
-- **Purpose:** Numeric less-than comparison.
-- **Arguments:**  
-  - `inputs`.  
-  - `type`: `"unsigned"`, `"signed"`, or `"float"`.  
-  - `value`: comparison threshold.
-- **Notes:** No direct `!lower_than` matcher exists; use `greater_than`/`equals` to cover the opposite condition.
-
-### `match_regex`
-- **Purpose:** Evaluate a RE2 regular expression.
-- **Arguments:**  
-  - `inputs`.  
-  - `regex`: pattern string.  
-  - `options` (optional map):  
-    - `min_length` (non-negative integer).  
-    - `case_sensitive` (boolean, defaults to `false`).
-- **Notes:** Negation `!match_regex` is available.
-
-### `match_regex_with_checksum`
-- **Purpose:** Run a regular expression alongside a checksum gate.
-- **Arguments:**  
-  - `inputs`.  
-  - `regex`: pattern string.  
-  - `checksum`: expected checksum identifier; compiled via `checksum_builder`.  
-  - `options` (optional): `min_length`, `case_sensitive`.
-- **Notes:** Negated form `!match_regex_with_checksum` is supported. Useful for large pattern sets where checksum pre-filtering trims evaluation cost.
-
-### `phrase_match`
-- **Purpose:** Fast multi-string search using the Aho–Corasick algorithm.
-- **Arguments:**  
-  - `inputs`.  
-  - `list`: array of phrases.  
-  - `options.enforce_word_boundary` (optional boolean) to require matches on word boundaries.
-- **Notes:** Negation `!phrase_match` is supported.
-
-### `ip_match`
-- **Purpose:** Match values against IP addresses or CIDR ranges.
-- **Arguments:**  
-  - `inputs`.  
-  - Either `list` (array of IP/CIDR strings) or `data` (rules-data identifier).  
-  - Optional transformers may normalise header values before matching.
-- **Notes:** Negated form `!ip_match` is supported. Lists are parsed into a radix tree internally.
-
-### `is_xss`
-- **Purpose:** Detect cross-site scripting payloads using libinjection.
-- **Arguments:** `inputs`.
-- **Notes:** Only the positive matcher is available; there is no `!is_xss`.
-
-### `is_sqli`
-- **Purpose:** Detect SQL injection payloads using libinjection.
-- **Arguments:** `inputs`.
-- **Notes:** Only the positive matcher is available; there is no `!is_sqli`.
-
-### `hidden_ascii_match`
-- **Purpose:** Flag strings containing hidden or non-printable ASCII characters.
-- **Arguments:** `inputs`.
-- **Notes:** Only the positive matcher is available; there is no `!hidden_ascii_match`.
-
-### `exists` / `!exists`
-- **Purpose:** Assert the presence (`exists`) or absence (`!exists`) of addresses.
-- **Arguments:**  
-  - `exists`: `inputs` (variadic). Returns `true` as soon as any address resolves; key paths are traversed so nested lookups honour the provided selectors.  
-  - `!exists`: `inputs` (exactly one). Returns `true` only when the address cannot be resolved.
-- **Notes:** Implemented as scalar conditions; the negated form must target a single address.
-
----
-
-## Detector operators
-
-Detector operators combine multiple signals and heuristics. They are versioned: a rule can request a specific revision using the `operator@vN` syntax, but the engine enforces the maximum version compiled into libddwaf (see the `version` constant in each detector).
-
-### `lfi_detector` (≤ v2)
-- **Purpose:** Detect local file inclusion attempts.
-- **Arguments:**  
-  - `resource`: unary argument pointing to the resolved filesystem path (for example, the file ultimately accessed).  
-  - `params`: variadic argument listing user-controlled inputs that contributed to the path.
-- **Behaviour:** Validates that user input is not escaping directories or forging absolute paths. Handles Unix and Windows path semantics.
-
-### `ssrf_detector` (≤ v3)
-- **Purpose:** Detect server-side request forgery attempts.
-- **Arguments:**  
-  - `resource`: the outbound URL being fetched.  
-  - `params`: request parameters associated with that URL.  
-  - `options` (optional map):  
-    - `authority-inspection` (bool, default `true`).  
-    - `path-inspection` (bool, default `false`).  
-    - `query-inspection` (bool, default `false`).  
-    - `forbid-full-url-injection` (bool, default `false`).  
-    - `enforce-policy-without-injection` (bool, default `false`).  
-  - `policy` (optional map):  
-    - `allowed-schemes` (array of scheme strings; defaults to `["https","http","ftps","ftp"]`).  
-    - `forbidden-domains` (array; defaults provided in the header).  
-    - `forbidden-ips` (array; defaults include RFC1918, loopback, and cloud metadata ranges).
-- **Behaviour:** Normalises the destination URL, evaluates it against the policy (schemes, domains, IPs), and inspects user parameters for full-URL injections.
-
-### `sqli_detector` (≤ v3)
-- **Purpose:** Detect SQL injection by analysing the concrete query and bound parameters.
-- **Arguments:**  
-  - `resource`: SQL statement emitted by the application.  
-  - `params`: parameters interpolated into the statement.  
-  - `db_type`: string identifying the SQL dialect (`mysql`, `pgsql`, `sqlite`, etc.).
-- **Behaviour:** Tokenises the query, strips literals, and inspects parameter tokens for tautologies, comment abuse, or structural anomalies given the specified dialect.
-
-### `shi_detector` (≤ v1)
-- **Purpose:** Detect shell injection across command invocations.
-- **Arguments:**  
-  - `resource`: shell command (string or array of tokens).  
-  - `params`: user-controlled arguments being appended to the command.
-- **Behaviour:** Tokenises both the base command and parameters, looking for injected commands or dangerous expansions (for example, `;`, `&&`, subshell operators). Supports string or array representations of the command.
-
-### `cmdi_detector` (≤ v1)
-- **Purpose:** Detect command injection patterns in command-line executions.
-- **Arguments:**  
-  - `resource`: executable path or command string captured from the application.  
-  - `params`: user-provided arguments.
-- **Behaviour:** Identifies attempt to append shell directives or bypass argument escaping by understanding known shell option formats (for Bash, PowerShell, etc.) and highlighting injected payloads.
-
----
-
-## Operator negation
-
-Only the scalar match operators `equals`, `exact_match`, `match_regex`, `match_regex_with_checksum`, `phrase_match`, and `ip_match` expose a dedicated negated variant prefixed with `!`—for example, `!match_regex` or `!ip_match`. Those negated operators accept exactly one address and invert the underlying predicate. Detector operators (`*_detector`) and the remaining scalar matchers do **not** provide negated forms; use complementary positive operators if alternative behaviour is needed.
-
-When combining operators, remember that each address may declare transformers and that the global condition applies them in the order specified in the rule definition.
diff --git a/docs/overview.md b/docs/overview.md
deleted file mode 100644
index 516437806..000000000
--- a/docs/overview.md
+++ /dev/null
@@ -1,150 +0,0 @@
-Libddwaf is Datadog's security data analysis engine, used to evaluate request, response and arbitrary instrumentation data in order to identify events of different security categories, such as WAF, RASP, API Security, Business logic, etc.
-
-Primitives
-
-Execution Pipeline
-
-Configuration
-
-
-
-
-libddwaf is Datadog's embeddable security engine. It ingests a declarative security configuration (rules, exclusions, processors, actions) and exposes a compact C API that any tracer or agent can use to evaluate inbound requests. At runtime the library:
-
-1. Parses one or more configurations into an immutable **WAF handle** (`ddwaf_handle`).
-2. Creates per-request **contexts** (`ddwaf_context`) bound to the handle and a memory allocator.
-3. Accepts request metadata as a tree of `ddwaf_object` values keyed by semantic **addresses** such as `server.request.body` or `http.client_ip`.
-4. Produces structured matches, derived attributes, and actions when rules trigger.
-
-The evaluation pipeline is incremental. Each call to `ddwaf_context_eval` updates the context with new data, derives additional inputs, applies exclusions, evaluates rules, and finally runs any post processing steps before returning results.
-
----
-
-## Execution Pipeline
-
-When a context receives new data, libddwaf processes it in a fixed order:
-
-1. **Preprocessors** enrich or rewrite the input map, often normalising raw user input into structured addresses used by rules.
-2. **Exclusion filters** decide which rules or inputs must be ignored for this evaluation (for example to suppress alerts on known-safe endpoints).
-3. **Rules** run matchers against the current address store and queue actions and events when they trigger.
-4. **Postprocessors** run after rule evaluation to augment the result payload—typically by calculating additional attributes or serialising payloads for downstream systems.
-5. The serializer aggregates matches, actions, derived attributes, and timeout information into the `result` object returned by `ddwaf_context_eval`.
-
-Any step can terminate early if the caller's timeout elapses; in that case the engine short-circuits remaining work while preserving as much partial state as possible.
-
----
-
-## Configuration Primitives
-
-### Rules
-
-Rules define the core detection logic. Each rule carries:
-
-- Metadata (`id`, `name`, and `tags`) that identifies its purpose and target module.
-- One or more **conditions**, each of which applies an operator (such as `match_regex`, `phrase_match`, or `validate_schema`) to a set of addresses. Conditions may also specify key paths and transformers.
-- Optional **actions** or overrides that tell integrating products how to respond when the rule matches.
-
-Rules are grouped by **module** internally (for example `network-acl`, `business-logic`, `waf`). Modules isolate specialised detection logic and let the engine maintain separate matcher caches. Each module sorts its rules first by the verdict they can emit (`block` before `monitor`), then by the rule **source** (user vs. Datadog) according to the precedence defined for that module (see *Module ordering and deadlines* below), and finally by the rule "type" string when applicable. If a rule returns a blocking verdict the module stops evaluating further rules, avoiding duplicate work once a decisive outcome is known. Monitor-level matches still allow evaluation to continue so other informative events can be collected.
-
-### Processors: Preprocessors and Postprocessors
-
-Processors are reusable pieces of logic that transform request data. Each entry in the `processors` section of the configuration specifies a `generator` (for example `uri_parse`, `extract_schema`, `jwt_decode`, or `fingerprint`), optional conditions, and a set of input/output mappings.
-
-Two booleans determine when a processor runs:
-
-- `evaluate: true` marks a **preprocessor**. It runs before exclusions and rules, and any derived addresses are available to matchers in the same evaluation. Typical use cases include decomposing URLs, parsing JWTs, or generating request fingerprints.
-- `output: true` marks a **postprocessor**. It runs after rules complete and can emit additional attributes into the result object—for example to expose the parsed URI or schema extraction summaries to telemetry pipelines.
-
-A single processor can act as both a pre- and postprocessor by setting both flags.
-
-Processors are cached per context so expensive computations are only repeated when their inputs change. They can also depend on **scanners**, which provide auxiliary data (for example known good fingerprints) to generator implementations.
-
-Processor expressions gate execution; optional inputs trigger re-evaluation only when new data appears. The deadline is honoured; a timeout aborts remaining processors in that phase.
-
-### Exclusion Filters
-
-Exclusion filters allow operators to silence noisy rules or drop inputs that should not be considered during evaluation. The configuration distinguishes two flavours:
-
-- **Rule filters** decide whether entire rules (or groups of rules identified by tags) should be skipped. They can bypass a rule, force monitor, or override the action to a custom value. They often key off request metadata such as the current service, endpoint, or environment.
-- **Input filters** remove or redact specific addresses (with optional key paths) before rules see them. Pruned inputs are invisible to matching and transformers. They are useful to shield sensitive fields from inspection or to ignore known benign payloads that would otherwise trigger false positives.
-
-Both filter types execute before rule evaluation, and their decisions are cached so later calls within the same context remain consistent. The combined `exclusion_policy` is consulted for every rule before evaluation to apply bypass/monitor/custom verdicts and input pruning.
-
----
-
-## Evaluation Flow
-
-This section provides implementation-level detail on how `evaluation_engine` runs processors, exclusions, and rules during `ddwaf_context_eval`, based on `evaluation_engine.cpp`, `module.cpp`, and the module builder.
-
-### Pipeline Overview
-
-1. **Skip if no new inputs**: if the `object_store` has no new targets, return immediately.
-2. **Preprocessors**: run in configured order, populating derived addresses. Each processor has a per-instance cache keyed by its pointer.
-3. **Filters**: evaluate rule filters then input filters. Matches populate an `exclusion_policy` (bypass/monitor/custom action, plus input pruning) used by rules.
-4. **Rules**: walk modules in fixed order (below). Blocking verdicts short-circuit the rest of the module set; monitor verdicts allow continued evaluation.
-5. **Postprocessors**: always run after rules; they may add attributes but never affect matching.
-6. **Serialize**: gather events, actions, attributes, and obfuscation into the result. If any rule fired, the engine injects `waf.context.event` so postprocessors can gate on it.
-
-Processor, filter, and rule caches persist across evaluations so repeated data does not trigger repeated work.
-
-### During a Single Evaluation
-
-- The incoming `ddwaf_object` map is handed to preprocessors (`evaluate: true` processors) which can create or rewrite addresses. Their outputs become part of the context store.
-- Rule and input exclusion filters run next, pruning the address set or muting matching rules before any detection logic executes.
-- The engine iterates through the modules in fixed order (`network-acl`, `authentication-acl`, `custom-acl`, `configuration`, `business-logic`, `rasp`, `waf`). The first two modules are non-expiring and always run to completion; the remaining modules respect the caller's timeout.
-- Inside each module, rules are ordered by verdict, source precedence (user vs. Datadog), and optionally type. If a rule returns a blocking verdict the module stops and subsequent modules are skipped; monitor verdicts allow evaluation to continue.
-- Once the module loop finishes (or short-circuits), postprocessors (`output: true` processors) enrich the collector with derived attributes that will appear in the result payload.
-- The serializer produces the final `result` object: matches, actions, derived attributes, execution metadata, and the `DDWAF_OK`/`DDWAF_MATCH` status that the caller receives.
-
-This sequencing keeps the evaluation deterministic while allowing preprocessors, filters, and postprocessors to cooperate around the shared context state.
-
-### Module Ordering and Deadlines
-
-Modules run in this fixed sequence (`module_category.hpp`). Each module sorts rules by verdict first (`block` before `monitor`) and then by source (Datadog vs. user) according to the policy below. A blocking rule stops the module; a monitor rule records a monitor verdict and lets evaluation continue.
-
-1. **`network-acl`** *(non-expiring)*  
-   - Ordering: Datadog before user.  
-   - Deadline: ignored; always runs to completion.
-2. **`authentication-acl`** *(non-expiring)*  
-   - Ordering: Datadog before user.  
-   - Deadline: ignored; always runs to completion.
-3. **`custom-acl`**  
-   - Ordering: user before Datadog.  
-   - Deadline: enforced.
-4. **`configuration`**  
-   - Ordering: user before Datadog.  
-   - Deadline: enforced.
-5. **`business-logic`**  
-   - Ordering: user before Datadog.  
-   - Deadline: enforced.
-6. **`rasp`**  
-   - Ordering: Datadog before user.  
-   - Deadline: enforced.
-7. **`waf`** *(collection-based)*  
-   - Collections: grouped by `tags.type`, verdict, and source in this order: user `block`, Datadog `block`, user `monitor`, Datadog `monitor`.  
-   - Caching: each collection caches its verdict; collections already satisfied at the same or higher verdict are skipped on later evaluations.  
-   - Execution: within a collection, rules run sequentially until one matches or the deadline expires. A `block` result stops remaining collections and modules; a `monitor` result records the verdict and moves to the next collection to gather more context.  
-   - Deadline: enforced.
-
----
-
-## Putting It All Together
-
-A minimal integration typically follows these steps:
-
-1. **Load configuration**: parse the JSON/YAML configurations describing rules, processors, exclusions, and overrides into `ddwaf_object` instances, then call `ddwaf_init` (or drive the builder API for multi-configuration workflows).
-2. **Create a context per request**: obtain an allocator (`ddwaf_get_default_allocator` or a custom one) and call `ddwaf_context_init`.
-3. **Populate addresses**: build a map of request data (`ddwaf_object_set_map` plus insertion helpers) covering the addresses referenced by your rules and preprocessors.
-4. **Evaluate**: call `ddwaf_context_eval` with the map, allocator, an optional result object, and a timeout. Inspect `DDWAF_MATCH` or `DDWAF_OK`, along with the populated `events`, `actions`, and `attributes`.
-5. **Clean up**: destroy the result with `ddwaf_object_destroy`, then destroy the context (and allocator if you created a custom one).
-
-Because preprocessors, exclusion filters, and postprocessors all operate deterministically on the same address store, their combined effect keeps the rule execution focused on actionable signals while still surfacing rich telemetry to downstream pipelines.
-
----
-
-## Practical Notes
-
-- Only addresses seen as new trigger work; unchanged inputs can skip processors, filters, and rules.
-- Non-expiring modules (`network-acl`, `authentication-acl`) ignore deadlines; all others honour them.
-- Postprocessors still run after a rule-timeout so existing data can surface in attributes.
-- Exclusions apply per rule right before condition evaluation, enabling fine-grained bypass/monitor/action overrides without editing rules.
diff --git a/docs/processor_overrides.md b/docs/processor_overrides.md
deleted file mode 100644
index f5033a55f..000000000
--- a/docs/processor_overrides.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# Processor Overrides
-
-Processor overrides tweak processor definitions without redefining them. They live in the top-level `processor_overrides` array and currently control scanner selection for `extract_schema`.
-
-## Schema
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `target` | array | yes | Identifies processors by `id` or `tags`. |
-| `scanners.include` | array | no | Scanners to add (by `id` or `tags`). |
-| `scanners.exclude` | array | no | Scanners to remove (by `id` or `tags`). |
-
-At least one of `scanners.include` or `scanners.exclude` must be provided.
-
-### Targets
-
-Each entry in `target` accepts:
-
-- `id`: processor identifier.
-- `tags`: processor tags (all key/value pairs must match).
-
-### Scanner merging
-
-Overrides are incremental: includes add scanners, excludes remove scanners from the processor’s configured set. The resolution order matches scanner selection precedence:
-
-1. Exclude by ID.
-2. Include by ID.
-3. Exclude by tags.
-4. Include by tags.
-
-Multiple overrides against the same processor are applied in sequence; later changes win when conflicting.
-
-## Example
-
-```json
-{
-  "processor_overrides": [
-    {
-      "target": [{ "id": "extract_schema_body" }],
-      "scanners": {
-        "include": [{ "id": "scanner-allowlist" }],
-        "exclude": [{ "tags": { "type": "experimental" } }]
-      }
-    }
-  ]
-}
-```
diff --git a/docs/processors.md b/docs/processors.md
deleted file mode 100644
index 29a8466b4..000000000
--- a/docs/processors.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# Processors
-
-Processors are reusable transformations that derive new addresses from request data. They can run before rule evaluation (preprocessors) or after rule evaluation to enrich result attributes (postprocessors). Each processor lives in the `processors` array of a configuration.
-
-## Processor schema
-
-Required fields:
-
-| Field | Type | Description |
-| --- | --- | --- |
-| `id` | string | Unique identifier for diagnostics and overrides. |
-| `generator` | string | Processor type (for example `uri_parse`, `jwt_decode`, `extract_schema`, fingerprint generators). |
-
-Optional fields:
-
-| Field | Type | Default | Notes |
-| --- | --- | --- | --- |
-| `conditions` | array | `[]` | Simplified expression that must evaluate to `true` before the processor runs. See [conditions](conditions.md). |
-| `parameters.mappings` | array | `[]` | Input/output bindings; see below. |
-| `parameters.scanners` | array | `[]` | Scanner include/exclude filters (only for `extract_schema`). |
-| `min_version`, `max_version` | semantic version | unrestricted | Restrict the processor to specific libddwaf versions. |
-| `evaluate` | boolean | `true` | When `true`, output is inserted into the object store (preprocessor). |
-| `output` | boolean | `false` | When `true`, output is exported via the attribute collector (postprocessor). |
-
-At least one of `evaluate` or `output` must be `true`; otherwise the processor is rejected.
-
-### Mappings
-
-Each entry in `parameters.mappings` wires processor inputs to addresses and declares an output:
-
-| Key | Type | Notes |
-| --- | --- | --- |
-| `<param>` | array | Required inputs keyed by the generator’s `param_names` (for example `inputs`, `headers`, `uri_raw`, `output`). Each array entry contains an `address` and optional `key_path`. |
-| `output` | string | Address where the generated object will be stored/emitted. |
-
-Inputs can provide `key_path` to navigate nested structures and may include only one address per parameter (current parser limitation).
-
-### Lifecycle and caching
-
-- **Preprocessors** (`evaluate: true`) run before exclusions and rules. Derived addresses are immediately available to conditions. Results are cloned into the caller allocator.
-- **Postprocessors** (`output: true`) run after rule evaluation and append attributes to the result payload without affecting rule logic.
-- Expressions, resolved inputs, and generated outputs are cached per context to avoid recomputation across evaluations. Optional parameters trigger re-evaluation only when new inputs appear.
-- Processors honor the evaluation deadline and throw on timeout.
-
-## Supported generators (summary)
-
-- `extract_schema`: Walks complex objects to build `{address}.schema` summaries; can use scanners; often configured as both pre- and postprocessor.
-- `jwt_decode`: Decodes JWT header/payload; commonly populates `server.request.jwt`.
-- `uri_parse`: Breaks a URI into structured components and query map.
-- Fingerprints: `http_endpoint_fingerprint`, `http_header_fingerprint`, `http_network_fingerprint`, `session_fingerprint`; emit deterministic fingerprint fragments under `_dd.appsec.fp.*`.
-
-Refer to integration tests under `tests/integration/processors` for concrete payloads and expected outputs.
-
-## Example configuration
-
-```json
-{
-  "processors": [
-    {
-      "id": "fingerprint-http-endpoint",
-      "generator": "http_endpoint_fingerprint",
-      "conditions": [
-        {
-          "operator": "equals",
-          "parameters": {
-            "inputs": [
-              { "address": "waf.context.processor", "key_path": ["fingerprint"] }
-            ],
-            "type": "boolean",
-            "value": true
-          }
-        }
-      ],
-      "parameters": {
-        "mappings": [
-          {
-            "method": [{ "address": "server.request.method" }],
-            "uri_raw": [{ "address": "server.request.uri.raw" }],
-            "query": [{ "address": "server.request.query" }],
-            "body": [{ "address": "server.request.body" }],
-            "output": "_dd.appsec.fp.http.endpoint"
-          }
-        ]
-      },
-      "evaluate": false,
-      "output": true
-    }
-  ]
-}
-```
-
-This example gates a postprocessor on a context flag, generates a deterministic endpoint fingerprint, and exports it as an attribute without affecting rule evaluation.
diff --git a/docs/rule_data.md b/docs/rule_data.md
deleted file mode 100644
index 3976cfbff..000000000
--- a/docs/rule_data.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Rules Data
-
-Rules data supplies external datasets consumed by operators such as `ip_match` and `exact_match`. It lives in the top-level `rules_data` map keyed by dataset identifier.
-
-## Schema
-
-`rules_data` is a map of entries:
-
-| Key | Value type | Description |
-| --- | --- | --- |
-| `<data_id>` | array | List of values for the dataset (strings for regex/phrase data, IP/CIDR strings for `ip_match`, etc.). |
-
-Datasets can be shared across base and custom rules as long as the `data` field in the rule’s operator points to the same `<data_id>`.
-
-## Example
-
-```json
-{
-  "rules_data": {
-    "trusted-ips": [
-      "10.0.0.0/8",
-      "192.168.0.0/16"
-    ],
-    "blocked-usernames": [
-      "admin",
-      "root"
-    ]
-  }
-}
-```
-
-A rule using `ip_match` may reference `"data": "trusted-ips"`; a rule using `exact_match` can reference `"data": "blocked-usernames"`.
-
-## Diagnostics
-
-During parsing, datasets are validated for type correctness per operator. Parsing diagnostics report missing datasets or invalid entries, and rules that reference invalid data are rejected.
diff --git a/docs/rule_overrides.md b/docs/rule_overrides.md
deleted file mode 100644
index 759ef9675..000000000
--- a/docs/rule_overrides.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# Rule Overrides
-
-Rule overrides adjust existing rules without redefining them. They live in the top-level `rules_override` array and are applied after rules/custom_rules are loaded.
-
-## Schema
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `rules_target` | array | yes | Targets selected rules by `id`/`rule_id` or `tags`. |
-| `enabled` | boolean | no | Forces enabled/disabled state. |
-| `on_match` | string | no | Overrides the action to emit (for example `monitor` or a custom action ID). |
-| `tags` | object | no | Additional tags to merge into the rule’s metadata. |
-| `transformers` | array | no | Overrides the rule-level transformer list. |
-
-An override must specify at least one mutating field (`enabled`, `on_match`, `tags`, or `transformers`).
-
-### Targets
-
-Each entry in `rules_target` accepts:
-
-- `id` / `rule_id`: exact rule identifier.
-- `tags`: object of tags to match (all key/value pairs must match).
-
-### Behaviour
-
-- Overrides are applied in order; later overrides replace earlier ones for the same rule attributes.
-- Tag additions merge into the existing tag set.
-- Providing `transformers` replaces the rule’s transformer list entirely.
-- `on_match` replaces the rule’s action list; use exclusions for conditional bypass/monitor.
-
-## Example
-
-```json
-{
-  "rules_override": [
-    {
-      "rules_target": [{ "tags": { "type": "lfi" } }],
-      "enabled": false
-    },
-    {
-      "rules_target": [{ "rule_id": "crs-930-120" }],
-      "on_match": "monitor",
-      "tags": { "policy": "allowlist" }
-    }
-  ]
-}
-```
diff --git a/docs/rules.md b/docs/rules.md
deleted file mode 100644
index f9045c086..000000000
--- a/docs/rules.md
+++ /dev/null
@@ -1,142 +0,0 @@
-# Rules and Custom Rules
-
-Configurations declare detections under two top-level arrays:
-
-- `rules`: Datadog-supplied content shipped with the ruleset.
-- `custom_rules`: Tenant- or agent-supplied additions.
-
-Both arrays share the same schema. Entries are merged by ID; IDs must be unique across both arrays or the duplicate is rejected.
-Rule actions referenced via `on_match` are resolved against the configuration’s action catalogue; see [Actions](actions.md).
-
-## Rule schema
-
-Required fields:
-
-| Field | Type | Description |
-| --- | --- | --- |
-| `id` | string | Stable identifier. Must not collide with any other rule in the configuration set. |
-| `name` | string | Human-readable label for diagnostics. |
-| `tags` | object | Metadata emitted in events and used for grouping/overrides. Must include a `type` key; may include `module`, `category`, or any custom taxonomy. |
-| `conditions` | array | Expression evaluated against request data. See the [Condition schema](conditions.md). |
-
-Optional fields:
-
-| Field | Type | Default | Notes |
-| --- | --- | --- | --- |
-| `enabled` | boolean | `true` | Disable the rule without removing it. |
-| `min_version`, `max_version` | semantic version | unrestricted | Load the rule only when the running libddwaf version falls within the range. |
-| `transformers` | array | `[]` | Up to 10 identifiers applied to every input in the rule. See the [Transformer Reference](transformers.md). |
-| `on_match` | array of strings | `[]` | Ordered list of action IDs to emit when the rule matches. See [Actions](actions.md) for the catalogue schema. |
-| `output` | object | `{ event: true, keep: true, attributes: {} }` | Shape the emitted event; see below. |
-
-### Tags and modules
-
-- `tags.type` is required and typically mirrors the threat category (for example `sql_injection`, `lfi`, or `grpc_request_blocking`).
-- `tags.module` is optional. Recognised values include `network-acl`, `authentication-acl`, `custom-acl`, `configuration`, `business-logic`, `rasp`, and `waf` (default). Modules control execution order and precedence (see `docs/overview.md`).
-- Additional tags are free-form and surface in events; they can be used by overrides and exclusions for selection.
-
-### Output object
-
-The `output` object controls how matches surface:
-
-- `event` (bool): when `false`, no event is produced.
-- `keep` (bool): when `false`, the match may be dropped during sampling.
-- `attributes` (object): map of extra fields to include in the result. Each value is either a static scalar (`value`) or a reference to request data via `address` and optional `key_path`.
-
-Attribute entries support:
-
-```json
-{
-  "attributes": {
-    "static-example": { "value": "constant value" },
-    "copied-field": {
-      "address": "server.request.query",
-      "key_path": ["user_id"]
-    }
-  }
-}
-```
-
-- `value` accepts strings, integers, floats, and booleans.
-- Referencing request data requires an `address` and an optional `key_path` (strings for map keys, integers for array indices). Omit `key_path` to copy the entire address.
-
-Rules must generate at least one event or attribute. A rule with `output.event = false` and an empty `attributes` object is rejected during parsing.
-
-Example:
-
-```json
-{
-  "output": {
-    "event": true,
-    "keep": true,
-    "attributes": {
-      "user-id": { "address": "usr.id" },
-      "static-tag": { "value": "auth" }
-    }
-  }
-}
-```
-
-### Conditions and operators
-
-Conditions use the shared expression schema documented in [conditions.md](conditions.md) and can reference any operator from the [Operator Reference](operators.md). Rule-level transformers apply to every input unless an input overrides them with its own `transformers` list.
-
-### Evaluation notes
-
-- Conditions operate on the request `values` data source by default and contribute matches to the rule event payload.
-- Rule-level transformers run before the operator chain and apply to every input reference unless overridden at the input level.
-- `on_match` actions fire in the order provided. Combine them with [exclusion filters](exclusions.md) to adjust the eventual verdict (`monitor`, `block`, or custom actions).
-- Disabled rules, rules gated by incompatible versions, or rules filtered out by exclusions are skipped without evaluating their conditions.
-
-## Example configuration
-
-```json
-{
-  "version": "2.2",
-  "actions": [
-    { "id": "redirect-to-login", "type": "redirect_request", "parameters": { "location": "/login", "status_code": 303 } }
-  ],
-  "rules": [
-    {
-      "id": "ddos-rate-limit",
-      "name": "Generic request flood",
-      "tags": { "type": "configuration", "module": "waf" },
-      "transformers": ["remove_nulls"],
-      "conditions": [
-        {
-          "operator": "greater_than",
-          "parameters": {
-            "inputs": [{ "address": "server.request.rate" }],
-            "type": "unsigned",
-            "value": 200
-          }
-        }
-      ],
-      "on_match": ["block_request"]
-    }
-  ],
-  "custom_rules": [
-    {
-      "id": "my-app-login-bruteforce",
-      "name": "Login brute force detector",
-      "tags": { "type": "security_scanner", "category": "auth", "module": "waf" },
-      "conditions": [
-        {
-          "operator": "match_regex",
-          "parameters": {
-            "inputs": [{ "address": "server.response.body" }],
-            "regex": "(?i)login failed"
-          }
-        }
-      ],
-      "on_match": ["monitor"],
-      "output": {
-        "event": true,
-        "attributes": { "response_snippet": { "address": "server.response.body" } }
-      }
-    }
-  ]
-}
-```
-
-Both rule collections are parsed with the same validation rules: missing required fields or incompatible versions cause the entry to be skipped with diagnostics; rules that generate neither events nor attributes are rejected. Modules and precedence follow the execution order described in `docs/overview.md` (user-defined rules in `custom_rules` take precedence within modules that favour user content).
diff --git a/docs/scanners.md b/docs/scanners.md
deleted file mode 100644
index 5788827c5..000000000
--- a/docs/scanners.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# Scanners
-
-Scanners provide optional annotations and filtering for processors that inspect structured data. They are primarily used by the `extract_schema` processor to tag or prune parts of a generated schema based on predefined logic.
-
-## Where scanners are used
-
-- **`extract_schema`**: accepts a `parameters.scanners` list of includes/excludes by ID or tags. The resolved set of scanner implementations is passed to the processor to influence how fields are marked or trimmed in the generated schema maps (`{address}.schema`).
-
-No other built-in processors currently consume scanners, but the mechanism is extensible for new generators.
-
-## Selection rules
-
-When resolving the scanner set, references are applied in this precedence order (`src/processor/extract_schema.*`):
-
-1. Exclusions by ID.
-2. Inclusions by ID.
-3. Exclusions by tags.
-4. Inclusions by tags.
-
-This ordering ensures explicit IDs win over tag-based selectors, and exclusions win over inclusions.
-
-## Configuration shape
-
-Within a processor definition:
-
-```json
-{
-  "id": "schema-extractor",
-  "generator": "extract_schema",
-  "parameters": {
-    "scanners": {
-      "include": ["trusted-scanner-id"],
-      "exclude": [{ "tags": ["experimental"] }]
-    },
-    "mappings": [
-      { "inputs": [{ "address": "server.request.body" }], "output": "server.request.body.schema" }
-    ]
-  },
-  "evaluate": true
-}
-```
-
-- `include` / `exclude` accept a mix of IDs (strings) and tag selectors (`{ "tags": [...] }`).
-- If neither include nor exclude is provided, all scanners are available to the processor.
-
-## Runtime behaviour
-
-Each selected scanner can:
-
-- Annotate schema nodes (for example mark sensitive fields).
-- Suppress nodes that match pruning criteria.
-- Leave the node untouched.
-
-The processor applies scanners to every visited node during schema extraction, respecting the include/exclude set resolved at configuration load time.
diff --git a/docs/transformers.md b/docs/transformers.md
deleted file mode 100644
index 1d6aec87e..000000000
--- a/docs/transformers.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Transformer Reference
-
-Transformers preprocess request data before operators or rules consume it. They can be chained within rule conditions and are applied in the order listed.
-
-| Name (v1.12+) | Alias (≤ v1.11) | Purpose | Example | Availability |
-| --- | --- | --- | --- | --- |
-| `remove_nulls` | `removeNulls` | Strip null bytes. | `bla\0bla → blabla` | ≥ v1.0 |
-| `html_entity_decode` | `htmlEntityDecode` | Decode HTML entities (UTF-16 aware). | `&lt;&gt;&amp;&quot;&nbsp; → <>&"\xa0` | ≥ v1.0 |
-| `js_decode` | `jsDecode` | Decode JavaScript escapes (UTF-16 aware). | `bla\x20bla → bla bla`<br>`\udbff\udfff → \xF0\x8F\xBF\xBF` | ≥ v1.0 |
-| `css_decode` | `cssDecode` | Decode CSS escapes (UTF-16 aware). | `"CSS\%0a tran\sf → CSS transformations` | ≥ v1.0 |
-| `base64_encode` | `base64Encode` | Base64 encode. | `bla → Ymxh` | ≥ v1.0 |
-| `base64_decode` | `base64Decode` | Decode Base64 (RFC 4648). | `Zm9v → foo`<br>`Zm==============9v → ❌` | ≥ v1.0 |
-| `base64DecodeExt` | — | Decode Base64 (RFC 2045). **Deprecated** in v1.12. | `Zm==============9v → foo` | ≥ v1.0 (deprecated v1.12) |
-| `url_decode` | `urlDecode` | Decode URL encoding. | `%01hex+encoder%0f → \x01hex encoder\x0f` | ≥ v1.0 |
-| `url_decode_iis` | `urlDecodeUni` | Decode URL encoding with IIS extensions. | `%u1234 → \xE1\x88\xB4` | ≥ v1.0 |
-| `normalize_path` | `normalizePath` | Collapse relative path segments. | `pony/../bla/ → bla/` | ≥ v1.0 |
-| `normalize_path_win` | `normalizePathWin` | Collapse Windows-style relative paths. | `pony\\..\\bla\\ → bla/` | ≥ v1.0 |
-| `compress_whitespace` | `compressWhiteSpace` | Replace repeated whitespace with a single space. | `bla  bla → bla bla` | ≥ v1.0 |
-| `lowercase` | `lowercase` | Convert to lowercase. | `BlA → bla` | ≥ v1.0 |
-| `length` | — | Compute string length. **Deprecated** in v1.12. | `bla → 3` | ≥ v1.0 (deprecated v1.12) |
-| `shell_unescape` | `cmdLine` | Remove shell escaping. | `normal \t\v\f\n\r (really) → normal(really)` | ≥ v1.0 |
-| `remove_comments` | `removeComments` | Strip C/HTML/SQL/shell comments. | `a/*b*/c<!--d-->e--f → ace` | ≥ v1.0 |
-| `numerize` | — | Parse integer strings (INT64_MIN ↔ UINT64_MAX). **Deprecated** in v1.12. | `"-123" → -123`<br>`"1.0" → ❌` | ≥ v1.0 (deprecated v1.12) |
-| `url_basename` | `_sqr_basename` | Extract filename from URI. | `/path/index.php?a=b → index.php` | ≥ v1.0 |
-| `url_path` | `_sqr_filename` | Extract path from URI. | `/path/index.php?a=b → /path/index.php` | ≥ v1.0 |
-| `url_querystring` | `_sqr_querystring` | Extract query string from URI. | `/path/index.php?a=b#d → a=b` | ≥ v1.0 |
-| `unicode_normalize` | — | Apply Unicode NFKD normalization to UTF-8 strings. | `a𝑎éßıfi2⁵—⅖ → aaessifi25-2/5` | ≥ v1.5 |
-| `keys_only` | — | Flatten structured data to a list of keys. | `{ a: b, c: { d: e } } → [a, c, d]` | ≥ v1.1 |
-
-Deprecated transformers remain available for backward compatibility but should be avoided in new rules.

From 1494ee9aadf6d6a68d08e61d9cac62cad9e852e1 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 13:17:58 +0000
Subject: [PATCH 24/32] Review fixes and improvements

---
 docs/upgrading/UPGRADING-v2.0.md |  20 ++--
 include/ddwaf.h                  | 154 +++----------------------------
 tools/common/utils.cpp           |  12 ++-
 tools/infer_schema.cpp           |  47 +++++-----
 4 files changed, 59 insertions(+), 174 deletions(-)

diff --git a/docs/upgrading/UPGRADING-v2.0.md b/docs/upgrading/UPGRADING-v2.0.md
index dadd52d9f..885771600 100644
--- a/docs/upgrading/UPGRADING-v2.0.md
+++ b/docs/upgrading/UPGRADING-v2.0.md
@@ -98,7 +98,7 @@ As mentioned, context evaluation no longer supports ephemeral data, consequently
 ```c
 ddwaf_object persistent_data = ...;
 ddwaf_object ephemeral_data = ...;
-ddwaf_result result;
+ddwaf_object result;
 
 // Separate persistent and ephemeral parameters
 DDWAF_RET_CODE code = ddwaf_run(context, &persistent_data, &ephemeral_data, &result, timeout);
@@ -109,7 +109,7 @@ if (code == DDWAF_MATCH) {
 }
 
 // Free result (v1 used internal memory management)
-ddwaf_result_free(&result);
+ddwaf_object_free(&result);
 ```
 
 **v2.x:**
@@ -138,15 +138,15 @@ ddwaf_context context = ddwaf_context_init(handle);
 
 // First evaluation with persistent data
 ddwaf_object persistent = ...;
-ddwaf_result result1;
+ddwaf_object result1;
 ddwaf_run(context, &persistent, NULL, &result1, timeout);
-ddwaf_result_free(&result1);
+ddwaf_object_free(&result1);
 
 // Second evaluation - persistent data still available
 ddwaf_object more_data = ...;
-ddwaf_result result2;
+ddwaf_object result2;
 ddwaf_run(context, &more_data, NULL, &result2, timeout);
-ddwaf_result_free(&result2);
+ddwaf_object_free(&result2);
 ```
 
 **v2.x:**
@@ -181,15 +181,15 @@ ddwaf_context context = ddwaf_context_init(handle);
 
 // Store persistent data
 ddwaf_object persistent = ...;
-ddwaf_result result1;
+ddwaf_object result1;
 ddwaf_run(context, &persistent, NULL, &result1, timeout);
-ddwaf_result_free(&result1);
+ddwaf_object_free(&result1);
 
 // Evaluate with ephemeral data
 ddwaf_object ephemeral = ...;
-ddwaf_result result2;
+ddwaf_object result2;
 ddwaf_run(context, NULL, &ephemeral, &result2, timeout);
-ddwaf_result_free(&result2);
+ddwaf_object_free(&result2);
 
 // Ephemeral data is NOT stored, persistent data remains
 ```
diff --git a/include/ddwaf.h b/include/ddwaf.h
index 9c124640e..aaa7cf3a2 100644
--- a/include/ddwaf.h
+++ b/include/ddwaf.h
@@ -196,7 +196,7 @@ static_assert(sizeof(struct _ddwaf_object_kv) == 32);
 /**
  * @typedef ddwaf_log_cb
  *
- * Callback that powerwaf will call to relay messages to the binding.
+ * Callback that libddwaf will call to relay messages to the binding.
  *
  * @param level The logging level.
  * @param function The native function that emitted the message. (nonnull)
@@ -210,8 +210,6 @@ typedef void (*ddwaf_log_cb)(
     const char* message, uint64_t message_len);
 
 /**
- * ddwaf_init
- *
  * Initialize a ddwaf instance
  *
  * @param ruleset ddwaf::object map containing rules, exclusions, rules_override and rules_data. (nonnull)
@@ -226,8 +224,6 @@ typedef void (*ddwaf_log_cb)(
 ddwaf_handle ddwaf_init(const ddwaf_object *ruleset,  ddwaf_object *diagnostics);
 
 /**
- * ddwaf_destroy
- *
  * Destroy a WAF instance.
  *
  * @param handle Handle to the WAF instance.
@@ -235,8 +231,6 @@ ddwaf_handle ddwaf_init(const ddwaf_object *ruleset,  ddwaf_object *diagnostics)
 void ddwaf_destroy(ddwaf_handle handle);
 
 /**
- * ddwaf_known_addresses
- *
  * Get an array of known (root) addresses used by rules, exclusion filters and
  * processors. This array contains both required and optional addresses. A more
  * accurate distinction between required and optional addresses is provided
@@ -255,8 +249,6 @@ void ddwaf_destroy(ddwaf_handle handle);
  **/
 const char* const* ddwaf_known_addresses(const ddwaf_handle handle, uint32_t *size);
 /**
- * ddwaf_known_actions
- *
  * Get an array of all the action types which could be triggered as a result of
  * the current set of rules and exclusion filters.
  *
@@ -273,12 +265,10 @@ const char* const* ddwaf_known_addresses(const ddwaf_handle handle, uint32_t *si
  **/
 const char *const *ddwaf_known_actions(const ddwaf_handle handle, uint32_t *size);
 /**
- * ddwaf_context_init
- *
  * Context object to perform matching using the provided WAF instance.
  *
  * @param handle Handle of the WAF instance containing the ruleset definition. (nonnull)
- * @param output Allocator used to serve output objects created during evaluation (nonnull)
+ * @param output_alloc Allocator used to serve output objects created during evaluation (nonnull)
 
  * @return Handle to the context instance.
  *
@@ -287,8 +277,6 @@ const char *const *ddwaf_known_actions(const ddwaf_handle handle, uint32_t *size
 ddwaf_context ddwaf_context_init(const ddwaf_handle handle, ddwaf_allocator output_alloc);
 
 /**
- * ddwaf_context_eval
- *
  * Perform a matching operation on the provided data
  *
  * @param context WAF context to be used in this run, this will determine the
@@ -310,7 +298,7 @@ ddwaf_context ddwaf_context_init(const ddwaf_handle handle, ddwaf_allocator outp
  * @param result (nullable) Object map containing the following items:
  *               - events: an array of the generated events.
  *               - actions: a map of the generated actions in the format:
- *                          {action type: { <parameter map> }, ...}
+ *                          "{action type: { <parameter map> }, ...}"
  *               - duration: an unsigned specifying the total runtime of the
  *                           call in nanoseconds.
  *               - timeout: whether there has been a timeout during the call.
@@ -327,12 +315,12 @@ ddwaf_context ddwaf_context_init(const ddwaf_handle handle, ddwaf_allocator outp
  * @param timeout Maximum time budget in microseconds.
  *
  * @return Return code of the operation.
- * @error DDWAF_ERR_INVALID_ARGUMENT The context is invalid, the data will not
+ * @retval DDWAF_ERR_INVALID_ARGUMENT The context is invalid, the data will not
  *                                   be freed.
- * @error DDWAF_ERR_INVALID_OBJECT The data provided didn't match the desired
+ * @retval DDWAF_ERR_INVALID_OBJECT The data provided didn't match the desired
  *                                 structure or contained invalid objects, the
  *                                 data will be freed by this function.
- * @error DDWAF_ERR_INTERNAL There was an unexpected error and the operation did
+ * @retval DDWAF_ERR_INTERNAL There was an unexpected error and the operation did
  *                           not succeed. The state of the WAF is undefined if
  *                           this error is produced and the ownership of the
  *                           data is unknown. The result structure will not be
@@ -349,8 +337,6 @@ DDWAF_RET_CODE ddwaf_context_eval(ddwaf_context context, ddwaf_object *data,
     ddwaf_allocator alloc, ddwaf_object *result,  uint64_t timeout);
 
 /**
- * ddwaf_context_destroy
- *
  * Performs the destruction of the context, freeing the data passed to it through
  * ddwaf_context_eval using the used-defined free function.
  *
@@ -359,19 +345,15 @@ DDWAF_RET_CODE ddwaf_context_eval(ddwaf_context context, ddwaf_object *data,
 void ddwaf_context_destroy(ddwaf_context context);
 
 /**
- * ddwaf_subcontext_init
- *
  * Subcontext object to perform matching using the provided WAF instance.
  *
- * @param conext Context from which to derive this subcontext. (nonnull)
+ * @param context Context from which to derive this subcontext. (nonnull)
 
  * @return Handle to the subcontext instance.
  **/
 ddwaf_subcontext ddwaf_subcontext_init(ddwaf_context context);
 
 /**
- * ddwaf_subcontext_eval
- *
  * Perform a matching operation on the provided data
  *
  * @param subcontext WAF subcontext to be used in this run, this will determine
@@ -392,7 +374,7 @@ ddwaf_subcontext ddwaf_subcontext_init(ddwaf_context context);
  * @param result (nullable) Object map containing the following items:
  *               - events: an array of the generated events.
  *               - actions: a map of the generated actions in the format:
- *                          {action type: { <parameter map> }, ...}
+ *                          "{action type: { <parameter map> }, ...}"
  *               - duration: an unsigned specifying the total runtime of the
  *                           call in nanoseconds.
  *               - timeout: whether there has been a timeout during the call.
@@ -409,12 +391,12 @@ ddwaf_subcontext ddwaf_subcontext_init(ddwaf_context context);
  * @param timeout Maximum time budget in microseconds.
  *
  * @return Return code of the operation.
- * @error DDWAF_ERR_INVALID_ARGUMENT The subcontext is invalid, the data will not
+ * @retval DDWAF_ERR_INVALID_ARGUMENT The subcontext is invalid, the data will not
  *                                   be freed.
- * @error DDWAF_ERR_INVALID_OBJECT The data provided didn't match the desired
+ * @retval DDWAF_ERR_INVALID_OBJECT The data provided didn't match the desired
  *                                 structure or contained invalid objects, the
  *                                 data will be freed by this function.
- * @error DDWAF_ERR_INTERNAL There was an unexpected error and the operation did
+ * @retval DDWAF_ERR_INTERNAL There was an unexpected error and the operation did
  *                           not succeed. The state of the WAF is undefined if
  *                           this error is produced and the ownership of the
  *                           data is unknown. The result structure will not be
@@ -431,8 +413,6 @@ DDWAF_RET_CODE ddwaf_subcontext_eval(ddwaf_subcontext subcontext, ddwaf_object *
     ddwaf_allocator alloc, ddwaf_object *result,  uint64_t timeout);
 
 /**
- * ddwaf_subcontext_destroy
- *
  * Performs the destruction of the subcontext, freeing the data passed to it through
  * ddwaf_subcontext_eval using the used-defined allocator.
  *
@@ -442,8 +422,6 @@ void ddwaf_subcontext_destroy(ddwaf_subcontext subcontext);
 
 
 /**
- * ddwaf_builder_init
- *
  * Initialize an instace of the waf builder.
  *
  * @return Handle to the builer instance or NULL on error.
@@ -453,8 +431,6 @@ void ddwaf_subcontext_destroy(ddwaf_subcontext subcontext);
 ddwaf_builder ddwaf_builder_init();
 
 /**
- * ddwaf_builder_add_or_update_config
- *
  * Adds or updates a configuration based on the given path, which must be a unique
  * identifier for the provided configuration.
  *
@@ -473,8 +449,6 @@ ddwaf_builder ddwaf_builder_init();
 bool ddwaf_builder_add_or_update_config(ddwaf_builder builder, const char *path, uint32_t path_len, const ddwaf_object *config, ddwaf_object *diagnostics);
 
 /**
- * ddwaf_builder_remove_config
- *
  * Removes a configuration based on the provided path.
  *
  * @param builder Builder to perform the operation on. (nonnull)
@@ -489,8 +463,6 @@ bool ddwaf_builder_add_or_update_config(ddwaf_builder builder, const char *path,
 bool ddwaf_builder_remove_config(ddwaf_builder builder, const char *path, uint32_t path_len);
 
 /**
- * ddwaf_builder_build_instance
- *
  * Builds a ddwaf instance based on the current set of configurations.
  *
  * @param builder Builder to perform the operation on. (nonnull)
@@ -502,8 +474,6 @@ bool ddwaf_builder_remove_config(ddwaf_builder builder, const char *path, uint32
 ddwaf_handle ddwaf_builder_build_instance(ddwaf_builder builder);
 
 /**
- * ddwaf_builder_get_config_paths
- *
  * Provides an array of the currently loaded paths, optionally matching the
  * regex provided in filter. In addition, the count is provided as the return
  * value, allowing paths to be nullptr.
@@ -526,8 +496,6 @@ ddwaf_handle ddwaf_builder_build_instance(ddwaf_builder builder);
 uint32_t ddwaf_builder_get_config_paths(ddwaf_builder builder, ddwaf_object *paths, const char *filter, uint32_t filter_len);
 
 /**
- * ddwaf_builder_destroy
- *
  * Destroy an instance of the builder.
  *
  * @param builder Builder to perform the operation on. (nonnull)
@@ -535,8 +503,6 @@ uint32_t ddwaf_builder_get_config_paths(ddwaf_builder builder, ddwaf_object *pat
 void ddwaf_builder_destroy(ddwaf_builder builder);
 
 /**
- * ddwaf_get_default_allocator
- *
  * Returns the default allocator used by the library.
  *
  * @return Allocator handle.
@@ -544,8 +510,6 @@ void ddwaf_builder_destroy(ddwaf_builder builder);
 ddwaf_allocator ddwaf_get_default_allocator();
 
 /**
- * ddwaf_synchronized_pool_allocator_init
- *
  * Creates a thread-safe pool allocator. Allocations are served from internal
  * pools sized by block class to reduce fragmentation and allocator overhead;
  * memory freed via the corresponding ddwaf APIs is returned to the pools for
@@ -560,8 +524,6 @@ ddwaf_allocator ddwaf_get_default_allocator();
 ddwaf_allocator ddwaf_synchronized_pool_allocator_init();
 
 /**
- * ddwaf_unsynchronized_pool_allocator_init
- *
  * Creates a pool allocator without internal synchronization. It provides the
  * same pooling characteristics as the synchronized variant but with lower
  * overhead. This allocator must not be used concurrently from multiple threads
@@ -576,8 +538,6 @@ ddwaf_allocator ddwaf_synchronized_pool_allocator_init();
 ddwaf_allocator ddwaf_unsynchronized_pool_allocator_init();
 
 /**
- * ddwaf_monotonic_allocator_init
- *
  * Creates a monotonic (growing) allocator. Allocations are fast and never freed
  * individually; all memory is reclaimed only when the allocator is destroyed.
  * This allocator must not be used concurrently from multiple threads unless
@@ -594,8 +554,6 @@ ddwaf_allocator ddwaf_unsynchronized_pool_allocator_init();
 ddwaf_allocator ddwaf_monotonic_allocator_init();
 
 /**
- * ddwaf_user_allocator_init
- *
  * Creates an allocator that forwards allocation and deallocation to user
  * provided callbacks.
  *
@@ -607,14 +565,15 @@ ddwaf_allocator ddwaf_monotonic_allocator_init();
  *        able to free any pointer previously returned by `alloc_fn`. (nonnull)
  * @param udata Opaque user pointer forwarded to both callbacks; can be used to
  *        carry custom state. (nullable)
+ * @param udata_free_fn User data destruction callback, used to perform any
+ *        relevant destruction and reclamation operations on the provided user
+ *        data.
  *
  * @return Allocator handle.
  **/
 ddwaf_allocator ddwaf_user_allocator_init(ddwaf_alloc_fn_type alloc_fn, ddwaf_free_fn_type free_fn, void *udata, ddwaf_udata_free_fn_type udata_free_fn);
 
 /**
- * ddwaf_allocator_alloc
- *
  * Allocates a block of memory from the given allocator with the requested
  * alignment.
  *
@@ -636,8 +595,6 @@ ddwaf_allocator ddwaf_user_allocator_init(ddwaf_alloc_fn_type alloc_fn, ddwaf_fr
 void *ddwaf_allocator_alloc(ddwaf_allocator alloc, size_t bytes, size_t alignment);
 
 /**
- * ddwaf_allocator_free
- *
  * Releases a block of memory previously obtained via ddwaf_allocator_alloc
  * from the same allocator.
  *
@@ -658,8 +615,6 @@ void ddwaf_allocator_free(ddwaf_allocator alloc, void *p, size_t bytes, size_t a
 
 
 /**
- * ddwaf_allocator_destroy
- *
  * Destroys an allocator created by one of the ddwaf_*_allocator_init functions
  * and releases any internal resources it holds.
  *
@@ -674,8 +629,6 @@ void ddwaf_allocator_free(ddwaf_allocator alloc, void *p, size_t bytes, size_t a
 void ddwaf_allocator_destroy(ddwaf_allocator alloc);
 
 /**
- * ddwaf_object_set_invalid
- *
  * Creates an invalid object.
  *
  * @param object Object to perform the operation on. (nonnull)
@@ -685,8 +638,6 @@ void ddwaf_allocator_destroy(ddwaf_allocator alloc);
 ddwaf_object* ddwaf_object_set_invalid(ddwaf_object *object);
 
 /**
- * ddwaf_object_set_null
- *
  * Creates an null object. Provides a different semantical value to invalid as
  * it can be used to signify that a value is null rather than of an unknown type.
  *
@@ -697,8 +648,6 @@ ddwaf_object* ddwaf_object_set_invalid(ddwaf_object *object);
 ddwaf_object* ddwaf_object_set_null(ddwaf_object *object);
 
 /**
- * ddwaf_object_set_string
- *
  * Creates an object from a string.
  *
  * @param object Object to perform the operation on. (nonnull)
@@ -711,8 +660,6 @@ ddwaf_object* ddwaf_object_set_null(ddwaf_object *object);
 ddwaf_object* ddwaf_object_set_string(ddwaf_object *object, const char *string, uint32_t length, ddwaf_allocator alloc);
 
 /**
- * ddwaf_object_set_string_literal
- *
  * Creates an object from a literal string and its length.
  *
  * @param object Object to perform the operation on. (nonnull)
@@ -725,8 +672,6 @@ ddwaf_object* ddwaf_object_set_string(ddwaf_object *object, const char *string,
 ddwaf_object* ddwaf_object_set_string_literal(ddwaf_object *object, const char *string, uint32_t length);
 
 /**
- * ddwaf_object_set_string_nocopy
- *
  * Creates an object with the string pointer and length provided, without copying the string.
  *
  * @param object Object to perform the operation on. (nonnull)
@@ -741,8 +686,6 @@ ddwaf_object* ddwaf_object_set_string_literal(ddwaf_object *object, const char *
  **/
 ddwaf_object* ddwaf_object_set_string_nocopy(ddwaf_object *object, const char *string, uint32_t length);
 /**
- * ddwaf_object_set_unsigned
- *
  * Creates an object using an unsigned integer (64-bit). The resulting object
  * will contain an unsigned integer as opposed to a string.
  *
@@ -754,8 +697,6 @@ ddwaf_object* ddwaf_object_set_string_nocopy(ddwaf_object *object, const char *s
 ddwaf_object* ddwaf_object_set_unsigned(ddwaf_object *object, uint64_t value);
 
 /**
- * ddwaf_object_set_signed
- *
  * Creates an object using a signed integer (64-bit). The resulting object
  * will contain a signed integer as opposed to a string.
  *
@@ -767,8 +708,6 @@ ddwaf_object* ddwaf_object_set_unsigned(ddwaf_object *object, uint64_t value);
 ddwaf_object* ddwaf_object_set_signed(ddwaf_object *object, int64_t value);
 
 /**
- * ddwaf_object_set_bool
- *
  * Creates an object using a boolean, the resulting object will contain a
  * boolean as opposed to a string.
  *
@@ -780,8 +719,6 @@ ddwaf_object* ddwaf_object_set_signed(ddwaf_object *object, int64_t value);
 ddwaf_object* ddwaf_object_set_bool(ddwaf_object *object, bool value);
 
 /**
- * ddwaf_object_set_float
- *
  * Creates an object using a double, the resulting object will contain a
  * double as opposed to a string.
  *
@@ -793,8 +730,6 @@ ddwaf_object* ddwaf_object_set_bool(ddwaf_object *object, bool value);
 ddwaf_object* ddwaf_object_set_float(ddwaf_object *object, double value);
 
 /**
- * ddwaf_object_set_array
- *
  * Creates an array object, for sequential storage.
  *
  * @param object Object to perform the operation on. (nonnull)
@@ -806,8 +741,6 @@ ddwaf_object* ddwaf_object_set_float(ddwaf_object *object, double value);
 ddwaf_object* ddwaf_object_set_array(ddwaf_object *object, uint16_t capacity, ddwaf_allocator alloc);
 
 /**
- * ddwaf_object_set_map
- *
  * Creates a map object, for key-value storage.
  *
  * @param object Object to perform the operation on. (nonnull)
@@ -819,8 +752,6 @@ ddwaf_object* ddwaf_object_set_array(ddwaf_object *object, uint16_t capacity, dd
 ddwaf_object* ddwaf_object_set_map(ddwaf_object *object, uint16_t capacity, ddwaf_allocator alloc);
 
 /**
- * ddwaf_object_insert
- *
  * Inserts a new object into an array object.
  *
  * @param array Array in which to insert the object. (nonnull)
@@ -832,8 +763,6 @@ ddwaf_object* ddwaf_object_set_map(ddwaf_object *object, uint16_t capacity, ddwa
 ddwaf_object *ddwaf_object_insert(ddwaf_object *array, ddwaf_allocator alloc);
 
 /**
- * ddwaf_object_insert_key
- *
  * Inserts a new object into a map object, using a key.
  *
  * @param map Map in which to insert the object. (nonnull)
@@ -846,8 +775,6 @@ ddwaf_object *ddwaf_object_insert(ddwaf_object *array, ddwaf_allocator alloc);
 ddwaf_object *ddwaf_object_insert_key(ddwaf_object *map, const char *key, uint32_t length, ddwaf_allocator alloc);
 
 /**
- * ddwaf_object_insert_literal_key
- *
  * Inserts a new object into a map object, using a literal key.
  *
  * @param map Map in which to insert the object. (nonnull)
@@ -861,8 +788,6 @@ ddwaf_object *ddwaf_object_insert_literal_key(ddwaf_object *map, const char *key
 
 
 /**
- * ddwaf_object_insert_key_nocopy
- *
  * Inserts a new object into a map object, using a key and its length, but without
  * creating a copy of the key.
  *
@@ -879,8 +804,6 @@ ddwaf_object *ddwaf_object_insert_literal_key(ddwaf_object *map, const char *key
 ddwaf_object *ddwaf_object_insert_key_nocopy(ddwaf_object *map, const char *key, uint32_t length, ddwaf_allocator alloc);
 
 /**
- * ddwaf_object_from_json
- *
  * Creates a ddwaf_object from a JSON string. The JSON will be parsed and converted
  * into the appropriate ddwaf_object structure, supporting all JSON types including
  * objects, arrays, strings, numbers, booleans, and null values.
@@ -888,6 +811,7 @@ ddwaf_object *ddwaf_object_insert_key_nocopy(ddwaf_object *map, const char *key,
  * @param output Object to populate with the parsed JSON data. (nonnull)
  * @param json_str The JSON string to parse. (nonnull)
  * @param length Length of the JSON string.
+ * @param alloc Allocator to use for memory allocation. (nonnull)
  *
  * @return The success or failure of the operation.
  *
@@ -898,8 +822,6 @@ ddwaf_object *ddwaf_object_insert_key_nocopy(ddwaf_object *map, const char *key,
 bool ddwaf_object_from_json(ddwaf_object *output, const char *json_str, uint32_t length, ddwaf_allocator alloc);
 
 /**
- * ddwaf_object_type
- *
  * Returns the type of the object.
  *
  * @param object The object from which to get the type.
@@ -909,8 +831,6 @@ bool ddwaf_object_from_json(ddwaf_object *output, const char *json_str, uint32_t
 DDWAF_OBJ_TYPE ddwaf_object_get_type(const ddwaf_object *object);
 
 /**
- * ddwaf_object_get_size
- *
  * Returns the size of the container object.
  *
  * @param object The object from which to get the size.
@@ -920,8 +840,6 @@ DDWAF_OBJ_TYPE ddwaf_object_get_type(const ddwaf_object *object);
 size_t ddwaf_object_get_size(const ddwaf_object *object);
 
 /**
- * ddwaf_object_get_length
- *
  * Returns the length of the string object.
  *
  * @param object The object from which to get the length.
@@ -931,8 +849,6 @@ size_t ddwaf_object_get_size(const ddwaf_object *object);
 size_t ddwaf_object_get_length(const ddwaf_object *object);
 
 /**
- * ddwaf_object_get_string
- *
  * Returns the string contained within the object.
  *
  * @param object The object from which to get the string.
@@ -944,8 +860,6 @@ size_t ddwaf_object_get_length(const ddwaf_object *object);
 const char* ddwaf_object_get_string(const ddwaf_object *object, size_t *length);
 
 /**
- * ddwaf_object_get_unsigned
- *
  * Returns the uint64 contained within the object.
  *
  * @param object The object from which to get the integer.
@@ -955,8 +869,6 @@ const char* ddwaf_object_get_string(const ddwaf_object *object, size_t *length);
 uint64_t ddwaf_object_get_unsigned(const ddwaf_object *object);
 
 /**
- * ddwaf_object_get_signed
- *
  * Returns the int64 contained within the object.
  *
  * @param object The object from which to get the integer.
@@ -966,8 +878,6 @@ uint64_t ddwaf_object_get_unsigned(const ddwaf_object *object);
 int64_t ddwaf_object_get_signed(const ddwaf_object *object);
 
 /**
- * ddwaf_object_get_float
- *
  * Returns the float64 (double) contained within the object.
  *
  * @param object The object from which to get the float.
@@ -977,8 +887,6 @@ int64_t ddwaf_object_get_signed(const ddwaf_object *object);
 double ddwaf_object_get_float(const ddwaf_object *object);
 
 /**
- * ddwaf_object_get_bool
- *
  * Returns the boolean contained within the object.
  *
  * @param object The object from which to get the boolean.
@@ -988,8 +896,6 @@ double ddwaf_object_get_float(const ddwaf_object *object);
 bool ddwaf_object_get_bool(const ddwaf_object *object);
 
 /**
- * ddwaf_object_at_key
- *
  * Returns the key contained in the container at the given index.
  *
  * @param object The container from which to extract the object.
@@ -1002,8 +908,6 @@ const ddwaf_object* ddwaf_object_at_key(const ddwaf_object *object, size_t index
 
 
 /**
- * ddwaf_object_at_value
- *
  * Returns the object contained in the container at the given index.
  *
  * @param object The container from which to extract the object.
@@ -1015,8 +919,6 @@ const ddwaf_object* ddwaf_object_at_key(const ddwaf_object *object, size_t index
 const ddwaf_object* ddwaf_object_at_value(const ddwaf_object *object, size_t index);
 
 /**
- * ddwaf_object_find
- *
  * Returns the object within the given map with a key matching the provided one.
  *
  * @param object The container from which to extract the object.
@@ -1029,8 +931,6 @@ const ddwaf_object* ddwaf_object_at_value(const ddwaf_object *object, size_t ind
 const ddwaf_object* ddwaf_object_find(const ddwaf_object *object, const char *key, size_t length);
 
 /**
- * ddwaf_object_clone
- *
  * Creates a deep copy of the source object into the destination object.
  *
  * @param source The source object to clone from. (nonnull)
@@ -1042,8 +942,6 @@ const ddwaf_object* ddwaf_object_find(const ddwaf_object *object, const char *ke
 ddwaf_object* ddwaf_object_clone(const ddwaf_object *source, ddwaf_object *destination, ddwaf_allocator alloc);
 
 /**
- * ddwaf_object_is_invalid
- *
  * Returns true if the object is invalid.
  *
  * @param object The object from which to get the type.
@@ -1053,8 +951,6 @@ ddwaf_object* ddwaf_object_clone(const ddwaf_object *source, ddwaf_object *desti
 bool ddwaf_object_is_invalid(const ddwaf_object *object);
 
 /**
- * ddwaf_object_is_null
- *
  * Returns true if the object is null.
  *
  * @param object The object from which to get the type.
@@ -1064,8 +960,6 @@ bool ddwaf_object_is_invalid(const ddwaf_object *object);
 bool ddwaf_object_is_null(const ddwaf_object *object);
 
 /**
- * ddwaf_object_is_bool
- *
  * Returns true if the object is a boolean.
  *
  * @param object The object from which to get the type.
@@ -1075,8 +969,6 @@ bool ddwaf_object_is_null(const ddwaf_object *object);
 bool ddwaf_object_is_bool(const ddwaf_object *object);
 
 /**
- * ddwaf_object_is_signed
- *
  * Returns true if the object is a signed integer.
  *
  * @param object The object from which to get the type.
@@ -1086,8 +978,6 @@ bool ddwaf_object_is_bool(const ddwaf_object *object);
 bool ddwaf_object_is_signed(const ddwaf_object *object);
 
 /**
- * ddwaf_object_is_unsigned
- *
  * Returns true if the object is an unsigned integer.
  *
  * @param object The object from which to get the type.
@@ -1097,8 +987,6 @@ bool ddwaf_object_is_signed(const ddwaf_object *object);
 bool ddwaf_object_is_unsigned(const ddwaf_object *object);
 
 /**
- * ddwaf_object_is_float
- *
  * Returns true if the object is a float.
  *
  * @param object The object from which to get the type.
@@ -1108,8 +996,6 @@ bool ddwaf_object_is_unsigned(const ddwaf_object *object);
 bool ddwaf_object_is_float(const ddwaf_object *object);
 
 /**
- * ddwaf_object_is_string
- *
  * Returns true if the object is a string.
  *
  * @param object The object from which to get the type.
@@ -1119,8 +1005,6 @@ bool ddwaf_object_is_float(const ddwaf_object *object);
 bool ddwaf_object_is_string(const ddwaf_object *object);
 
 /**
- * ddwaf_object_is_array
- *
  * Returns true if the object is an array.
  *
  * @param object The object from which to get the type.
@@ -1130,8 +1014,6 @@ bool ddwaf_object_is_string(const ddwaf_object *object);
 bool ddwaf_object_is_array(const ddwaf_object *object);
 
 /**
- * ddwaf_object_is_map
- *
  * Returns true if the object is a map.
  *
  * @param object The object from which to get the type.
@@ -1141,8 +1023,6 @@ bool ddwaf_object_is_array(const ddwaf_object *object);
 bool ddwaf_object_is_map(const ddwaf_object *object);
 
 /**
- * ddwaf_object_destroy
- *
  * Frees the memory contained within the object.
  *
  * @param object Object to destroy. (nonnull)
@@ -1151,8 +1031,6 @@ bool ddwaf_object_is_map(const ddwaf_object *object);
 void ddwaf_object_destroy(ddwaf_object *object, ddwaf_allocator alloc);
 
 /**
- * ddwaf_get_version
- *
  * Return the version of the library
  *
  * @return version Version string, note that this should not be freed
@@ -1160,8 +1038,6 @@ void ddwaf_object_destroy(ddwaf_object *object, ddwaf_allocator alloc);
 const char *ddwaf_get_version();
 
 /**
- * ddwaf_set_log_cb
- *
  * Sets the callback to relay logging messages to the binding
  *
  * @param cb The callback to call, or NULL to stop relaying messages
diff --git a/tools/common/utils.cpp b/tools/common/utils.cpp
index 86c4be608..e7457f4ff 100644
--- a/tools/common/utils.cpp
+++ b/tools/common/utils.cpp
@@ -275,9 +275,11 @@ void object_to_json_helper(
     case DDWAF_OBJ_FLOAT:
         output.SetDouble(ddwaf_object_get_float(&obj));
         break;
-    case DDWAF_OBJ_STRING: {
-        auto sv = std::string_view(obj.via.str.ptr, obj.via.str.size);
-        output.SetString(sv.data(), sv.size(), alloc);
+    case DDWAF_OBJ_STRING:
+    case DDWAF_OBJ_SMALL_STRING:
+    case DDWAF_OBJ_LITERAL_STRING: {
+        output.SetString(
+            ddwaf_object_get_string(&obj, nullptr), ddwaf_object_get_length(&obj), alloc);
     } break;
     case DDWAF_OBJ_MAP:
         output.SetObject();
@@ -287,8 +289,10 @@ void object_to_json_helper(
 
             auto child = obj.via.map.ptr[i];
             object_to_json_helper(child.val, value, alloc);
+            const auto *child_key = ddwaf_object_at_key(&obj, i);
+            key.SetString(ddwaf_object_get_string(child_key, nullptr),
+                ddwaf_object_get_length(child_key), alloc);
 
-            key.SetString(child.key.via.str.ptr, child.key.via.str.size, alloc);
             output.AddMember(key, value, alloc);
         }
         break;
diff --git a/tools/infer_schema.cpp b/tools/infer_schema.cpp
index 2a04692ad..53e101bb5 100644
--- a/tools/infer_schema.cpp
+++ b/tools/infer_schema.cpp
@@ -4,14 +4,9 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2021 Datadog, Inc.
 #include "common/utils.hpp"
-#include "generator/extract_schema.hpp"
 #include "ddwaf.h"
 
-#include <algorithm>
-#include <stdexcept>
-#include <type_traits>
-#include <unordered_set>
-#include <variant>
+#include <limits>
 
 
 int main(int argc, char *argv[])
@@ -22,11 +17,12 @@ int main(int argc, char *argv[])
         return EXIT_FAILURE;
     }
 
+    auto *alloc = ddwaf_get_default_allocator();
+
     std::string rule_str = read_file(argv[1]);
     auto rule = YAML::Load(rule_str).as<ddwaf_object>();
 
-    ddwaf_config config{{nullptr, nullptr}, nullptr};
-    ddwaf_handle handle = ddwaf_init(&rule, &config, nullptr);
+    ddwaf_handle handle = ddwaf_init(&rule, nullptr);
     ddwaf_object_destroy(&rule, alloc);
     if (handle == nullptr) {
         std::cout << "Failed to load " << argv[1] << '\n';
@@ -36,32 +32,41 @@ int main(int argc, char *argv[])
     std::string body_str = read_file(argv[2]);
     auto body = json_to_object(body_str);
 
-    ddwaf_object tmp;
     ddwaf_object settings;
     ddwaf_object input;
 
-    ddwaf_object_map(&input);
-    ddwaf_object_map(&settings);
-    ddwaf_object_map_add(&settings, "extract-schema", ddwaf_object_set_bool(&tmp, true));
-    ddwaf_object_map_add(&input, "waf.context.processor", &settings);
-    ddwaf_object_map_add(&input, "server.request.body", &body);
+    ddwaf_object_set_map(&input, 2, alloc);
+    ddwaf_object_set_map(&settings, 1, alloc);
+
+    ddwaf_object *extract_schema = ddwaf_object_insert_literal_key(&settings, STRL("extract-schema"), alloc);
+    ddwaf_object_set_bool(extract_schema, true);
+
+    ddwaf_object *processor = ddwaf_object_insert_literal_key(&input, STRL("waf.context.processor"), alloc);
+    *processor = settings;
+
+    ddwaf_object *request_body = ddwaf_object_insert_literal_key(&input, STRL("server.request.body"), alloc);
+    *request_body = body;
 
-    ddwaf_context context = ddwaf_context_init(handle);
+    ddwaf_context context = ddwaf_context_init(handle, alloc);
     if (context == nullptr) {
+        ddwaf_object_destroy(&input, alloc);
         ddwaf_destroy(handle);
         return EXIT_FAILURE;
     }
 
-    ddwaf_result ret;
-    ddwaf_context_eval(context, &input, nullptr, &ret, std::numeric_limits<uint32_t>::max());
-    if (ddwaf_object_get_size(&ret.derivatives) > 0) {
-        std::cout << object_to_json(ret.derivatives) << '\n';
+    ddwaf_object result;
+    auto code = ddwaf_context_eval(context, &input, alloc, &result, std::numeric_limits<uint64_t>::max());
+    if (code == DDWAF_MATCH) {
+        std::cout << object_to_json(result) << '\n';
+/*        const ddwaf_object *attributes = ddwaf_object_find(&result, STRL("attributes"));*/
+        /*if (attributes != nullptr && ddwaf_object_get_size(attributes) > 0) {*/
+            /*std::cout << object_to_json(*attributes) << '\n';*/
+        /*}*/
     }
 
-    ddwaf_result_free(&ret);
+    ddwaf_object_destroy(&result, alloc);
     ddwaf_context_destroy(context);
 
-    ddwaf_object_destroy(&input, alloc);
     ddwaf_destroy(handle);
 
     return EXIT_SUCCESS;

From 663acd72f72f17cbe67cacea8e22b293c5eaa675 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 13:55:11 +0000
Subject: [PATCH 25/32] Script to autogenerate markdown documentation from
 include/ddwaf.h

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 Doxyfile                        |   15 +
 docs/README.md                  |    4 +-
 docs/c-api/api.md               | 1177 ++++++++++++++++++++++++-------
 include/ddwaf.h                 |   11 +-
 tools/generate_documentation.py |  547 ++++++++++++++
 5 files changed, 1499 insertions(+), 255 deletions(-)
 create mode 100644 Doxyfile
 create mode 100755 tools/generate_documentation.py

diff --git a/Doxyfile b/Doxyfile
new file mode 100644
index 000000000..4adb698e1
--- /dev/null
+++ b/Doxyfile
@@ -0,0 +1,15 @@
+PROJECT_NAME = libddwaf
+OUTPUT_DIRECTORY = docs/c-api/doxygen
+INPUT = include/ddwaf.h
+FILE_PATTERNS = *.h
+RECURSIVE = NO
+EXTRACT_ALL = YES
+EXTRACT_STATIC = YES
+EXTRACT_PRIVATE = NO
+GENERATE_HTML = NO
+GENERATE_LATEX = NO
+GENERATE_MAN = NO
+GENERATE_RTF = NO
+GENERATE_DOCBOOK = NO
+GENERATE_XML = YES
+XML_OUTPUT = xml
diff --git a/docs/README.md b/docs/README.md
index d0a7785ce..242bae166 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,7 +1,7 @@
 # Documentation Index
 
-- [Overview](overview.md) – Architectural summary and execution pipeline.
+- Overview (TBD) – Architectural summary and execution pipeline.
 - [C API Reference](c-api/api.md) – Comprehensive description of all exported functions, structs, and macros.
 - [Binding Integration Guide](c-api/binding-integration-guide.md) – Guidance for language bindings embedding libddwaf.
 - [Latest Changelog](changelog/CHANGELOG-latest.md) – Release notes for the current version; see the [changelog](changelog/) directory for previous versions.
-- [Upgrading Guides](upgrading/) - Upgrading guides for all versions with relevant and / or breaking changes.
\ No newline at end of file
+- [Upgrading Guides](upgrading/) - Upgrading guides for all versions with relevant and / or breaking changes.
diff --git a/docs/c-api/api.md b/docs/c-api/api.md
index 8694d2b2b..5ebf4c8ff 100644
--- a/docs/c-api/api.md
+++ b/docs/c-api/api.md
@@ -1,441 +1,1120 @@
 # libddwaf C API Reference
 
-This document provides a complete reference for the public symbols exported through `include/ddwaf.h`. It covers every macro, enumeration, structure, type alias, callback signature, and function available to C or C++ callers embedding libddwaf 2.0.0 or later.
+This document describes the public C API of libddwaf.
+
+## Table of Contents
+
+- [Enumerations](#enumerations)
+  - [DDWAF_OBJ_TYPE](#ddwaf-obj-type)
+  - [DDWAF_RET_CODE](#ddwaf-ret-code)
+  - [DDWAF_LOG_LEVEL](#ddwaf-log-level)
+- [Type Definitions](#type-definitions)
+- [Functions](#functions)
+  - [Initialization/Destruction](#initializationdestruction)
+  - [Builder](#builder)
+  - [Context](#context)
+  - [Subcontext](#subcontext)
+  - [Allocator](#allocator)
+  - [Object Creation](#object-creation)
+  - [Object Inspection](#object-inspection)
+  - [Object Container Operations](#object-container-operations)
+  - [Object Type Checking](#object-type-checking)
+  - [Utility](#utility)
 
-- All prototypes and types are defined in `include/ddwaf.h`.
-- Functions follow the conventional C calling convention; when used from C++ be sure to include the header without wrapping it in your own `extern "C"`.
-- Every function that receives or returns `ddwaf_object` instances requires the caller to respect the allocator ownership rules described in the *Allocator APIs* section.
+---
+
+## Enumerations
+
+### DDWAF_OBJ_TYPE
+
+Specifies the type of a ddwaf::object.
+
+| Value | Code | Description |
+|-------|------|-------------|
+| `DDWAF_OBJ_INVALID` | `= 0` |  |
+| `DDWAF_OBJ_NULL` | `= 0x01` |  |
+| `DDWAF_OBJ_BOOL` | `= 0x02` |  |
+| `DDWAF_OBJ_SIGNED` | `= 0x04` |  |
+| `DDWAF_OBJ_UNSIGNED` | `= 0x06` |  |
+| `DDWAF_OBJ_FLOAT` | `= 0x08` |  |
+| `DDWAF_OBJ_STRING` | `= 0x10` |  |
+| `DDWAF_OBJ_LITERAL_STRING` | `= 0x12` |  |
+| `DDWAF_OBJ_SMALL_STRING` | `= 0x14` |  |
+| `DDWAF_OBJ_ARRAY` | `= 0x20` |  |
+| `DDWAF_OBJ_MAP` | `= 0x40` |  |
+
+### DDWAF_RET_CODE
+
+Codes returned by ddwaf_context_eval.
+
+| Value | Code | Description |
+|-------|------|-------------|
+| `DDWAF_ERR_INTERNAL` | `= -3` |  |
+| `DDWAF_ERR_INVALID_OBJECT` | `= -2` |  |
+| `DDWAF_ERR_INVALID_ARGUMENT` | `= -1` |  |
+| `DDWAF_OK` | `= 0` |  |
+| `DDWAF_MATCH` | `= 1` |  |
+
+### DDWAF_LOG_LEVEL
+
+Internal WAF log levels, to be used when setting the minimum log level and cb.
+
+| Value | Code | Description |
+|-------|------|-------------|
+| `DDWAF_LOG_TRACE` | `` |  |
+| `DDWAF_LOG_DEBUG` | `` |  |
+| `DDWAF_LOG_INFO` | `` |  |
+| `DDWAF_LOG_WARN` | `` |  |
+| `DDWAF_LOG_ERROR` | `` |  |
+| `DDWAF_LOG_OFF` | `` |  |
 
 ---
 
-## Preprocessor Macros
+## Type Definitions
 
-### `DDWAF_H`
-Include guard that prevents the header from being processed multiple times. It has no behavioural meaning and should not be referenced directly.
+### Handle Types
 
-### `DDWAF_OBJ_SSTR_SIZE`
-Defines the storage capacity (in bytes) of the inline small-string buffer inside `_ddwaf_object_small_string`. The constant has the value `14`.
+| Type | Definition |
+|------|------------|
+| `ddwaf_handle` | `typedef struct _ddwaf_handle* ddwaf_handle` |
+| `ddwaf_context` | `typedef struct _ddwaf_context* ddwaf_context` |
+| `ddwaf_subcontext` | `typedef struct _ddwaf_subcontext* ddwaf_subcontext` |
+| `ddwaf_builder` | `typedef struct _ddwaf_builder* ddwaf_builder` |
+| `ddwaf_allocator` | `typedef struct _ddwaf_allocator* ddwaf_allocator` |
+| `ddwaf_alloc_fn_type` | `typedef void *() ddwaf_alloc_fn_type(void *, size_t, size_t)` |
+| `ddwaf_free_fn_type` | `typedef void() ddwaf_free_fn_type(void *, void *, size_t, size_t)` |
+| `ddwaf_udata_free_fn_type` | `typedef void() ddwaf_udata_free_fn_type(void *)` |
+| `ddwaf_object` | `typedef union _ddwaf_object ddwaf_object` |
 
-### `static_assert`
-For C compilers that expose `_Static_assert` but not `static_assert`, the header maps `static_assert` to `_Static_assert`. Prefer the standard spelling in your own code.
+### ddwaf_log_cb
 
----
+```c
+ddwaf_log_cb)(DDWAF_LOG_LEVEL level, const char *function, const char *file, unsigned line, const char *message, uint64_t message_len)
+```
 
-## Enumerations
+Callback that libddwaf will call to relay messages to the binding.
+
+**Parameters:**
 
-### `DDWAF_OBJ_TYPE`
-Identifies the payload stored in a `ddwaf_object`.
-
-| Value | Meaning |
-| --- | --- |
-| `DDWAF_OBJ_INVALID` | Sentinel for uninitialised or invalid objects. |
-| `DDWAF_OBJ_NULL` | Represents an explicit `null` value. |
-| `DDWAF_OBJ_BOOL` | Boolean payload. |
-| `DDWAF_OBJ_SIGNED` | Signed 64-bit integer payload. |
-| `DDWAF_OBJ_UNSIGNED` | Unsigned 64-bit integer payload. |
-| `DDWAF_OBJ_FLOAT` | Double-precision floating point payload. |
-| `DDWAF_OBJ_STRING` | Heap-allocated UTF-8 string. |
-| `DDWAF_OBJ_LITERAL_STRING` | Non-owning string literal; libddwaf never frees it. |
-| `DDWAF_OBJ_SMALL_STRING` | Inline UTF-8 string up to `DDWAF_OBJ_SSTR_SIZE`. |
-| `DDWAF_OBJ_ARRAY` | Sequential container of `ddwaf_object`. |
-| `DDWAF_OBJ_MAP` | Associative container of key/value `ddwaf_object` pairs. |
-
-### `DDWAF_RET_CODE`
-Return codes produced by the evaluation functions.
-
-| Value | Meaning |
-| --- | --- |
-| `DDWAF_ERR_INTERNAL` (`-3`) | Unexpected internal error; context state is undefined. |
-| `DDWAF_ERR_INVALID_OBJECT` (`-2`) | Input object did not match the expected structure. |
-| `DDWAF_ERR_INVALID_ARGUMENT` (`-1`) | Call failed because an argument was not valid. |
-| `DDWAF_OK` (`0`) | Call completed without generating matches or errors. |
-| `DDWAF_MATCH` (`1`) | Call completed with at least one rule match. |
-
-### `DDWAF_LOG_LEVEL`
-Verbosity levels used by the logging subsystem.
-
-`DDWAF_LOG_TRACE`, `DDWAF_LOG_DEBUG`, `DDWAF_LOG_INFO`, `DDWAF_LOG_WARN`, `DDWAF_LOG_ERROR`, `DDWAF_LOG_OFF`.
+- `level`: The logging level.
+- `function`: The native function that emitted the message. (nonnull)
+- `file`: The file of the native function that emmitted the message. (nonnull)
+- `line`: The line where the message was emmitted.
+- `message`: The size of the logging message. NUL-terminated
+- `message_len`: The length of the logging message (excluding NUL terminator).
 
 ---
 
-## Type Aliases and Callback Signatures
+## Functions
 
-| Symbol | Description |
-| --- | --- |
-| `ddwaf_handle` | Opaque pointer to a WAF instance returned by `ddwaf_init` or `ddwaf_builder_build_instance`. |
-| `ddwaf_context` | Opaque pointer representing an evaluation context obtained via `ddwaf_context_init`. |
-| `ddwaf_subcontext` | Opaque pointer representing a lightweight clone of a context created with `ddwaf_subcontext_init`. |
-| `ddwaf_builder` | Opaque pointer to the configuration builder returned by `ddwaf_builder_init`. |
-| `ddwaf_allocator` | Opaque pointer identifying an allocator instance. |
-| `ddwaf_alloc_fn_type` | Signature for custom allocation callbacks used with `ddwaf_user_allocator_init`. |
-| `ddwaf_free_fn_type` | Signature for custom free callbacks passed to `ddwaf_user_allocator_init`. |
-| `ddwaf_udata_free_fn_type` | Optional destructor for the user data passed to `ddwaf_user_allocator_init`. |
+### Initialization/Destruction
 
-### `ddwaf_log_cb`
+#### ddwaf_init
 
 ```c
-typedef void (*ddwaf_log_cb)(
-    DDWAF_LOG_LEVEL level,
-    const char *function,
-    const char *file,
-    unsigned line,
-    const char *message,
-    uint64_t message_len);
+ddwaf_handle ddwaf_init(const ddwaf_object * ruleset, ddwaf_object * diagnostics)
 ```
 
-Logging callback used by `ddwaf_set_log_cb`. The strings are null-terminated, and `message_len` excludes the terminator.
+Initialize a ddwaf instance
 
----
+**Parameters:**
 
-## Structure and Union Layouts
+- `ruleset`: ddwaf::object map containing rules, exclusions, rules_override and rules_data. (nonnull)
+- `diagnostics`: Optional ruleset parsing diagnostics. (nullable)
 
-The header exposes the internal representation of `ddwaf_object` for interoperability. Always prefer the accessor helpers instead of touching fields directly unless you are implementing a low-level binding.
+**Returns:** Handle to the WAF instance or NULL on error.
 
-- Primitive wrappers: `_ddwaf_object_bool`, `_ddwaf_object_signed`, `_ddwaf_object_unsigned`, `_ddwaf_object_float`, `_ddwaf_object_string`, `_ddwaf_object_small_string`.
-- Container wrappers: `_ddwaf_object_array`, `_ddwaf_object_map`, `_ddwaf_object_kv`.
-- Tagged union: `_ddwaf_object` (aliased as `ddwaf_object`).
+> **Note:** If ruleset is NULL, the diagnostics object will not be initialised.
 
-The type tag stored in `via` must match the helper you use; mixing the two is undefined behaviour.
+> **Note:** The deallocation of the diagnostics must be made with default allocator.
 
----
+#### ddwaf_destroy
+
+```c
+void ddwaf_destroy(ddwaf_handle handle)
+```
+
+Destroy a WAF instance.
 
-## Library Lifecycle Functions
+**Parameters:**
 
-### `ddwaf_init`
+- `handle`: Handle to the WAF instance.
+
+#### ddwaf_known_addresses
 
 ```c
-ddwaf_handle ddwaf_init(const ddwaf_object *ruleset, ddwaf_object *diagnostics);
+const char *const * ddwaf_known_addresses(const ddwaf_handle handle, uint32_t * size)
 ```
 
-Creates a WAF instance from a configuration object. The `ruleset` must be a map that contains the rule definitions, overrides, data, and exclusions. When supplied, `diagnostics` receives parser warnings and errors; destroy it with `ddwaf_object_destroy` after use. Returns `NULL` on failure.
+Get an array of known (root) addresses used by rules, exclusion filters and processors. This array contains both required and optional addresses. A more accurate distinction between required and optional addresses is provided within the diagnostics.
+
+**Parameters:**
+
+- `handle`: Handle to the WAF instance.
+- `size`: Output parameter in which the size will be returned. The value of size will be 0 if the return value is NULL.
 
-### `ddwaf_destroy`
+**Returns:** NULL if empty, otherwise a pointer to an array with size elements.
+
+> **Note:** This function is not thread-safe
+
+> **Note:** The returned array should be considered invalid after calling ddwaf_destroy on the handle used to obtain it.
+
+#### ddwaf_known_actions
 
 ```c
-void ddwaf_destroy(ddwaf_handle handle);
+const char *const * ddwaf_known_actions(const ddwaf_handle handle, uint32_t * size)
 ```
 
-Destroys a WAF instance and releases its resources. Safe to call with `NULL`.
+Get an array of all the action types which could be triggered as a result of the current set of rules and exclusion filters.
+
+**Parameters:**
+
+- `handle`: Handle to the WAF instance.
+- `size`: Output parameter in which the size will be returned. The value of size will be 0 if the return value is NULL.
+
+**Returns:** NULL if empty, otherwise a pointer to an array with size elements.
 
-### `ddwaf_get_version`
+> **Note:** This function is not thread-safe
+
+> **Note:** The returned array should be considered invalid after calling ddwaf_destroy on the handle used to obtain it.
+
+### Builder
+
+#### ddwaf_builder_init
 
 ```c
-const char *ddwaf_get_version(void);
+ddwaf_builder ddwaf_builder_init()
 ```
 
-Returns a null-terminated string describing the libddwaf version. The pointer remains owned by the library.
+Initialize an instace of the waf builder.
 
-### `ddwaf_set_log_cb`
+**Returns:** Handle to the builer instance or NULL on error.
+
+> **Note:** If config is NULL, default values will be used
+
+#### ddwaf_builder_add_or_update_config
 
 ```c
-bool ddwaf_set_log_cb(ddwaf_log_cb cb, DDWAF_LOG_LEVEL min_level);
+bool ddwaf_builder_add_or_update_config(ddwaf_builder builder, const char * path, uint32_t path_len, const ddwaf_object * config, ddwaf_object * diagnostics)
 ```
 
-Installs a callback that receives libddwaf log messages at or above `min_level`. Passing `NULL` disables logging. Returns `false` if the logging system rejects the callback (for example, when called concurrently).
+Adds or updates a configuration based on the given path, which must be a unique identifier for the provided configuration.
 
----
+**Parameters:**
 
-## Introspection Helpers
+- `builder`: Builder to perform the operation on. (nonnull)
+- `path`: A string containing the path of the configuration, this must uniquely identify the configuration. (nonnull)
+- `path_len`: The length of the string contained within path.
+- `config`: ddwaf::object map containing rules, exclusions, rules_override and rules_data. (nonnull)
+- `diagnostics`: Optional ruleset parsing diagnostics. (nullable)
 
-### `ddwaf_known_addresses`
+**Returns:** Whether the operation succeeded (true) or failed (false).
+
+> **Note:** if any of the arguments are NULL, the diagnostics object will not be initialised.
+
+> **Note:** The memory associated with the path, config and diagnostics must be freed by the caller.
+
+> **Note:** The deallocation of the diagnostics must be made with default allocator.
+
+> **Note:** This function is not thread-safe.
+
+#### ddwaf_builder_remove_config
 
 ```c
-const char *const *ddwaf_known_addresses(const ddwaf_handle handle, uint32_t *size);
+bool ddwaf_builder_remove_config(ddwaf_builder builder, const char * path, uint32_t path_len)
 ```
 
-Returns the null-terminated root addresses referenced by the active configuration. The returned array is owned by libddwaf and becomes invalid after `ddwaf_destroy`.
+Removes a configuration based on the provided path.
+
+**Parameters:**
 
-### `ddwaf_known_actions`
+- `builder`: Builder to perform the operation on. (nonnull)
+- `path`: A string containing the path of the configuration to be removed. (nonnull)
+- `path_len`: The length of the string contained within path.
+
+**Returns:** Whether the operation succeeded (true) or failed (false).
+
+> **Note:** The memory associated with the path must be freed by the caller.
+
+> **Note:** This function is not thread-safe.
+
+#### ddwaf_builder_build_instance
 
 ```c
-const char *const *ddwaf_known_actions(const ddwaf_handle handle, uint32_t *size);
+ddwaf_handle ddwaf_builder_build_instance(ddwaf_builder builder)
 ```
 
-Lists the action identifiers that may appear in evaluation results. Ownership rules mirror `ddwaf_known_addresses`.
+Builds a ddwaf instance based on the current set of configurations.
 
----
+**Parameters:**
+
+- `builder`: Builder to perform the operation on. (nonnull)
 
-## Context APIs
+**Returns:** Handle to the new WAF instance or NULL if there was an error.
 
-### `ddwaf_context_init`
+> **Note:** This function is not thread-safe.
+
+#### ddwaf_builder_get_config_paths
 
 ```c
-ddwaf_context ddwaf_context_init(const ddwaf_handle handle, ddwaf_allocator output_alloc);
+uint32_t ddwaf_builder_get_config_paths(ddwaf_builder builder, ddwaf_object * paths, const char * filter, uint32_t filter_len)
 ```
 
-Creates an evaluation context bound to a WAF instance. The `output_alloc` allocator is used to allocate result objects returned by `ddwaf_context_eval` and `ddwaf_subcontext_eval`. Returns `NULL` on allocation errors.
+Provides an array of the currently loaded paths, optionally matching the regex provided in filter. In addition, the count is provided as the return value, allowing paths to be nullptr.
+
+**Parameters:**
+
+- `builder`: Builder to perform the operation on. (nonnull)
+- `paths`: The object in which paths will be returned, as an array of strings. If NULL, only the count is provided. (nullable)
+- `filter`: An optional string regex to filter the provided paths. The provided regular expression is used unanchored so matches can be found at any point within the path, any necessary anchors must be explicitly added to the regex. (nullable).
+- `filter_len`: The length of the filter string (or 0 otherwise).
+
+**Returns:** The total number of configurations loaded or, if provided, the number of those matching the filter.
+
+> **Note:** This function is not thread-safe and the memory of the paths object must be freed by the caller using the default allocator.
 
-### `ddwaf_context_eval`
+#### ddwaf_builder_destroy
 
 ```c
-DDWAF_RET_CODE ddwaf_context_eval(
-    ddwaf_context context,
-    ddwaf_object *data,
-    ddwaf_allocator alloc,
-    ddwaf_object *result,
-    uint64_t timeout);
+void ddwaf_builder_destroy(ddwaf_builder builder)
 ```
 
-Evaluates a request payload. `data` must be a map keyed by address. The `alloc` parameter is the allocator used to free the `data` object after evaluation completes (if non-null). When `result` is non-null and the return code is `DDWAF_OK` or `DDWAF_MATCH`, it contains detailed events and metadata allocated with the `output_alloc` from `ddwaf_context_init`, and must be released with `ddwaf_object_destroy(result, output_alloc)`. The function enforces a microsecond timeout.
+Destroy an instance of the builder.
 
-### `ddwaf_context_destroy`
+**Parameters:**
+
+- `builder`: Builder to perform the operation on. (nonnull)
+
+### Context
+
+#### ddwaf_context_init
 
 ```c
-void ddwaf_context_destroy(ddwaf_context context);
+ddwaf_context ddwaf_context_init(const ddwaf_handle handle, ddwaf_allocator output_alloc)
 ```
 
-Destroys a context and releases any persistent copies of request data using the allocator associated with the context.
+Context object to perform matching using the provided WAF instance.
 
----
+**Parameters:**
+
+- `handle`: Handle of the WAF instance containing the ruleset definition. (nonnull)
+- `output_alloc`: Allocator used to serve output objects created during evaluation (nonnull)
+
+**Returns:** Handle to the context instance.
 
-## Subcontext APIs
+> **Note:** The WAF instance needs to be valid for the lifetime of the context.
 
-### `ddwaf_subcontext_init`
+#### ddwaf_context_eval
 
 ```c
-ddwaf_subcontext ddwaf_subcontext_init(ddwaf_context context);
+DDWAF_RET_CODE ddwaf_context_eval(ddwaf_context context, ddwaf_object * data, ddwaf_allocator alloc, ddwaf_object * result, uint64_t timeout)
 ```
 
-Creates a lightweight clone that shares persistent state with its parent context. The subcontext inherits the allocator that was passed to `ddwaf_context_init`.
+Perform a matching operation on the provided data
 
-### `ddwaf_subcontext_eval`
+**Parameters:**
+
+- `context`: WAF context to be used in this run, this will determine the ruleset which will be used and it will also ensure that parameters are taken into account across runs (nonnull)
+- `data`: (nonnull) Data on which to perform the pattern matching. This data will be stored by the context and used across multiple calls to this function or ddwaf_subcontext_eval. Once the context is destroyed, the user defined allocator will be used to free the data provided. Note that the data passed must be valid until the destruction of the context. The object must be a map of {string,
+- `alloc`: (nullable) Allocator used to free the data provided. If NULL, the data will not be freed.
+- `result`: (nullable) Object map containing the following items:
+- events: an array of the generated events.
+- actions: a map of the generated actions in the format: "{action type: { <parameter map> }, ...}"
+- duration: an unsigned specifying the total runtime of the call in nanoseconds.
+- timeout: whether there has been a timeout during the call.
+- attributes: a map containing all derived objects in the format: {tag, value}
+- keep: whether the data contained herein must override any transport sampling through the relevant mechanism. This structure must be freed by the caller using the output allocator provided through ddwaf_context_init. The object will contain all specified keys when the value returned by ddwaf_context_eval is either DDWAF_OK or DDWAF_MATCH and will be empty otherwise. IMPORTANT: This object is not allocated with the allocator passed in this call. It uses the allocator given to ddwaf_context_init instead.
+- `timeout`: Maximum time budget in microseconds.
+
+**Returns:** Return code of the operation.
+
+**Return Values:**
+
+- `DDWAF_ERR_INVALID_ARGUMENT`: The context is invalid, the data will not be freed.
+- `DDWAF_ERR_INVALID_OBJECT`: The data provided didn't match the desired structure or contained invalid objects, the data will be freed by this function.
+- `DDWAF_ERR_INTERNAL`: There was an unexpected error and the operation did not succeed. The state of the WAF is undefined if this error is produced and the ownership of the data is unknown. The result structure will not be filled if this error occurs.
+
+#### ddwaf_context_destroy
 
 ```c
-DDWAF_RET_CODE ddwaf_subcontext_eval(
-    ddwaf_subcontext subcontext,
-    ddwaf_object *data,
-    ddwaf_allocator alloc,
-    ddwaf_object *result,
-    uint64_t timeout);
+void ddwaf_context_destroy(ddwaf_context context)
 ```
 
-Evaluates request data against a subcontext using the same semantics as `ddwaf_context_eval`. The `alloc` parameter is used to free the `data` object. The `result` object, when populated, is allocated with the `output_alloc` from the parent context's `ddwaf_context_init` call and must be destroyed with that same allocator.
+Performs the destruction of the context, freeing the data passed to it through ddwaf_context_eval using the provided allocator during evaluation.
+
+**Parameters:**
 
-### `ddwaf_subcontext_destroy`
+- `context`: Context to destroy. (nonnull)
+
+### Subcontext
+
+#### ddwaf_subcontext_init
 
 ```c
-void ddwaf_subcontext_destroy(ddwaf_subcontext subcontext);
+ddwaf_subcontext ddwaf_subcontext_init(ddwaf_context context)
 ```
 
-Destroys the subcontext and releases any data cached within it.
+Subcontext object to perform matching using the provided WAF instance.
 
----
+**Parameters:**
+
+- `context`: Context from which to derive this subcontext. (nonnull)
+
+**Returns:** Handle to the subcontext instance.
+
+#### ddwaf_subcontext_eval
+
+```c
+DDWAF_RET_CODE ddwaf_subcontext_eval(ddwaf_subcontext subcontext, ddwaf_object * data, ddwaf_allocator alloc, ddwaf_object * result, uint64_t timeout)
+```
+
+Perform a matching operation on the provided data
+
+**Parameters:**
 
-## Builder APIs
+- `subcontext`: WAF subcontext to be used in this run, this will determine the ruleset which will be used and it will also ensure that parameters are taken into account across runs (nonnull)
+- `data`: (nonnull) Data on which to perform the pattern matching. This data will be stored by the subcontext and used across multiple calls to this function. Once the subcontext is destroyed, the user defined allocator will be used to free the data provided. Note that the data passed must be valid until the destruction of the subcontext. The object must be a map of {string,
+- `alloc`: (nullable) Allocator used to free the data provided. If NULL, the data will not be freed.
+- `result`: (nullable) Object map containing the following items:
+- events: an array of the generated events.
+- actions: a map of the generated actions in the format: "{action type: { <parameter map> }, ...}"
+- duration: an unsigned specifying the total runtime of the call in nanoseconds.
+- timeout: whether there has been a timeout during the call.
+- attributes: a map containing all derived objects in the format: {tag, value}
+- keep: whether the data contained herein must override any transport sampling through the relevant mechanism. This structure must be freed by the caller and will contain all specified keys when the value returned by ddwaf_subcontext_eval is either DDWAF_OK or DDWAF_MATCH and will be empty otherwise. IMPORTANT: This object is not allocated with the allocator passed in this call. It uses the allocator given to ddwaf_context_init instead.
+- `timeout`: Maximum time budget in microseconds.
 
-Use the builder when you need to manage multiple configurations or build WAF instances incrementally.
+**Returns:** Return code of the operation.
 
-### `ddwaf_builder_init`
+**Return Values:**
+
+- `DDWAF_ERR_INVALID_ARGUMENT`: The subcontext is invalid, the data will not be freed.
+- `DDWAF_ERR_INVALID_OBJECT`: The data provided didn't match the desired structure or contained invalid objects, the data will be freed by this function.
+- `DDWAF_ERR_INTERNAL`: There was an unexpected error and the operation did not succeed. The state of the WAF is undefined if this error is produced and the ownership of the data is unknown. The result structure will not be filled if this error occurs.
+
+#### ddwaf_subcontext_destroy
 
 ```c
-ddwaf_builder ddwaf_builder_init(void);
+void ddwaf_subcontext_destroy(ddwaf_subcontext subcontext)
 ```
 
-Allocates a new builder instance. Returns `NULL` on failure.
+Performs the destruction of the subcontext, freeing the data passed to it through ddwaf_subcontext_eval using the used-defined allocator.
+
+**Parameters:**
 
-### `ddwaf_builder_add_or_update_config`
+- `subcontext`: subcontext to destroy. (nonnull)
+
+### Allocator
+
+#### ddwaf_get_default_allocator
 
 ```c
-bool ddwaf_builder_add_or_update_config(
-    ddwaf_builder builder,
-    const char *path,
-    uint32_t path_len,
-    const ddwaf_object *config,
-    ddwaf_object *diagnostics);
+ddwaf_allocator ddwaf_get_default_allocator()
 ```
 
-Registers or refreshes a configuration identified by `path`. The `config` object is parsed immediately; on error the return value is `false` and `diagnostics` (when provided) contains parser feedback.
+Returns the default allocator used by the library.
+
+**Returns:** Allocator handle.
 
-### `ddwaf_builder_remove_config`
+#### ddwaf_synchronized_pool_allocator_init
 
 ```c
-bool ddwaf_builder_remove_config(
-    ddwaf_builder builder,
-    const char *path,
-    uint32_t path_len);
+ddwaf_allocator ddwaf_synchronized_pool_allocator_init()
 ```
 
-Deletes the configuration identified by `path`. Returns `false` if the path was not known.
+Creates a thread-safe pool allocator. Allocations are served from internal pools sized by block class to reduce fragmentation and allocator overhead; memory freed via the corresponding ddwaf APIs is returned to the pools for reuse. This allocator can be shared across threads safely.
 
-### `ddwaf_builder_build_instance`
+**Returns:** Allocator handle.
+
+#### ddwaf_unsynchronized_pool_allocator_init
 
 ```c
-ddwaf_handle ddwaf_builder_build_instance(ddwaf_builder builder);
+ddwaf_allocator ddwaf_unsynchronized_pool_allocator_init()
 ```
 
-Compiles the currently loaded configurations into a WAF instance. Returns `NULL` when compilation fails.
+Creates a pool allocator without internal synchronization. It provides the same pooling characteristics as the synchronized variant but with lower overhead. This allocator must not be used concurrently from multiple threads unless externally synchronized.
+
+**Returns:** Allocator handle.
 
-### `ddwaf_builder_get_config_paths`
+#### ddwaf_monotonic_allocator_init
 
 ```c
-uint32_t ddwaf_builder_get_config_paths(
-    ddwaf_builder builder,
-    ddwaf_object *paths,
-    const char *filter,
-    uint32_t filter_len);
+ddwaf_allocator ddwaf_monotonic_allocator_init()
 ```
 
-Counts the configurations present in the builder and optionally populates `paths` with their identifiers. If `filter` is non-null, only the paths matching the unanchored regular expression are reported.
+Creates a monotonic (growing) allocator. Allocations are fast and never freed individually; all memory is reclaimed only when the allocator is destroyed. This allocator must not be used concurrently from multiple threads unless externally synchronized.
+
+**Returns:** Allocator handle.
 
-### `ddwaf_builder_destroy`
+#### ddwaf_user_allocator_init
 
 ```c
-void ddwaf_builder_destroy(ddwaf_builder builder);
+ddwaf_allocator ddwaf_user_allocator_init(ddwaf_alloc_fn_type alloc_fn, ddwaf_free_fn_type free_fn, void * udata, ddwaf_udata_free_fn_type udata_free_fn)
 ```
 
-Releases all resources associated with the builder.
+Creates an allocator that forwards allocation and deallocation to user provided callbacks.
 
----
+**Parameters:**
+
+- `alloc_fn`: Allocation callback. It receives the opaque `udata`, the requested `size` and `alignment`, and must return a pointer meeting the alignment requirements or NULL on failure. (nonnull)
+- `free_fn`: Deallocation callback. It receives the opaque `udata`, the pointer to free, and the original `size` and `alignment`. It must be able to free any pointer previously returned by `alloc_fn`. (nonnull)
+- `udata`: Opaque user pointer forwarded to both callbacks; can be used to carry custom state. (nullable)
+- `udata_free_fn`: User data destruction callback, used to perform any relevant destruction and reclamation operations on the provided user data.
 
-## Allocator APIs
+**Returns:** Allocator handle.
 
-### `ddwaf_get_default_allocator`
+#### ddwaf_allocator_alloc
 
 ```c
-ddwaf_allocator ddwaf_get_default_allocator(void);
+void * ddwaf_allocator_alloc(ddwaf_allocator alloc, size_t bytes, size_t alignment)
 ```
 
-Returns the allocator used internally by libddwaf. The handle is owned by the library and must not be destroyed.
+Allocates a block of memory from the given allocator with the requested alignment.
+
+**Parameters:**
 
-### Pool and monotonic allocators
+- `alloc`: Allocator to use for the allocation. (nonnull)
+- `bytes`: Number of bytes to allocate.
+- `alignment`: Required alignment in bytes; must be a power of two.
+
+**Returns:** Pointer to the allocated memory or NULL on failure.
+
+#### ddwaf_allocator_free
 
 ```c
-ddwaf_allocator ddwaf_synchronized_pool_allocator_init(void);
-ddwaf_allocator ddwaf_unsynchronized_pool_allocator_init(void);
-ddwaf_allocator ddwaf_monotonic_allocator_init(void);
+void ddwaf_allocator_free(ddwaf_allocator alloc, void * p, size_t bytes, size_t alignment)
 ```
 
-Factory functions that create dedicated allocators. Destroy them with `ddwaf_allocator_destroy` when no outstanding allocations remain.
+Releases a block of memory previously obtained via ddwaf_allocator_alloc from the same allocator.
+
+**Parameters:**
 
-### `ddwaf_user_allocator_init`
+- `alloc`: Allocator used for the original allocation. (nonnull)
+- `p`: Pointer to the memory to free. (nonnull)
+- `bytes`: Size in bytes of the original allocation.
+- `alignment`: Alignment in bytes of the original allocation.
+
+#### ddwaf_allocator_destroy
 
 ```c
-ddwaf_allocator ddwaf_user_allocator_init(
-    ddwaf_alloc_fn_type alloc_fn,
-    ddwaf_free_fn_type free_fn,
-    void *udata,
-    ddwaf_udata_free_fn_type udata_free_fn);
+void ddwaf_allocator_destroy(ddwaf_allocator alloc)
 ```
 
-Wraps user-provided allocation routines in a libddwaf-compatible allocator. When `udata_free_fn` is non-null it is called automatically during `ddwaf_allocator_destroy`.
+Destroys an allocator created by one of the ddwaf_*_allocator_init functions and releases any internal resources it holds.
+
+**Parameters:**
+
+- `alloc`: Allocator to destroy. (nonnull)
 
-### Allocation helpers
+### Object Creation
+
+#### ddwaf_object_set_invalid
 
 ```c
-void *ddwaf_allocator_alloc(ddwaf_allocator alloc, size_t bytes, size_t alignment);
-void ddwaf_allocator_free(ddwaf_allocator alloc, void *p, size_t bytes, size_t alignment);
-void ddwaf_allocator_destroy(ddwaf_allocator alloc);
+ddwaf_object * ddwaf_object_set_invalid(ddwaf_object * object)
 ```
 
-Low-level allocation routines. The `alloc` argument must be the same handle returned by the allocator factory. `ddwaf_allocator_destroy` is a no-op for the default allocator but must be called for user-created allocators once all objects have been released.
+Creates an invalid object.
 
----
+**Parameters:**
+
+- `object`: Object to perform the operation on. (nonnull)
+
+**Returns:** A pointer to the passed object or NULL if the operation failed.
+
+#### ddwaf_object_set_null
 
-## Object Construction Helpers
+```c
+ddwaf_object * ddwaf_object_set_null(ddwaf_object * object)
+```
+
+Creates an null object. Provides a different semantical value to invalid as it can be used to signify that a value is null rather than of an unknown type.
+
+**Parameters:**
+
+- `object`: Object to perform the operation on. (nonnull)
+
+**Returns:** A pointer to the passed object or NULL if the operation failed.
 
-Each helper returns the pointer passed in on success and `NULL` on failure unless stated otherwise.
+#### ddwaf_object_set_string
 
 ```c
-ddwaf_object *ddwaf_object_set_invalid(ddwaf_object *object);
-ddwaf_object *ddwaf_object_set_null(ddwaf_object *object);
-ddwaf_object *ddwaf_object_set_string(ddwaf_object *object, const char *string, uint32_t length, ddwaf_allocator alloc);
-ddwaf_object *ddwaf_object_set_string_literal(ddwaf_object *object, const char *string, uint32_t length);
-ddwaf_object *ddwaf_object_set_string_nocopy(ddwaf_object *object, const char *string, uint32_t length);
-ddwaf_object *ddwaf_object_set_unsigned(ddwaf_object *object, uint64_t value);
-ddwaf_object *ddwaf_object_set_signed(ddwaf_object *object, int64_t value);
-ddwaf_object *ddwaf_object_set_bool(ddwaf_object *object, bool value);
-ddwaf_object *ddwaf_object_set_float(ddwaf_object *object, double value);
-ddwaf_object *ddwaf_object_set_array(ddwaf_object *object, uint16_t capacity, ddwaf_allocator alloc);
-ddwaf_object *ddwaf_object_set_map(ddwaf_object *object, uint16_t capacity, ddwaf_allocator alloc);
+ddwaf_object * ddwaf_object_set_string(ddwaf_object * object, const char * string, uint32_t length, ddwaf_allocator alloc)
 ```
 
-- The `_string_literal` variant never copies the buffer; the caller must guarantee its lifetime exceeds that of the object.
-- The `_string_nocopy` variant assumes the buffer was allocated by the same allocator that will be used during destruction.
-- Arrays and maps allocate storage with the capacity supplied; call `ddwaf_object_insert*` to populate them.
+Creates an object from a string.
 
-### Container insertion and JSON parsing
+**Parameters:**
+
+- `object`: Object to perform the operation on. (nonnull)
+- `string`: String to initialise the object with, this string will be copied. (nonnull)
+- `length`: Length of the string.
+- `alloc`: Allocator to use for memory allocation. (nonnull)
+
+**Returns:** A pointer to the passed object or NULL if the operation failed.
+
+#### ddwaf_object_set_string_literal
 
 ```c
-ddwaf_object *ddwaf_object_insert(ddwaf_object *array, ddwaf_allocator alloc);
-ddwaf_object *ddwaf_object_insert_key(ddwaf_object *map, const char *key, uint32_t length, ddwaf_allocator alloc);
-ddwaf_object *ddwaf_object_insert_literal_key(ddwaf_object *map, const char *key, uint32_t length, ddwaf_allocator alloc);
-ddwaf_object *ddwaf_object_insert_key_nocopy(ddwaf_object *map, const char *key, uint32_t length, ddwaf_allocator alloc);
-bool ddwaf_object_from_json(ddwaf_object *output, const char *json_str, uint32_t length, ddwaf_allocator alloc);
+ddwaf_object * ddwaf_object_set_string_literal(ddwaf_object * object, const char * string, uint32_t length)
 ```
 
-Insertion helpers expand array or map containers by one element and return the slot to be filled. `ddwaf_object_from_json` parses a JSON document into a `ddwaf_object`; destroy the result with `ddwaf_object_destroy`.
+Creates an object from a literal string and its length.
 
----
+**Parameters:**
+
+- `object`: Object to perform the operation on. (nonnull)
+- `string`: Literal string to initialise the object with, this string will not be copied and must remain valid for the lifetime of the object. (nonnull)
+- `length`: Length of the string.
 
-## Object Accessors and Predicates
+**Returns:** A pointer to the passed object or NULL if the operation failed.
 
-### Introspection
+#### ddwaf_object_set_string_nocopy
 
 ```c
-DDWAF_OBJ_TYPE ddwaf_object_get_type(const ddwaf_object *object);
-size_t ddwaf_object_get_size(const ddwaf_object *object);
-size_t ddwaf_object_get_length(const ddwaf_object *object);
-const char *ddwaf_object_get_string(const ddwaf_object *object, size_t *length);
-uint64_t ddwaf_object_get_unsigned(const ddwaf_object *object);
-int64_t ddwaf_object_get_signed(const ddwaf_object *object);
-double ddwaf_object_get_float(const ddwaf_object *object);
-bool ddwaf_object_get_bool(const ddwaf_object *object);
+ddwaf_object * ddwaf_object_set_string_nocopy(ddwaf_object * object, const char * string, uint32_t length)
 ```
 
-Retrieve metadata or scalar values from an object. When the object is not of the expected type, the returned value is zero or `NULL`.
+Creates an object with the string pointer and length provided, without copying the string.
+
+**Parameters:**
 
-### Container lookup
+- `object`: Object to perform the operation on. (nonnull)
+- `string`: String pointer to initialise the object with, this string will not be copied and must remain valid for the lifetime of the object. (nonnull)
+- `length`: Length of the string.
+
+**Returns:** A pointer to the passed object or NULL if the operation failed.
+
+> **Note:** The provided string must have been allocated with the same allocator used with ddwaf_object_destroy.
+
+#### ddwaf_object_set_unsigned
 
 ```c
-const ddwaf_object *ddwaf_object_at_key(const ddwaf_object *object, size_t index);
-const ddwaf_object *ddwaf_object_at_value(const ddwaf_object *object, size_t index);
-const ddwaf_object *ddwaf_object_find(const ddwaf_object *object, const char *key, size_t length);
+ddwaf_object * ddwaf_object_set_unsigned(ddwaf_object * object, uint64_t value)
 ```
 
-`ddwaf_object_at_key` returns the key object for the entry at `index` when iterating over a map (arrays do not expose keys). `ddwaf_object_at_value` returns the corresponding value object. `ddwaf_object_find` performs a direct lookup by key and returns the associated value.
+Creates an object using an unsigned integer (64-bit). The resulting object will contain an unsigned integer as opposed to a string.
+
+**Parameters:**
+
+- `object`: Object to perform the operation on. (nonnull)
+- `value`: Integer to initialise the object with.
+
+**Returns:** A pointer to the passed object or NULL if the operation failed.
 
-### Cloning
+#### ddwaf_object_set_signed
 
 ```c
-ddwaf_object *ddwaf_object_clone(
-    const ddwaf_object *source,
-    ddwaf_object *destination,
-    ddwaf_allocator alloc);
+ddwaf_object * ddwaf_object_set_signed(ddwaf_object * object, int64_t value)
 ```
 
-Performs a deep copy of `source` into `destination`, allocating any necessary storage from `alloc`. The destination must be destroyed with the same allocator once it is no longer needed.
+Creates an object using a signed integer (64-bit). The resulting object will contain a signed integer as opposed to a string.
 
-### Type predicates
+**Parameters:**
+
+- `object`: Object to perform the operation on. (nonnull)
+- `value`: Integer to initialise the object with.
+
+**Returns:** A pointer to the passed object or NULL if the operation failed.
+
+#### ddwaf_object_set_bool
 
 ```c
-bool ddwaf_object_is_invalid(const ddwaf_object *object);
-bool ddwaf_object_is_null(const ddwaf_object *object);
-bool ddwaf_object_is_bool(const ddwaf_object *object);
-bool ddwaf_object_is_signed(const ddwaf_object *object);
-bool ddwaf_object_is_unsigned(const ddwaf_object *object);
-bool ddwaf_object_is_float(const ddwaf_object *object);
-bool ddwaf_object_is_string(const ddwaf_object *object);
-bool ddwaf_object_is_array(const ddwaf_object *object);
-bool ddwaf_object_is_map(const ddwaf_object *object);
+ddwaf_object * ddwaf_object_set_bool(ddwaf_object * object, bool value)
 ```
 
-Convenience wrappers that compare the object type to the respective category.
+Creates an object using a boolean, the resulting object will contain a boolean as opposed to a string.
+
+**Parameters:**
+
+- `object`: Object to perform the operation on. (nonnull)
+- `value`: Boolean to initialise the object with.
+
+**Returns:** A pointer to the passed object or NULL if the operation failed.
 
-### Destruction
+#### ddwaf_object_set_float
 
 ```c
-void ddwaf_object_destroy(ddwaf_object *object, ddwaf_allocator alloc);
+ddwaf_object * ddwaf_object_set_float(ddwaf_object * object, double value)
 ```
 
-Reclaims any memory owned by the object. Always pass the allocator that was used to build it.
+Creates an object using a double, the resulting object will contain a double as opposed to a string.
 
----
+**Parameters:**
+
+- `object`: Object to perform the operation on. (nonnull)
+- `value`: Double to initialise the object with.
+
+**Returns:** A pointer to the passed object or NULL if the operation failed.
+
+#### ddwaf_object_set_array
+
+```c
+ddwaf_object * ddwaf_object_set_array(ddwaf_object * object, uint16_t capacity, ddwaf_allocator alloc)
+```
+
+Creates an array object, for sequential storage.
+
+**Parameters:**
+
+- `object`: Object to perform the operation on. (nonnull)
+- `capacity`: Initial capacity of the array.
+- `alloc`: Allocator to use for memory allocation. (nonnull)
+
+**Returns:** A pointer to the passed object or NULL if the operation failed.
+
+#### ddwaf_object_set_map
+
+```c
+ddwaf_object * ddwaf_object_set_map(ddwaf_object * object, uint16_t capacity, ddwaf_allocator alloc)
+```
+
+Creates a map object, for key-value storage.
+
+**Parameters:**
+
+- `object`: Object to perform the operation on. (nonnull)
+- `capacity`: Initial capacity of the map.
+- `alloc`: Allocator to use for memory allocation. (nonnull)
+
+**Returns:** A pointer to the passed object or NULL if the operation failed.
+
+#### ddwaf_object_from_json
+
+```c
+bool ddwaf_object_from_json(ddwaf_object * output, const char * json_str, uint32_t length, ddwaf_allocator alloc)
+```
+
+Creates a ddwaf_object from a JSON string. The JSON will be parsed and converted into the appropriate ddwaf_object structure, supporting all JSON types including objects, arrays, strings, numbers, booleans, and null values.
+
+**Parameters:**
+
+- `output`: Object to populate with the parsed JSON data. (nonnull)
+- `json_str`: The JSON string to parse. (nonnull)
+- `length`: Length of the JSON string.
+- `alloc`: Allocator to use for memory allocation. (nonnull)
+
+**Returns:** The success or failure of the operation.
+
+> **Note:** The output object must be freed by the caller using ddwaf_object_free.
+
+> **Note:** If parsing fails, the output object will be left in an undefined state.
+
+> **Note:** The provided JSON string is owned by the caller.
+
+### Object Inspection
+
+#### ddwaf_object_get_type
+
+```c
+DDWAF_OBJ_TYPE ddwaf_object_get_type(const ddwaf_object * object)
+```
+
+Returns the type of the object.
+
+**Parameters:**
+
+- `object`: The object from which to get the type.
+
+**Returns:** The object type of DDWAF_OBJ_INVALID if NULL.
+
+#### ddwaf_object_get_size
+
+```c
+size_t ddwaf_object_get_size(const ddwaf_object * object)
+```
+
+Returns the size of the container object.
+
+**Parameters:**
+
+- `object`: The object from which to get the size.
+
+**Returns:** The object size or 0 if the object is not a container (array, map).
+
+#### ddwaf_object_get_length
+
+```c
+size_t ddwaf_object_get_length(const ddwaf_object * object)
+```
+
+Returns the length of the string object.
+
+**Parameters:**
+
+- `object`: The object from which to get the length.
+
+**Returns:** The string length or 0 if the object is not a string.
+
+#### ddwaf_object_get_string
+
+```c
+const char * ddwaf_object_get_string(const ddwaf_object * object, size_t * length)
+```
+
+Returns the string contained within the object.
+
+**Parameters:**
+
+- `object`: The object from which to get the string.
+- `length`: Output parameter on which to return the length of the string, this parameter is optional / nullable.
+
+**Returns:** The string of the object or NULL if the object is not a string.
+
+#### ddwaf_object_get_unsigned
+
+```c
+uint64_t ddwaf_object_get_unsigned(const ddwaf_object * object)
+```
+
+Returns the uint64 contained within the object.
+
+**Parameters:**
+
+- `object`: The object from which to get the integer.
+
+**Returns:** The integer or 0 if the object is not an unsigned.
+
+#### ddwaf_object_get_signed
+
+```c
+int64_t ddwaf_object_get_signed(const ddwaf_object * object)
+```
+
+Returns the int64 contained within the object.
+
+**Parameters:**
+
+- `object`: The object from which to get the integer.
+
+**Returns:** The integer or 0 if the object is not a signed.
+
+#### ddwaf_object_get_float
+
+```c
+double ddwaf_object_get_float(const ddwaf_object * object)
+```
+
+Returns the float64 (double) contained within the object.
+
+**Parameters:**
+
+- `object`: The object from which to get the float.
+
+**Returns:** The float or 0.0 if the object is not a float.
+
+#### ddwaf_object_get_bool
+
+```c
+bool ddwaf_object_get_bool(const ddwaf_object * object)
+```
+
+Returns the boolean contained within the object.
+
+**Parameters:**
+
+- `object`: The object from which to get the boolean.
+
+**Returns:** The boolean or false if the object is not a boolean.
+
+### Object Container Operations
+
+#### ddwaf_object_insert
+
+```c
+ddwaf_object * ddwaf_object_insert(ddwaf_object * array, ddwaf_allocator alloc)
+```
+
+Inserts a new object into an array object.
+
+**Parameters:**
+
+- `array`: Array in which to insert the object. (nonnull)
+- `alloc`: Allocator to use for memory allocation. (nonnull)
+
+**Returns:** A pointer to the newly inserted object or NULL if the operation failed.
+
+#### ddwaf_object_insert_key
+
+```c
+ddwaf_object * ddwaf_object_insert_key(ddwaf_object * map, const char * key, uint32_t length, ddwaf_allocator alloc)
+```
+
+Inserts a new object into a map object, using a key.
+
+**Parameters:**
+
+- `map`: Map in which to insert the object. (nonnull)
+- `key`: The key for indexing purposes, this string will be copied. (nonnull)
+- `length`: Length of the key.
+- `alloc`: Allocator to use for memory allocation. (nonnull)
+
+**Returns:** A pointer to the newly inserted object or NULL if the operation failed.
+
+#### ddwaf_object_insert_literal_key
+
+```c
+ddwaf_object * ddwaf_object_insert_literal_key(ddwaf_object * map, const char * key, uint32_t length, ddwaf_allocator alloc)
+```
+
+Inserts a new object into a map object, using a literal key.
+
+**Parameters:**
+
+- `map`: Map in which to insert the object. (nonnull)
+- `key`: The key for indexing purposes, this string will not be copied. (nonnull)
+- `length`: Length of the key.
+- `alloc`: Allocator to use for memory allocation. (nonnull)
+
+**Returns:** A pointer to the newly inserted object or NULL if the operation failed.
+
+#### ddwaf_object_insert_key_nocopy
+
+```c
+ddwaf_object * ddwaf_object_insert_key_nocopy(ddwaf_object * map, const char * key, uint32_t length, ddwaf_allocator alloc)
+```
+
+Inserts a new object into a map object, using a key and its length, but without creating a copy of the key.
+
+**Parameters:**
+
+- `map`: Map in which to insert the object. (nonnull)
+- `key`: The key for indexing purposes, this string will not be copied. (nonnull)
+- `length`: Length of the key.
+- `alloc`: Allocator to use for memory allocation. (nonnull)
+
+**Returns:** A pointer to the newly inserted object or NULL if the operation failed.
+
+> **Note:** The provided string must have been allocated with the same allocator used with ddwaf_object_destroy.
+
+#### ddwaf_object_at_key
+
+```c
+const ddwaf_object * ddwaf_object_at_key(const ddwaf_object * object, size_t index)
+```
+
+Returns the key contained in the container at the given index.
+
+**Parameters:**
+
+- `object`: The container from which to extract the object.
+- `index`: The position of the required object within the container.
+
+**Returns:** The requested object or NULL if the index is out of bounds or the object is not a container.
+
+#### ddwaf_object_at_value
+
+```c
+const ddwaf_object * ddwaf_object_at_value(const ddwaf_object * object, size_t index)
+```
+
+Returns the object contained in the container at the given index.
+
+**Parameters:**
+
+- `object`: The container from which to extract the object.
+- `index`: The position of the required object within the container.
+
+**Returns:** The requested object or NULL if the index is out of bounds or the object is not a container.
+
+#### ddwaf_object_find
+
+```c
+const ddwaf_object * ddwaf_object_find(const ddwaf_object * object, const char * key, size_t length)
+```
+
+Returns the object within the given map with a key matching the provided one.
+
+**Parameters:**
+
+- `object`: The container from which to extract the object.
+- `key`: A string representing the key to find.
+- `length`: Length of the key.
+
+**Returns:** The requested object or NULL if the key was not found or the object is not a container.
+
+#### ddwaf_object_clone
+
+```c
+ddwaf_object * ddwaf_object_clone(const ddwaf_object * source, ddwaf_object * destination, ddwaf_allocator alloc)
+```
+
+Creates a deep copy of the source object into the destination object.
+
+**Parameters:**
+
+- `source`: The source object to clone from. (nonnull)
+- `destination`: The destination object to clone into. (nonnull)
+- `alloc`: Allocator to use for memory allocation. (nonnull)
+
+**Returns:** A pointer to the destination object or NULL if the operation failed.
+
+#### ddwaf_object_destroy
+
+```c
+void ddwaf_object_destroy(ddwaf_object * object, ddwaf_allocator alloc)
+```
+
+Frees the memory contained within the object.
+
+**Parameters:**
+
+- `object`: Object to destroy. (nonnull)
+- `alloc`: Allocator to use for memory reclamation. (nonnull)
+
+### Object Type Checking
+
+#### ddwaf_object_is_invalid
+
+```c
+bool ddwaf_object_is_invalid(const ddwaf_object * object)
+```
+
+Returns true if the object is invalid.
+
+**Parameters:**
+
+- `object`: The object from which to get the type.
+
+**Returns:** True if the object is invalid, false otherwise.
+
+#### ddwaf_object_is_null
+
+```c
+bool ddwaf_object_is_null(const ddwaf_object * object)
+```
+
+Returns true if the object is null.
+
+**Parameters:**
+
+- `object`: The object from which to get the type.
+
+**Returns:** True if the object is null, false otherwise.
+
+#### ddwaf_object_is_bool
+
+```c
+bool ddwaf_object_is_bool(const ddwaf_object * object)
+```
+
+Returns true if the object is a boolean.
+
+**Parameters:**
+
+- `object`: The object from which to get the type.
+
+**Returns:** True if the object is a boolean, false otherwise.
+
+#### ddwaf_object_is_signed
+
+```c
+bool ddwaf_object_is_signed(const ddwaf_object * object)
+```
+
+Returns true if the object is a signed integer.
+
+**Parameters:**
+
+- `object`: The object from which to get the type.
+
+**Returns:** True if the object is a signed integer, false otherwise.
+
+#### ddwaf_object_is_unsigned
+
+```c
+bool ddwaf_object_is_unsigned(const ddwaf_object * object)
+```
+
+Returns true if the object is an unsigned integer.
+
+**Parameters:**
+
+- `object`: The object from which to get the type.
+
+**Returns:** True if the object is an unsigned integer, false otherwise.
+
+#### ddwaf_object_is_float
+
+```c
+bool ddwaf_object_is_float(const ddwaf_object * object)
+```
+
+Returns true if the object is a float.
+
+**Parameters:**
+
+- `object`: The object from which to get the type.
+
+**Returns:** True if the object is a float, false otherwise.
+
+#### ddwaf_object_is_string
+
+```c
+bool ddwaf_object_is_string(const ddwaf_object * object)
+```
+
+Returns true if the object is a string.
+
+**Parameters:**
+
+- `object`: The object from which to get the type.
+
+**Returns:** True if the object is a string, false otherwise.
+
+#### ddwaf_object_is_array
+
+```c
+bool ddwaf_object_is_array(const ddwaf_object * object)
+```
+
+Returns true if the object is an array.
+
+**Parameters:**
+
+- `object`: The object from which to get the type.
+
+**Returns:** True if the object is an array, false otherwise.
+
+#### ddwaf_object_is_map
+
+```c
+bool ddwaf_object_is_map(const ddwaf_object * object)
+```
+
+Returns true if the object is a map.
+
+**Parameters:**
+
+- `object`: The object from which to get the type.
+
+**Returns:** True if the object is a map, false otherwise.
+
+### Utility
+
+#### ddwaf_get_version
+
+```c
+const char * ddwaf_get_version()
+```
+
+Return the version of the library
+
+**Returns:** version Version string, note that this should not be freed
+
+#### ddwaf_set_log_cb
+
+```c
+bool ddwaf_set_log_cb(ddwaf_log_cb cb, DDWAF_LOG_LEVEL min_level)
+```
+
+Sets the callback to relay logging messages to the binding
+
+**Parameters:**
 
-## Thread Safety and Lifetime Notes
+- `cb`: The callback to call, or NULL to stop relaying messages
+- `min_level`: The minimum logging level for which to relay messages
 
-- WAF handles are thread-safe for read operations (`ddwaf_context_init`, `ddwaf_known_addresses`, `ddwaf_known_actions`). Builder operations and handle destruction are not thread-safe with respect to these read operations.
-- Allocation routines inherit the thread-safety guarantees of the allocator instance returned by the corresponding factory.
-- Objects created with `_string_literal` or `_insert_literal_key` expect the referenced buffers to outlive the object or to remain immutable.
-- Result objects returned by evaluation functions remain valid until destroyed. Never reuse them across calls without destroying or reinitialising them first.
+**Returns:** whether the operation succeeded or not
 
-This reference mirrors the API shipped in `include/ddwaf.h` and should be kept in sync whenever the header changes.
+> **Note:** This function is not thread-safe
diff --git a/include/ddwaf.h b/include/ddwaf.h
index aaa7cf3a2..f2a4ac011 100644
--- a/include/ddwaf.h
+++ b/include/ddwaf.h
@@ -306,9 +306,11 @@ ddwaf_context ddwaf_context_init(const ddwaf_handle handle, ddwaf_allocator outp
  *                             format: {tag, value}
  *               - keep: whether the data contained herein must override any
  *                       transport sampling through the relevant mechanism.
- *               This structure must be freed by the caller and will contain all
- *               specified keys when the value returned by ddwaf_context_eval is either
- *               DDWAF_OK or DDWAF_MATCH and will be empty otherwise.
+ *               This structure must be freed by the caller using the output
+ *               allocator provided through ddwaf_context_init. The object will
+ *               contain all specified keys when the value returned by
+ *               ddwaf_context_eval is either DDWAF_OK or DDWAF_MATCH and will
+ *               be empty otherwise.
  *               IMPORTANT: This object is not allocated with the allocator
  *               passed in this call. It uses the allocator given to
  *               ddwaf_context_init instead.
@@ -338,7 +340,7 @@ DDWAF_RET_CODE ddwaf_context_eval(ddwaf_context context, ddwaf_object *data,
 
 /**
  * Performs the destruction of the context, freeing the data passed to it through
- * ddwaf_context_eval using the used-defined free function.
+ * ddwaf_context_eval using the provided allocator during evaluation.
  *
  * @param context Context to destroy. (nonnull)
  **/
@@ -444,6 +446,7 @@ ddwaf_builder ddwaf_builder_init();
  *
  * @note if any of the arguments are NULL, the diagnostics object will not be initialised.
  * @note The memory associated with the path, config and diagnostics must be freed by the caller.
+ * @note The deallocation of the diagnostics must be made with default allocator.
  * @note This function is not thread-safe.
  **/
 bool ddwaf_builder_add_or_update_config(ddwaf_builder builder, const char *path, uint32_t path_len, const ddwaf_object *config, ddwaf_object *diagnostics);
diff --git a/tools/generate_documentation.py b/tools/generate_documentation.py
new file mode 100755
index 000000000..6903d352b
--- /dev/null
+++ b/tools/generate_documentation.py
@@ -0,0 +1,547 @@
+#!/usr/bin/env python3
+"""
+Generate C API documentation for libddwaf.
+
+This script:
+1. Runs Doxygen to generate XML from include/ddwaf.h
+2. Converts the XML to a single Markdown file
+3. Cleans up the intermediate Doxygen files
+
+Usage:
+    ./tools/generate_documentation.py [--keep-xml]
+
+Options:
+    --keep-xml    Keep the intermediate Doxygen XML files
+"""
+
+import xml.etree.ElementTree as ET
+import subprocess
+import shutil
+import sys
+import re
+import tempfile
+from pathlib import Path
+
+
+def get_text(element):
+    """Extract all text content from an element, handling nested elements."""
+    if element is None:
+        return ""
+
+    result = []
+    if element.text:
+        result.append(element.text)
+
+    for child in element:
+        if child.tag == "para":
+            result.append(get_text(child))
+            result.append("\n\n")
+        elif child.tag == "parameterlist":
+            pass  # Handle separately
+        elif child.tag == "simplesect":
+            pass  # Handle separately
+        elif child.tag == "ref":
+            result.append(child.text or "")
+        elif child.tag == "computeroutput":
+            result.append(f"`{child.text or ''}`")
+        elif child.tag == "emphasis":
+            result.append(f"*{child.text or ''}*")
+        elif child.tag == "bold":
+            result.append(f"**{child.text or ''}**")
+        elif child.tag == "itemizedlist":
+            for item in child.findall("listitem"):
+                result.append(f"\n- {get_text(item).strip()}")
+            result.append("\n")
+        elif child.tag == "orderedlist":
+            for i, item in enumerate(child.findall("listitem"), 1):
+                result.append(f"\n{i}. {get_text(item).strip()}")
+            result.append("\n")
+        else:
+            result.append(get_text(child))
+
+        if child.tail:
+            result.append(child.tail)
+
+    return "".join(result).strip()
+
+
+def extract_description(memberdef):
+    """Extract brief and detailed description from a memberdef."""
+    brief = memberdef.find("briefdescription")
+    detailed = memberdef.find("detaileddescription")
+
+    brief_text = get_text(brief) if brief is not None else ""
+    detailed_text = get_text(detailed) if detailed is not None else ""
+
+    if detailed_text:
+        return detailed_text
+    return brief_text
+
+
+def extract_params(memberdef):
+    """Extract parameter documentation from a memberdef."""
+    params = []
+    detailed = memberdef.find("detaileddescription")
+    if detailed is None:
+        return params
+
+    for paramlist in detailed.iter("parameterlist"):
+        if paramlist.get("kind") == "param":
+            for item in paramlist.findall("parameteritem"):
+                name_elem = item.find(".//parametername")
+                desc_elem = item.find("parameterdescription")
+                if name_elem is not None:
+                    name = name_elem.text or ""
+                    desc = get_text(desc_elem) if desc_elem is not None else ""
+                    params.append((name, desc))
+
+    return params
+
+
+def extract_return(memberdef):
+    """Extract return value documentation."""
+    detailed = memberdef.find("detaileddescription")
+    if detailed is None:
+        return ""
+
+    for simplesect in detailed.iter("simplesect"):
+        if simplesect.get("kind") == "return":
+            return get_text(simplesect)
+
+    return ""
+
+
+def extract_retvals(memberdef):
+    """Extract return value codes documentation."""
+    retvals = []
+    detailed = memberdef.find("detaileddescription")
+    if detailed is None:
+        return retvals
+
+    for paramlist in detailed.iter("parameterlist"):
+        if paramlist.get("kind") == "retval":
+            for item in paramlist.findall("parameteritem"):
+                name_elem = item.find(".//parametername")
+                desc_elem = item.find("parameterdescription")
+                if name_elem is not None:
+                    name = name_elem.text or ""
+                    desc = get_text(desc_elem) if desc_elem is not None else ""
+                    retvals.append((name, desc))
+
+    return retvals
+
+
+def extract_notes(memberdef):
+    """Extract notes from documentation."""
+    notes = []
+    detailed = memberdef.find("detaileddescription")
+    if detailed is None:
+        return notes
+
+    for simplesect in detailed.iter("simplesect"):
+        if simplesect.get("kind") == "note":
+            notes.append(get_text(simplesect))
+
+    return notes
+
+
+def format_function_signature(memberdef):
+    """Format a function signature."""
+    return_type = memberdef.find("type")
+    name = memberdef.find("name")
+
+    ret_text = ""
+    if return_type is not None:
+        ret_text = get_text(return_type)
+        for ref in return_type.findall(".//ref"):
+            if ref.text:
+                ret_text = ret_text.replace(ref.text, ref.text)
+
+    func_name = name.text if name is not None else ""
+
+    params = []
+    for param in memberdef.findall("param"):
+        param_type = param.find("type")
+        param_name = param.find("declname")
+
+        type_text = get_text(param_type) if param_type is not None else ""
+        name_text = param_name.text if param_name is not None else ""
+
+        if type_text or name_text:
+            params.append(f"{type_text} {name_text}".strip())
+
+    return f"{ret_text} {func_name}({', '.join(params)})"
+
+
+def format_typedef_signature(memberdef):
+    """Format a typedef signature."""
+    definition = memberdef.find("definition")
+    argsstring = memberdef.find("argsstring")
+
+    def_text = definition.text if definition is not None else ""
+    args_text = argsstring.text if argsstring is not None and argsstring.text else ""
+
+    if args_text and args_text in def_text:
+        return def_text
+
+    return f"{def_text}{args_text}"
+
+
+def parse_header_xml(xml_path):
+    """Parse the main header XML file."""
+    tree = ET.parse(xml_path)
+    root = tree.getroot()
+
+    data = {
+        "enums": [],
+        "typedefs": [],
+        "functions": [],
+    }
+
+    compounddef = root.find("compounddef")
+    if compounddef is None:
+        return data
+
+    for sectiondef in compounddef.findall("sectiondef"):
+        for memberdef in sectiondef.findall("memberdef"):
+            member_kind = memberdef.get("kind")
+            name_elem = memberdef.find("name")
+            name = name_elem.text if name_elem is not None else ""
+
+            # Skip internal/compiler-specific stuff
+            if name.startswith("__") or name.startswith("_ddwaf_object_"):
+                continue
+
+            if member_kind == "enum":
+                enum_data = {
+                    "name": name,
+                    "description": extract_description(memberdef),
+                    "values": []
+                }
+
+                for enumvalue in memberdef.findall("enumvalue"):
+                    val_name = enumvalue.find("name")
+                    val_init = enumvalue.find("initializer")
+                    val_desc = enumvalue.find("detaileddescription")
+
+                    enum_data["values"].append({
+                        "name": val_name.text if val_name is not None else "",
+                        "value": val_init.text if val_init is not None else "",
+                        "description": get_text(val_desc) if val_desc is not None else ""
+                    })
+
+                data["enums"].append(enum_data)
+
+            elif member_kind == "typedef":
+                typedef_data = {
+                    "name": name,
+                    "signature": format_typedef_signature(memberdef),
+                    "description": extract_description(memberdef),
+                    "params": extract_params(memberdef),
+                }
+                data["typedefs"].append(typedef_data)
+
+            elif member_kind == "function":
+                func_data = {
+                    "name": name,
+                    "signature": format_function_signature(memberdef),
+                    "description": extract_description(memberdef),
+                    "params": extract_params(memberdef),
+                    "return": extract_return(memberdef),
+                    "retvals": extract_retvals(memberdef),
+                    "notes": extract_notes(memberdef),
+                }
+                data["functions"].append(func_data)
+
+    return data
+
+
+def categorize_functions(functions):
+    """Categorize functions by their purpose."""
+    categories = {
+        "Initialization/Destruction": [],
+        "Builder": [],
+        "Context": [],
+        "Subcontext": [],
+        "Allocator": [],
+        "Object Creation": [],
+        "Object Inspection": [],
+        "Object Container Operations": [],
+        "Object Type Checking": [],
+        "Utility": [],
+    }
+
+    for func in functions:
+        name = func["name"]
+
+        if name in ("ddwaf_init", "ddwaf_destroy"):
+            categories["Initialization/Destruction"].append(func)
+        elif "builder" in name:
+            categories["Builder"].append(func)
+        elif "subcontext" in name:
+            categories["Subcontext"].append(func)
+        elif "context" in name:
+            categories["Context"].append(func)
+        elif "allocator" in name or name.endswith("_allocator_init"):
+            categories["Allocator"].append(func)
+        elif name.startswith("ddwaf_object_set_") or name == "ddwaf_object_from_json":
+            categories["Object Creation"].append(func)
+        elif name.startswith("ddwaf_object_get_"):
+            categories["Object Inspection"].append(func)
+        elif name.startswith("ddwaf_object_is_"):
+            categories["Object Type Checking"].append(func)
+        elif name.startswith("ddwaf_object_"):
+            categories["Object Container Operations"].append(func)
+        elif name.startswith("ddwaf_known_"):
+            categories["Initialization/Destruction"].append(func)
+        else:
+            categories["Utility"].append(func)
+
+    order = [
+        "Initialization/Destruction",
+        "Builder",
+        "Context",
+        "Subcontext",
+        "Allocator",
+        "Object Creation",
+        "Object Inspection",
+        "Object Container Operations",
+        "Object Type Checking",
+        "Utility",
+    ]
+
+    return [(cat, categories[cat]) for cat in order if categories[cat]]
+
+
+def generate_markdown(data):
+    """Generate markdown from parsed data."""
+    lines = []
+
+    # Header
+    lines.append("# libddwaf C API Reference")
+    lines.append("")
+    lines.append("This document describes the public C API of libddwaf.")
+    lines.append("")
+
+    # Table of Contents
+    lines.append("## Table of Contents")
+    lines.append("")
+    lines.append("- [Enumerations](#enumerations)")
+    for enum in data["enums"]:
+        lines.append(f"  - [{enum['name']}](#{enum['name'].lower().replace('_', '-')})")
+    lines.append("- [Type Definitions](#type-definitions)")
+    lines.append("- [Functions](#functions)")
+
+    func_categories = categorize_functions(data["functions"])
+    for category, _ in func_categories:
+        anchor = category.lower().replace(" ", "-").replace("/", "")
+        lines.append(f"  - [{category}](#{anchor})")
+
+    lines.append("")
+
+    # Enumerations
+    lines.append("---")
+    lines.append("")
+    lines.append("## Enumerations")
+    lines.append("")
+
+    for enum in data["enums"]:
+        lines.append(f"### {enum['name']}")
+        lines.append("")
+        if enum["description"]:
+            lines.append(enum["description"])
+            lines.append("")
+
+        lines.append("| Value | Code | Description |")
+        lines.append("|-------|------|-------------|")
+        for val in enum["values"]:
+            desc = val["description"].replace("\n", " ").strip()
+            lines.append(f"| `{val['name']}` | `{val['value']}` | {desc} |")
+        lines.append("")
+
+    # Type Definitions
+    lines.append("---")
+    lines.append("")
+    lines.append("## Type Definitions")
+    lines.append("")
+
+    notable_typedefs = [t for t in data["typedefs"] if t["description"] or t["params"]]
+    simple_typedefs = [t for t in data["typedefs"] if not t["description"] and not t["params"]]
+
+    if simple_typedefs:
+        lines.append("### Handle Types")
+        lines.append("")
+        lines.append("| Type | Definition |")
+        lines.append("|------|------------|")
+        for typedef in simple_typedefs:
+            sig = typedef["signature"].replace("|", "\\|")
+            lines.append(f"| `{typedef['name']}` | `{sig}` |")
+        lines.append("")
+
+    for typedef in notable_typedefs:
+        lines.append(f"### {typedef['name']}")
+        lines.append("")
+        lines.append("```c")
+        lines.append(typedef["signature"])
+        lines.append("```")
+        lines.append("")
+
+        if typedef["description"]:
+            lines.append(typedef["description"])
+            lines.append("")
+
+        if typedef["params"]:
+            lines.append("**Parameters:**")
+            lines.append("")
+            for pname, pdesc in typedef["params"]:
+                lines.append(f"- `{pname}`: {pdesc}")
+            lines.append("")
+
+    # Functions
+    lines.append("---")
+    lines.append("")
+    lines.append("## Functions")
+    lines.append("")
+
+    for category, funcs in func_categories:
+        lines.append(f"### {category}")
+        lines.append("")
+
+        for func in funcs:
+            lines.append(f"#### {func['name']}")
+            lines.append("")
+            lines.append("```c")
+            lines.append(func["signature"])
+            lines.append("```")
+            lines.append("")
+
+            desc = func["description"]
+            desc_clean = re.split(r'\n\n', desc)[0] if desc else ""
+            if desc_clean:
+                lines.append(desc_clean)
+                lines.append("")
+
+            if func["params"]:
+                lines.append("**Parameters:**")
+                lines.append("")
+                for pname, pdesc in func["params"]:
+                    lines.append(f"- `{pname}`: {pdesc}")
+                lines.append("")
+
+            if func["return"]:
+                lines.append(f"**Returns:** {func['return']}")
+                lines.append("")
+
+            if func["retvals"]:
+                lines.append("**Return Values:**")
+                lines.append("")
+                for rname, rdesc in func["retvals"]:
+                    lines.append(f"- `{rname}`: {rdesc}")
+                lines.append("")
+
+            if func["notes"]:
+                for note in func["notes"]:
+                    lines.append(f"> **Note:** {note}")
+                    lines.append("")
+
+    return "\n".join(lines)
+
+
+def run_doxygen(root_dir, output_dir):
+    """Run Doxygen to generate XML output."""
+    # Create a temporary Doxyfile
+    doxyfile_content = f"""
+PROJECT_NAME = libddwaf
+OUTPUT_DIRECTORY = {output_dir}
+INPUT = {root_dir / 'include' / 'ddwaf.h'}
+FILE_PATTERNS = *.h
+RECURSIVE = NO
+EXTRACT_ALL = YES
+EXTRACT_STATIC = YES
+EXTRACT_PRIVATE = NO
+GENERATE_HTML = NO
+GENERATE_LATEX = NO
+GENERATE_MAN = NO
+GENERATE_RTF = NO
+GENERATE_DOCBOOK = NO
+GENERATE_XML = YES
+XML_OUTPUT = xml
+QUIET = YES
+WARNINGS = NO
+"""
+
+    doxyfile_path = output_dir / "Doxyfile"
+    doxyfile_path.write_text(doxyfile_content)
+
+    # Run doxygen
+    result = subprocess.run(
+        ["doxygen", str(doxyfile_path)],
+        cwd=root_dir,
+        capture_output=True,
+        text=True
+    )
+
+    if result.returncode != 0:
+        print(f"Doxygen error: {result.stderr}")
+        return False
+
+    return True
+
+
+def main():
+    # Parse arguments
+    keep_xml = "--keep-xml" in sys.argv
+
+    # Determine paths
+    script_path = Path(__file__).resolve()
+    root_dir = script_path.parent.parent
+    output_file = root_dir / "docs" / "c-api" / "api.md"
+
+    # Check for doxygen
+    if shutil.which("doxygen") is None:
+        print("Error: doxygen not found in PATH")
+        print("Please install doxygen: apt install doxygen / brew install doxygen")
+        sys.exit(1)
+
+    # Create temporary directory for doxygen output
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_path = Path(temp_dir)
+
+        print("Running Doxygen...")
+        if not run_doxygen(root_dir, temp_path):
+            print("Error: Doxygen failed")
+            sys.exit(1)
+
+        # Find the XML file
+        xml_file = temp_path / "xml" / "ddwaf_8h.xml"
+        if not xml_file.exists():
+            print(f"Error: Expected XML file not found: {xml_file}")
+            sys.exit(1)
+
+        print("Parsing XML...")
+        data = parse_header_xml(xml_file)
+
+        print(f"Found {len(data['enums'])} enums, {len(data['typedefs'])} typedefs, {len(data['functions'])} functions")
+
+        print("Generating Markdown...")
+        markdown = generate_markdown(data)
+
+        # Ensure output directory exists
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+
+        print(f"Writing {output_file}...")
+        output_file.write_text(markdown)
+
+        # Optionally keep XML files
+        if keep_xml:
+            xml_dest = root_dir / "docs" / "c-api" / "doxygen"
+            if xml_dest.exists():
+                shutil.rmtree(xml_dest)
+            shutil.copytree(temp_path, xml_dest)
+            print(f"XML files saved to {xml_dest}")
+
+    print("Done!")
+
+
+if __name__ == "__main__":
+    main()

From 7743a2e06752a7a88b447a8cdfd71a251a393d51 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 14:10:48 +0000
Subject: [PATCH 26/32] Small fix

---
 tools/infer_schema.cpp | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/tools/infer_schema.cpp b/tools/infer_schema.cpp
index 53e101bb5..b37a8d721 100644
--- a/tools/infer_schema.cpp
+++ b/tools/infer_schema.cpp
@@ -57,11 +57,10 @@ int main(int argc, char *argv[])
     ddwaf_object result;
     auto code = ddwaf_context_eval(context, &input, alloc, &result, std::numeric_limits<uint64_t>::max());
     if (code == DDWAF_MATCH) {
-        std::cout << object_to_json(result) << '\n';
-/*        const ddwaf_object *attributes = ddwaf_object_find(&result, STRL("attributes"));*/
-        /*if (attributes != nullptr && ddwaf_object_get_size(attributes) > 0) {*/
-            /*std::cout << object_to_json(*attributes) << '\n';*/
-        /*}*/
+        const ddwaf_object *attributes = ddwaf_object_find(&result, STRL("attributes"));
+        if (attributes != nullptr && ddwaf_object_get_size(attributes) > 0) {
+            std::cout << object_to_json(*attributes) << '\n';
+        }
     }
 
     ddwaf_object_destroy(&result, alloc);

From 87a264e02cb299a99d4ce6698c0c88f704b503a9 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 14:30:52 +0000
Subject: [PATCH 27/32] Update CHANGELOG-v2.0.0.md

---
 docs/changelog/CHANGELOG-v2.0.0.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/changelog/CHANGELOG-v2.0.0.md b/docs/changelog/CHANGELOG-v2.0.0.md
index 4a321b2f5..8a9cbfbf9 100644
--- a/docs/changelog/CHANGELOG-v2.0.0.md
+++ b/docs/changelog/CHANGELOG-v2.0.0.md
@@ -8,17 +8,17 @@ The most fundamental change in v2 is the introduction of allocators throughout t
 
 ### Object Model and Creation API
 
-The `ddwaf_object` structure has been completely redesigned to reduce memory overhead. A single object now requires only 16 bytes, down from a considerably larger footprint in v1. This was achieved through the introduction of small strings, where strings of 14 bytes or fewer are stored directly within the object without additional heap allocation, and literal strings, which reference read-only memory that is never freed by the library.
+The `ddwaf_object` structure has been completely redesigned to reduce memory overhead. A single object now requires only 16 bytes, down from a considerably larger footprint in v1. This was achieved through carefully redesigning each of the possible type variants and, more specifically, through the removal of map keys from the main `ddwaf_object` in favour of representing maps through a separate `ddwaf_object_kv` structure. Indirectly, this new version enables further reduction in the memory and allocations through the introduction of small strings, where strings of 14 bytes or fewer are stored directly within the object without additional heap allocation, and literal strings, which reference read-only memory that is never freed by the library.
 
 Object creation functions have been renamed to follow a consistent `ddwaf_object_set_*` pattern and now require an allocator parameter where allocation may occur. Container insertion returns a pointer to the newly inserted element, eliminating the need for intermediate objects. For example, where v1 required creating a value object separately and then adding it to a map, v2 allows direct initialisation: `ddwaf_object_set_string(ddwaf_object_insert_key(&map, "key", 3, alloc), "value", 5, alloc)`. This pattern reduces boilerplate and makes the ownership model clearer.
 
 ### Context and Subcontext Lifecycle
 
-The function `ddwaf_run` has been renamed to `ddwaf_context_eval` for consistency with the rest of the API. More significantly, ephemeral data semantics have been replaced with a new subcontext mechanism. In v1, ephemeral data was passed as a separate parameter to each run call and was not retained. In v2, a subcontext is explicitly created from a parent context via `ddwaf_subcontext_init`, evaluated with `ddwaf_subcontext_eval`, and destroyed with `ddwaf_subcontext_destroy`. Subcontexts inherit all persistent data from their parent context but maintain their own isolated evaluation state. Multiple concurrent subcontexts can be created from the same parent context, each defining its own data scope and lifetime.
+The function `ddwaf_run` has been renamed to `ddwaf_context_eval` for consistency with the rest of the API. More significantly, ephemeral data semantics have been replaced with a new subcontext mechanism. In v1, ephemeral data was passed as a separate parameter to each `ddwaf_run` call and was not retained. In v2, a subcontext is explicitly created from a parent context via `ddwaf_subcontext_init`, evaluated with `ddwaf_subcontext_eval`, and destroyed with `ddwaf_subcontext_destroy`. Subcontexts inherit all data from their parent context but maintain their own isolated evaluation state. Multiple concurrent subcontexts can be created from the same parent context, each defining its own data scope and lifetime.
 
 ### Breaking Changes Summary
 
-Binding library maintainers should note that this release is not backwards compatible. Key migration points include: all object creation and destruction requires allocators, `ddwaf_run` is now `ddwaf_context_eval`, ephemeral data is handled through subcontexts rather than a parameter, `ddwaf_config` is removed, and `ddwaf_result_free` is replaced by `ddwaf_object_destroy` with the appropriate allocator. The upgrading guide at `docs/upgrading/UPGRADING-v2.0.md` provides detailed migration examples for each of these changes.
+As expected, this release is not backwards compatible; the upgrading guide at `docs/upgrading/UPGRADING-v2.0.md` provides detailed migration examples for each of the breaking changes.
 
 ## Release Changelog
 ### Changes

From 015e20643e8a8afbd9e2b2cdcce84fe72f0646d8 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 14:31:39 +0000
Subject: [PATCH 28/32] Update CHANGELOG-v2.0.0.md

---
 docs/changelog/CHANGELOG-v2.0.0.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/changelog/CHANGELOG-v2.0.0.md b/docs/changelog/CHANGELOG-v2.0.0.md
index 8a9cbfbf9..5b0a43433 100644
--- a/docs/changelog/CHANGELOG-v2.0.0.md
+++ b/docs/changelog/CHANGELOG-v2.0.0.md
@@ -2,6 +2,8 @@
 
 libddwaf v2.0.0 represents a significant redesign of the C API, focusing on explicit memory ownership, reduced memory footprint, and a more consistent interface. Beyond the public API, the internals have also been refactored to use safer and more C++-native abstractions. This is an alpha release intended for early adopters and binding library maintainers to begin integration work.
 
+As expected, this release is not backwards compatible; the upgrading guide at `docs/upgrading/UPGRADING-v2.0.md` provides detailed migration examples for each of the breaking changes.
+
 ### Memory Ownership and Allocators
 
 The most fundamental change in v2 is the introduction of allocators throughout the API. In v1, memory ownership across the API boundary was often ambiguous, leading to potential issues in complex integration scenarios. The new allocator system makes memory ownership explicit: callers provide an allocator when creating objects and use the same allocator when destroying them. A default allocator is available via `ddwaf_get_default_allocator()` for simple use cases, while custom allocators enable advanced memory management strategies.
@@ -16,10 +18,6 @@ Object creation functions have been renamed to follow a consistent `ddwaf_object
 
 The function `ddwaf_run` has been renamed to `ddwaf_context_eval` for consistency with the rest of the API. More significantly, ephemeral data semantics have been replaced with a new subcontext mechanism. In v1, ephemeral data was passed as a separate parameter to each `ddwaf_run` call and was not retained. In v2, a subcontext is explicitly created from a parent context via `ddwaf_subcontext_init`, evaluated with `ddwaf_subcontext_eval`, and destroyed with `ddwaf_subcontext_destroy`. Subcontexts inherit all data from their parent context but maintain their own isolated evaluation state. Multiple concurrent subcontexts can be created from the same parent context, each defining its own data scope and lifetime.
 
-### Breaking Changes Summary
-
-As expected, this release is not backwards compatible; the upgrading guide at `docs/upgrading/UPGRADING-v2.0.md` provides detailed migration examples for each of the breaking changes.
-
 ## Release Changelog
 ### Changes
 

From 1602fee81cac081ec40790d76460fbdbdfc0312e Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 14:37:03 +0000
Subject: [PATCH 29/32] Remove doxyfile

---
 Doxyfile | 15 ---------------
 1 file changed, 15 deletions(-)
 delete mode 100644 Doxyfile

diff --git a/Doxyfile b/Doxyfile
deleted file mode 100644
index 4adb698e1..000000000
--- a/Doxyfile
+++ /dev/null
@@ -1,15 +0,0 @@
-PROJECT_NAME = libddwaf
-OUTPUT_DIRECTORY = docs/c-api/doxygen
-INPUT = include/ddwaf.h
-FILE_PATTERNS = *.h
-RECURSIVE = NO
-EXTRACT_ALL = YES
-EXTRACT_STATIC = YES
-EXTRACT_PRIVATE = NO
-GENERATE_HTML = NO
-GENERATE_LATEX = NO
-GENERATE_MAN = NO
-GENERATE_RTF = NO
-GENERATE_DOCBOOK = NO
-GENERATE_XML = YES
-XML_OUTPUT = xml

From eca4352edfe105c1ac7d811b5e04d64cde43e903 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 15:39:40 +0000
Subject: [PATCH 30/32] Update api.md

---
 docs/c-api/api.md | 103 +++++++++++++++++++---------------------------
 1 file changed, 42 insertions(+), 61 deletions(-)

diff --git a/docs/c-api/api.md b/docs/c-api/api.md
index 5ebf4c8ff..e3c451830 100644
--- a/docs/c-api/api.md
+++ b/docs/c-api/api.md
@@ -2,71 +2,50 @@
 
 This document describes the public C API of libddwaf.
 
-## Table of Contents
-
-- [Enumerations](#enumerations)
-  - [DDWAF_OBJ_TYPE](#ddwaf-obj-type)
-  - [DDWAF_RET_CODE](#ddwaf-ret-code)
-  - [DDWAF_LOG_LEVEL](#ddwaf-log-level)
-- [Type Definitions](#type-definitions)
-- [Functions](#functions)
-  - [Initialization/Destruction](#initializationdestruction)
-  - [Builder](#builder)
-  - [Context](#context)
-  - [Subcontext](#subcontext)
-  - [Allocator](#allocator)
-  - [Object Creation](#object-creation)
-  - [Object Inspection](#object-inspection)
-  - [Object Container Operations](#object-container-operations)
-  - [Object Type Checking](#object-type-checking)
-  - [Utility](#utility)
-
----
-
 ## Enumerations
 
 ### DDWAF_OBJ_TYPE
 
 Specifies the type of a ddwaf::object.
 
-| Value | Code | Description |
-|-------|------|-------------|
-| `DDWAF_OBJ_INVALID` | `= 0` |  |
-| `DDWAF_OBJ_NULL` | `= 0x01` |  |
-| `DDWAF_OBJ_BOOL` | `= 0x02` |  |
-| `DDWAF_OBJ_SIGNED` | `= 0x04` |  |
-| `DDWAF_OBJ_UNSIGNED` | `= 0x06` |  |
-| `DDWAF_OBJ_FLOAT` | `= 0x08` |  |
-| `DDWAF_OBJ_STRING` | `= 0x10` |  |
-| `DDWAF_OBJ_LITERAL_STRING` | `= 0x12` |  |
-| `DDWAF_OBJ_SMALL_STRING` | `= 0x14` |  |
-| `DDWAF_OBJ_ARRAY` | `= 0x20` |  |
-| `DDWAF_OBJ_MAP` | `= 0x40` |  |
+| Value | Code |
+|-------|------|
+| `DDWAF_OBJ_INVALID` | `= 0` |
+| `DDWAF_OBJ_NULL` | `= 0x01` |
+| `DDWAF_OBJ_BOOL` | `= 0x02` |
+| `DDWAF_OBJ_SIGNED` | `= 0x04` |
+| `DDWAF_OBJ_UNSIGNED` | `= 0x06` |
+| `DDWAF_OBJ_FLOAT` | `= 0x08` |
+| `DDWAF_OBJ_STRING` | `= 0x10` |
+| `DDWAF_OBJ_LITERAL_STRING` | `= 0x12` |
+| `DDWAF_OBJ_SMALL_STRING` | `= 0x14` |
+| `DDWAF_OBJ_ARRAY` | `= 0x20` |
+| `DDWAF_OBJ_MAP` | `= 0x40` |
 
 ### DDWAF_RET_CODE
 
 Codes returned by ddwaf_context_eval.
 
-| Value | Code | Description |
-|-------|------|-------------|
-| `DDWAF_ERR_INTERNAL` | `= -3` |  |
-| `DDWAF_ERR_INVALID_OBJECT` | `= -2` |  |
-| `DDWAF_ERR_INVALID_ARGUMENT` | `= -1` |  |
-| `DDWAF_OK` | `= 0` |  |
-| `DDWAF_MATCH` | `= 1` |  |
+| Value | Code |
+|-------|------|
+| `DDWAF_ERR_INTERNAL` | `= -3` |
+| `DDWAF_ERR_INVALID_OBJECT` | `= -2` |
+| `DDWAF_ERR_INVALID_ARGUMENT` | `= -1` |
+| `DDWAF_OK` | `= 0` |
+| `DDWAF_MATCH` | `= 1` |
 
 ### DDWAF_LOG_LEVEL
 
 Internal WAF log levels, to be used when setting the minimum log level and cb.
 
-| Value | Code | Description |
-|-------|------|-------------|
-| `DDWAF_LOG_TRACE` | `` |  |
-| `DDWAF_LOG_DEBUG` | `` |  |
-| `DDWAF_LOG_INFO` | `` |  |
-| `DDWAF_LOG_WARN` | `` |  |
-| `DDWAF_LOG_ERROR` | `` |  |
-| `DDWAF_LOG_OFF` | `` |  |
+| Value |
+|-------|
+| `DDWAF_LOG_TRACE` |
+| `DDWAF_LOG_DEBUG` |
+| `DDWAF_LOG_INFO` |
+| `DDWAF_LOG_WARN` |
+| `DDWAF_LOG_ERROR` |
+| `DDWAF_LOG_OFF` |
 
 ---
 
@@ -318,12 +297,13 @@ Perform a matching operation on the provided data
 - `data`: (nonnull) Data on which to perform the pattern matching. This data will be stored by the context and used across multiple calls to this function or ddwaf_subcontext_eval. Once the context is destroyed, the user defined allocator will be used to free the data provided. Note that the data passed must be valid until the destruction of the context. The object must be a map of {string,
 - `alloc`: (nullable) Allocator used to free the data provided. If NULL, the data will not be freed.
 - `result`: (nullable) Object map containing the following items:
-- events: an array of the generated events.
-- actions: a map of the generated actions in the format: "{action type: { <parameter map> }, ...}"
-- duration: an unsigned specifying the total runtime of the call in nanoseconds.
-- timeout: whether there has been a timeout during the call.
-- attributes: a map containing all derived objects in the format: {tag, value}
-- keep: whether the data contained herein must override any transport sampling through the relevant mechanism. This structure must be freed by the caller using the output allocator provided through ddwaf_context_init. The object will contain all specified keys when the value returned by ddwaf_context_eval is either DDWAF_OK or DDWAF_MATCH and will be empty otherwise. IMPORTANT: This object is not allocated with the allocator passed in this call. It uses the allocator given to ddwaf_context_init instead.
+  - `events`: an array of the generated events.
+  - `actions`: a map of the generated actions in the format: "{action type: { <parameter map> }, ...}"
+  - `duration`: an unsigned specifying the total runtime of the call in nanoseconds.
+  - `timeout`: whether there has been a timeout during the call.
+  - `attributes`: a map containing all derived objects in the format: {tag, value}
+  - `keep`: whether the data contained herein must override any transport sampling through the relevant mechanism. This structure must be freed by the caller using the output allocator provided through ddwaf_context_init. The object will contain all specified keys when the value returned by ddwaf_context_eval is either DDWAF_OK or DDWAF_MATCH and will be empty otherwise.
+  - **IMPORTANT**: This object is not allocated with the allocator passed in this call. It uses the allocator given to ddwaf_context_init instead.
 - `timeout`: Maximum time budget in microseconds.
 
 **Returns:** Return code of the operation.
@@ -376,12 +356,13 @@ Perform a matching operation on the provided data
 - `data`: (nonnull) Data on which to perform the pattern matching. This data will be stored by the subcontext and used across multiple calls to this function. Once the subcontext is destroyed, the user defined allocator will be used to free the data provided. Note that the data passed must be valid until the destruction of the subcontext. The object must be a map of {string,
 - `alloc`: (nullable) Allocator used to free the data provided. If NULL, the data will not be freed.
 - `result`: (nullable) Object map containing the following items:
-- events: an array of the generated events.
-- actions: a map of the generated actions in the format: "{action type: { <parameter map> }, ...}"
-- duration: an unsigned specifying the total runtime of the call in nanoseconds.
-- timeout: whether there has been a timeout during the call.
-- attributes: a map containing all derived objects in the format: {tag, value}
-- keep: whether the data contained herein must override any transport sampling through the relevant mechanism. This structure must be freed by the caller and will contain all specified keys when the value returned by ddwaf_subcontext_eval is either DDWAF_OK or DDWAF_MATCH and will be empty otherwise. IMPORTANT: This object is not allocated with the allocator passed in this call. It uses the allocator given to ddwaf_context_init instead.
+  - `events`: an array of the generated events.
+  - `actions`: a map of the generated actions in the format: "{action type: { <parameter map> }, ...}"
+  - `duration`: an unsigned specifying the total runtime of the call in nanoseconds.
+  - `timeout`: whether there has been a timeout during the call.
+  - `attributes`: a map containing all derived objects in the format: {tag, value}
+  - `keep`: whether the data contained herein must override any transport sampling through the relevant mechanism. This structure must be freed by the caller and will contain all specified keys when the value returned by ddwaf_subcontext_eval is either DDWAF_OK or DDWAF_MATCH and will be empty otherwise.
+  - **IMPORTANT**: This object is not allocated with the allocator passed in this call. It uses the allocator given to ddwaf_context_init instead.
 - `timeout`: Maximum time budget in microseconds.
 
 **Returns:** Return code of the operation.

From b2a95f1ff25757e7a088e77938f080c6170ca400 Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 16:23:18 +0000
Subject: [PATCH 31/32] Minor doc improvements

---
 docs/c-api/api.md | 106 ++++++++++++++++++++++++++++------------------
 include/ddwaf.h   |  51 +++++++++++++---------
 2 files changed, 95 insertions(+), 62 deletions(-)

diff --git a/docs/c-api/api.md b/docs/c-api/api.md
index e3c451830..b22d6f340 100644
--- a/docs/c-api/api.md
+++ b/docs/c-api/api.md
@@ -2,50 +2,71 @@
 
 This document describes the public C API of libddwaf.
 
+## Table of Contents
+
+- [Enumerations](#enumerations)
+  - [DDWAF_OBJ_TYPE](#ddwaf-obj-type)
+  - [DDWAF_RET_CODE](#ddwaf-ret-code)
+  - [DDWAF_LOG_LEVEL](#ddwaf-log-level)
+- [Type Definitions](#type-definitions)
+- [Functions](#functions)
+  - [Initialization/Destruction](#initializationdestruction)
+  - [Builder](#builder)
+  - [Context](#context)
+  - [Subcontext](#subcontext)
+  - [Allocator](#allocator)
+  - [Object Creation](#object-creation)
+  - [Object Inspection](#object-inspection)
+  - [Object Container Operations](#object-container-operations)
+  - [Object Type Checking](#object-type-checking)
+  - [Utility](#utility)
+
+---
+
 ## Enumerations
 
 ### DDWAF_OBJ_TYPE
 
 Specifies the type of a ddwaf::object.
 
-| Value | Code |
-|-------|------|
-| `DDWAF_OBJ_INVALID` | `= 0` |
-| `DDWAF_OBJ_NULL` | `= 0x01` |
-| `DDWAF_OBJ_BOOL` | `= 0x02` |
-| `DDWAF_OBJ_SIGNED` | `= 0x04` |
-| `DDWAF_OBJ_UNSIGNED` | `= 0x06` |
-| `DDWAF_OBJ_FLOAT` | `= 0x08` |
-| `DDWAF_OBJ_STRING` | `= 0x10` |
-| `DDWAF_OBJ_LITERAL_STRING` | `= 0x12` |
-| `DDWAF_OBJ_SMALL_STRING` | `= 0x14` |
-| `DDWAF_OBJ_ARRAY` | `= 0x20` |
-| `DDWAF_OBJ_MAP` | `= 0x40` |
+| Value | Code | Description |
+|-------|------|-------------|
+| `DDWAF_OBJ_INVALID` | `= 0` | Unkmown or uninitialised type |
+| `DDWAF_OBJ_NULL` | `= 0x01` | Null type, only used for its semantical value |
+| `DDWAF_OBJ_BOOL` | `= 0x02` | Boolean type |
+| `DDWAF_OBJ_SIGNED` | `= 0x04` | 64-bit signed integer type |
+| `DDWAF_OBJ_UNSIGNED` | `= 0x06` | 64-bit unsigned integer type |
+| `DDWAF_OBJ_FLOAT` | `= 0x08` | 64-bit float (or double) type |
+| `DDWAF_OBJ_STRING` | `= 0x10` | Dynamic UTF-8 string of up to max(uint32) length |
+| `DDWAF_OBJ_LITERAL_STRING` | `= 0x12` | Literal UTF-8 string of up to max(uint32) length, these are never freed |
+| `DDWAF_OBJ_SMALL_STRING` | `= 0x14` | UTF-8 string of up to 14 bytes in length |
+| `DDWAF_OBJ_ARRAY` | `= 0x20` | Array of ddwaf_object, up to max(uint16) capacity |
+| `DDWAF_OBJ_MAP` | `= 0x40` | Array of ddwaf_object_kv, up to max(uint16) capacity |
 
 ### DDWAF_RET_CODE
 
 Codes returned by ddwaf_context_eval.
 
-| Value | Code |
-|-------|------|
-| `DDWAF_ERR_INTERNAL` | `= -3` |
-| `DDWAF_ERR_INVALID_OBJECT` | `= -2` |
-| `DDWAF_ERR_INVALID_ARGUMENT` | `= -1` |
-| `DDWAF_OK` | `= 0` |
-| `DDWAF_MATCH` | `= 1` |
+| Value | Code | Description |
+|-------|------|-------------|
+| `DDWAF_ERR_INTERNAL` | `= -3` | Unknown error, typically due to an unexpected exception |
+| `DDWAF_ERR_INVALID_OBJECT` | `= -2` | The provided data object didn't match the expected schema |
+| `DDWAF_ERR_INVALID_ARGUMENT` | `= -1` | One or more of the provided arguments to a function is invalid |
+| `DDWAF_OK` | `= 0` | The data evaluation didn't yield any events, attributes, etc |
+| `DDWAF_MATCH` | `= 1` | The data evaluation resulted in an event, attribute, etc |
 
 ### DDWAF_LOG_LEVEL
 
 Internal WAF log levels, to be used when setting the minimum log level and cb.
 
-| Value |
-|-------|
-| `DDWAF_LOG_TRACE` |
-| `DDWAF_LOG_DEBUG` |
-| `DDWAF_LOG_INFO` |
-| `DDWAF_LOG_WARN` |
-| `DDWAF_LOG_ERROR` |
-| `DDWAF_LOG_OFF` |
+| Value | Code | Description |
+|-------|------|-------------|
+| `DDWAF_LOG_TRACE` | `= 0` | Finest-grained logging for detailed tracing |
+| `DDWAF_LOG_DEBUG` | `= 1` | Debugging information for development |
+| `DDWAF_LOG_INFO` | `= 2` | General informational messages |
+| `DDWAF_LOG_WARN` | `= 3` | Warning messages for potential issues |
+| `DDWAF_LOG_ERROR` | `= 4` | Error messages for failures |
+| `DDWAF_LOG_OFF` | `= 5` | Disable all logging |
 
 ---
 
@@ -64,6 +85,7 @@ Internal WAF log levels, to be used when setting the minimum log level and cb.
 | `ddwaf_free_fn_type` | `typedef void() ddwaf_free_fn_type(void *, void *, size_t, size_t)` |
 | `ddwaf_udata_free_fn_type` | `typedef void() ddwaf_udata_free_fn_type(void *)` |
 | `ddwaf_object` | `typedef union _ddwaf_object ddwaf_object` |
+| `ddwaf_object_kv` | `typedef struct _ddwaf_object_kv ddwaf_object_kv` |
 
 ### ddwaf_log_cb
 
@@ -297,13 +319,13 @@ Perform a matching operation on the provided data
 - `data`: (nonnull) Data on which to perform the pattern matching. This data will be stored by the context and used across multiple calls to this function or ddwaf_subcontext_eval. Once the context is destroyed, the user defined allocator will be used to free the data provided. Note that the data passed must be valid until the destruction of the context. The object must be a map of {string,
 - `alloc`: (nullable) Allocator used to free the data provided. If NULL, the data will not be freed.
 - `result`: (nullable) Object map containing the following items:
-  - `events`: an array of the generated events.
-  - `actions`: a map of the generated actions in the format: "{action type: { <parameter map> }, ...}"
-  - `duration`: an unsigned specifying the total runtime of the call in nanoseconds.
-  - `timeout`: whether there has been a timeout during the call.
-  - `attributes`: a map containing all derived objects in the format: {tag, value}
-  - `keep`: whether the data contained herein must override any transport sampling through the relevant mechanism. This structure must be freed by the caller using the output allocator provided through ddwaf_context_init. The object will contain all specified keys when the value returned by ddwaf_context_eval is either DDWAF_OK or DDWAF_MATCH and will be empty otherwise.
-  - **IMPORTANT**: This object is not allocated with the allocator passed in this call. It uses the allocator given to ddwaf_context_init instead.
+	- `events`: an array of the generated events.
+	- `actions`: a map of the generated actions in the format: "{action type: { <parameter map> }, ...}"
+	- `duration`: an unsigned specifying the total runtime of the call in nanoseconds.
+	- `timeout`: whether there has been a timeout during the call.
+	- `attributes`: a map containing all derived objects in the format: {tag, value}
+	- `keep`: whether the data contained herein must override any transport sampling through the relevant mechanism. This structure must be freed by the caller using the output allocator provided through ddwaf_context_init. The object will contain all specified keys when the value returned by ddwaf_context_eval is either DDWAF_OK or DDWAF_MATCH and will be empty otherwise.
+	- **IMPORTANT**: This object is not allocated with the allocator passed in this call. It uses the allocator given to ddwaf_context_init instead.
 - `timeout`: Maximum time budget in microseconds.
 
 **Returns:** Return code of the operation.
@@ -356,13 +378,13 @@ Perform a matching operation on the provided data
 - `data`: (nonnull) Data on which to perform the pattern matching. This data will be stored by the subcontext and used across multiple calls to this function. Once the subcontext is destroyed, the user defined allocator will be used to free the data provided. Note that the data passed must be valid until the destruction of the subcontext. The object must be a map of {string,
 - `alloc`: (nullable) Allocator used to free the data provided. If NULL, the data will not be freed.
 - `result`: (nullable) Object map containing the following items:
-  - `events`: an array of the generated events.
-  - `actions`: a map of the generated actions in the format: "{action type: { <parameter map> }, ...}"
-  - `duration`: an unsigned specifying the total runtime of the call in nanoseconds.
-  - `timeout`: whether there has been a timeout during the call.
-  - `attributes`: a map containing all derived objects in the format: {tag, value}
-  - `keep`: whether the data contained herein must override any transport sampling through the relevant mechanism. This structure must be freed by the caller and will contain all specified keys when the value returned by ddwaf_subcontext_eval is either DDWAF_OK or DDWAF_MATCH and will be empty otherwise.
-  - **IMPORTANT**: This object is not allocated with the allocator passed in this call. It uses the allocator given to ddwaf_context_init instead.
+	- `events`: an array of the generated events.
+	- `actions`: a map of the generated actions in the format: "{action type: { <parameter map> }, ...}"
+	- `duration`: an unsigned specifying the total runtime of the call in nanoseconds.
+	- `timeout`: whether there has been a timeout during the call.
+	- `attributes`: a map containing all derived objects in the format: {tag, value}
+	- `keep`: whether the data contained herein must override any transport sampling through the relevant mechanism. This structure must be freed by the caller and will contain all specified keys when the value returned by ddwaf_subcontext_eval is either DDWAF_OK or DDWAF_MATCH and will be empty otherwise.
+	- **IMPORTANT**: This object is not allocated with the allocator passed in this call. It uses the allocator given to ddwaf_context_init instead.
 - `timeout`: Maximum time budget in microseconds.
 
 **Returns:** Return code of the operation.
diff --git a/include/ddwaf.h b/include/ddwaf.h
index f2a4ac011..043d21d29 100644
--- a/include/ddwaf.h
+++ b/include/ddwaf.h
@@ -41,26 +41,27 @@ extern "C"
  **/
 typedef enum
 {
+    /** Unkmown or uninitialised type **/
     DDWAF_OBJ_INVALID  = 0,
-    // Null type, only used for its semantical value
+    /** Null type, only used for its semantical value **/
     DDWAF_OBJ_NULL     = 0x01,
-    // Boolean type
+    /** Boolean type **/
     DDWAF_OBJ_BOOL     = 0x02,
-    // 64-bit signed integer type
+    /** 64-bit signed integer type **/
     DDWAF_OBJ_SIGNED   = 0x04,
-    // 64-bit unsigned integer type
+    /** 64-bit unsigned integer type **/
     DDWAF_OBJ_UNSIGNED = 0x06,
-    // 64-bit float (or double) type
+    /** 64-bit float (or double) type **/
     DDWAF_OBJ_FLOAT    = 0x08,
-    // Dynamic UTF-8 string of up to max(uint16) length
+    /** Dynamic UTF-8 string of up to max(uint32) length **/
     DDWAF_OBJ_STRING   = 0x10,
-    // Literal UTF-8 string of up to max(uint32) length, these are never freed
+    /** Literal UTF-8 string of up to max(uint32) length, these are never freed **/
     DDWAF_OBJ_LITERAL_STRING   = 0x12,
-    // UTF-8 string of up to 14 bytes in length
+    /** UTF-8 string of up to 14 bytes in length **/
     DDWAF_OBJ_SMALL_STRING   = 0x14,
-    // Array of ddwaf_object of length nbEntries, each item having no parameterName
+    /** Array of ddwaf_object, up to max(uint16) capacity **/
     DDWAF_OBJ_ARRAY    = 0x20,
-    // Array of ddwaf_object of length nbEntries, each item having a parameterName
+    /** Array of ddwaf_object_kv, up to max(uint16) capacity **/
     DDWAF_OBJ_MAP      = 0x40,
 } DDWAF_OBJ_TYPE;
 
@@ -71,10 +72,15 @@ typedef enum
  **/
 typedef enum
 {
+    /** Unknown error, typically due to an unexpected exception **/
     DDWAF_ERR_INTERNAL          = -3,
+    /** The provided data object didn't match the expected schema **/
     DDWAF_ERR_INVALID_OBJECT    = -2,
+    /** One or more of the provided arguments to a function is invalid **/
     DDWAF_ERR_INVALID_ARGUMENT  = -1,
+    /** The data evaluation didn't yield any events, attributes, etc **/
     DDWAF_OK                    = 0,
+    /** The data evaluation resulted in an event, attribute, etc **/
     DDWAF_MATCH                 = 1,
 } DDWAF_RET_CODE;
 
@@ -85,12 +91,18 @@ typedef enum
  **/
 typedef enum
 {
-    DDWAF_LOG_TRACE,
-    DDWAF_LOG_DEBUG,
-    DDWAF_LOG_INFO,
-    DDWAF_LOG_WARN,
-    DDWAF_LOG_ERROR,
-    DDWAF_LOG_OFF,
+    /** Finest-grained logging for detailed tracing */
+    DDWAF_LOG_TRACE = 0,
+    /** Debugging information for development */
+    DDWAF_LOG_DEBUG = 1,
+    /** General informational messages */
+    DDWAF_LOG_INFO = 2,
+    /** Warning messages for potential issues */
+    DDWAF_LOG_WARN = 3,
+    /** Error messages for failures */
+    DDWAF_LOG_ERROR = 4,
+    /** Disable all logging */
+    DDWAF_LOG_OFF = 5,
 } DDWAF_LOG_LEVEL;
 
 #ifndef __cplusplus
@@ -106,8 +118,7 @@ typedef void (ddwaf_udata_free_fn_type)(void *);
 #endif
 
 typedef union _ddwaf_object ddwaf_object;
-
-struct _ddwaf_object_kv;
+typedef struct _ddwaf_object_kv ddwaf_object_kv;
 
 struct _ddwaf_object_bool {
     uint8_t type;
@@ -385,8 +396,8 @@ ddwaf_subcontext ddwaf_subcontext_init(ddwaf_context context);
  *               - keep: whether the data contained herein must override any
  *                       transport sampling through the relevant mechanism.
  *               This structure must be freed by the caller and will contain all
- *               specified keys when the value returned by ddwaf_subcontext_eval is either
- *               DDWAF_OK or DDWAF_MATCH and will be empty otherwise.
+ *               specified keys when the value returned by ddwaf_subcontext_eval
+ *               is either DDWAF_OK or DDWAF_MATCH and will be empty otherwise.
  *               IMPORTANT: This object is not allocated with the allocator
  *               passed in this call. It uses the allocator given to
  *               ddwaf_context_init instead.

From 7e90a3451c85b918b34e1229297f3fa867b9c6bd Mon Sep 17 00:00:00 2001
From: Anil Mahtani <929854+Anilm3@users.noreply.github.com>
Date: Wed, 21 Jan 2026 17:26:03 +0000
Subject: [PATCH 32/32] Fixes and obfuscator use example in the upgrading guide

---
 docs/README.md                     |  2 +-
 docs/changelog/CHANGELOG-v2.0.0.md |  4 +--
 docs/upgrading/UPGRADING-v2.0.md   | 58 +++++++++++++++++++++++++++++-
 3 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index 242bae166..f4c901982 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -3,5 +3,5 @@
 - Overview (TBD) – Architectural summary and execution pipeline.
 - [C API Reference](c-api/api.md) – Comprehensive description of all exported functions, structs, and macros.
 - [Binding Integration Guide](c-api/binding-integration-guide.md) – Guidance for language bindings embedding libddwaf.
-- [Latest Changelog](changelog/CHANGELOG-latest.md) – Release notes for the current version; see the [changelog](changelog/) directory for previous versions.
+- [Changelogs](changelog/) – Release notes for all versions, the CHANGELOG-latest.md symlink always points to the latest release changelog.
 - [Upgrading Guides](upgrading/) - Upgrading guides for all versions with relevant and / or breaking changes.
diff --git a/docs/changelog/CHANGELOG-v2.0.0.md b/docs/changelog/CHANGELOG-v2.0.0.md
index 5b0a43433..76aff5d94 100644
--- a/docs/changelog/CHANGELOG-v2.0.0.md
+++ b/docs/changelog/CHANGELOG-v2.0.0.md
@@ -21,10 +21,10 @@ The function `ddwaf_run` has been renamed to `ddwaf_context_eval` for consistenc
 ## Release Changelog
 ### Changes
 
-- Object model overhaul: immutable `object_view`, owned/borrowed writable objects, raw configuration on `object_view`, container view types, and updated unit tests ([#341](https://github.com/DataDog/libddwaf/pull/341), [#378](https://github.com/DataDog/libddwaf/pull/378), [#382](https://github.com/DataDog/libddwaf/pull/382), [#387](https://github.com/DataDog/libddwaf/pull/387), [#390](https://github.com/DataDog/libddwaf/pull/390), [#391](https://github.com/DataDog/libddwaf/pull/391), [#394](https://github.com/DataDog/libddwaf/pull/394), [#408](https://github.com/DataDog/libddwaf/pull/408), [#413](https://github.com/DataDog/libddwaf/pull/413)), ([#476](https://github.com/DataDog/libddwaf/pull/476)).
+- Object model overhaul: immutable `object_view`, owned/borrowed writable objects, raw configuration on `object_view`, container view types, and updated unit tests ([#341](https://github.com/DataDog/libddwaf/pull/341), [#378](https://github.com/DataDog/libddwaf/pull/378), [#382](https://github.com/DataDog/libddwaf/pull/382), [#387](https://github.com/DataDog/libddwaf/pull/387), [#390](https://github.com/DataDog/libddwaf/pull/390), [#391](https://github.com/DataDog/libddwaf/pull/391), [#394](https://github.com/DataDog/libddwaf/pull/394), [#408](https://github.com/DataDog/libddwaf/pull/408), [#413](https://github.com/DataDog/libddwaf/pull/413), [#476](https://github.com/DataDog/libddwaf/pull/476)).
 - Allocator API: propagate allocators through contexts/subcontexts, expose allocator-aware interfaces, and stop generating zero-terminated strings ([#418](https://github.com/DataDog/libddwaf/pull/418), [#420](https://github.com/DataDog/libddwaf/pull/420), [#427](https://github.com/DataDog/libddwaf/pull/427), [#452](https://github.com/DataDog/libddwaf/pull/452)).
 - Refactored evaluation lifecycle: separated data insertion from evaluation and lifted evaluation stages out of the context ([#407](https://github.com/DataDog/libddwaf/pull/407), [#442](https://github.com/DataDog/libddwaf/pull/442)).
-- Subcontexts with user-defined lifetimes and validator support for subcontexts/attributes ([#443](https://github.com/DataDog/libddwaf/pull/443), [#451](https://github.com/DataDog/libddwaf/pull/451)), ([#468](https://github.com/DataDog/libddwaf/pull/468)).
+- Subcontexts with user-defined lifetimes and validator support for subcontexts/attributes ([#443](https://github.com/DataDog/libddwaf/pull/443), [#451](https://github.com/DataDog/libddwaf/pull/451), [#468](https://github.com/DataDog/libddwaf/pull/468)).
 - Array indexing on key paths ([#458](https://github.com/DataDog/libddwaf/pull/458)).
 - Instantiate obfuscator through configuration and remove `ddwaf_config` ([#464](https://github.com/DataDog/libddwaf/pull/464)).
 - Return `DDWAF_MATCH` when events, attributes, or actions are present ([#455](https://github.com/DataDog/libddwaf/pull/455)).
diff --git a/docs/upgrading/UPGRADING-v2.0.md b/docs/upgrading/UPGRADING-v2.0.md
index 885771600..ce1377bad 100644
--- a/docs/upgrading/UPGRADING-v2.0.md
+++ b/docs/upgrading/UPGRADING-v2.0.md
@@ -25,7 +25,7 @@ However, note that other allocators are also available. See the [allocators docu
 
 ## 1. WAF instantiation: Removal of `ddwaf_config`
 
-The main changes pertaining to WAF initialisation are the removal of `ddwaf_config`, as the evaluation limits have been entirely removed, in favour of user-controlled truncation, and the free function is no longer required due to the explicit memory ownership defined through allocators. As a consequence, instantiation through `ddwaf_init` has changed as follows:
+The main changes pertaining to WAF initialisation are the removal of `ddwaf_config`, as the evaluation limits have been entirely removed, in favour of user-controlled truncation, the free function is no longer required due to the explicit memory ownership defined through allocators and the obfuscator is now configured through a configuration. As a consequence, instantiation through `ddwaf_init` has changed as follows:
 
 **v1.x:**
 ```c
@@ -56,6 +56,62 @@ ddwaf_builder builder = ddwaf_builder_init(&config);
 ddwaf_builder builder = ddwaf_builder_init();
 ```
 
+### Obfuscator Configuration
+
+In v1.x, the obfuscator regexes were provided through `ddwaf_config`. In v2.x, the obfuscator must be configured through the builder by providing a configuration containing the `obfuscator` key. The configuration format is:
+
+```yaml
+obfuscator:
+  key_regex: "<regex>"    # Optional, defaults to built-in key regex
+  value_regex: "<regex>"  # Optional, defaults to built-in value regex
+```
+
+Both `key_regex` and `value_regex` are optional; if not provided, the built-in defaults are used.
+
+**v1.x:**
+```c
+ddwaf_config config;
+memset(&config, 0, sizeof(config));
+config.obfuscator.key_regex = "^password$";
+config.obfuscator.value_regex = "^secret_.*";
+
+ddwaf_handle handle = ddwaf_init(&ruleset, &config, &diagnostics);
+// or
+ddwaf_builder builder = ddwaf_builder_init(&config);
+```
+
+**v2.x:**
+```c
+ddwaf_builder builder = ddwaf_builder_init();
+
+// Create an obfuscator configuration
+ddwaf_allocator alloc = ddwaf_get_default_allocator();
+ddwaf_object obfuscator_config;
+ddwaf_object_set_map(&obfuscator_config, 1, alloc);
+
+ddwaf_object *obfuscator = ddwaf_object_insert_literal_key(
+    &obfuscator_config, "obfuscator", 10, alloc);
+ddwaf_object_set_map(obfuscator, 2, alloc);
+
+ddwaf_object_set_string_literal(
+    ddwaf_object_insert_literal_key(obfuscator, "key_regex", 9, alloc),
+    "^password$", 10);
+
+ddwaf_object_set_string_literal(
+    ddwaf_object_insert_literal_key(obfuscator, "value_regex", 11, alloc),
+    "^secret_.*", 10);
+
+// Add the obfuscator configuration to the builder
+ddwaf_object diagnostics;
+ddwaf_builder_add_or_update_config(builder,
+    "obfuscator/config", 17, &obfuscator_config, &diagnostics);
+
+ddwaf_object_destroy(&obfuscator_config, alloc);
+ddwaf_object_destroy(&diagnostics, ddwaf_get_default_allocator());
+```
+
+The obfuscator configuration can be provided as a standalone configuration or combined with other configurations (e.g., rules) in a single `ddwaf_builder_add_or_update_config` call.
+
 Note that the `diagnostics` object is allocated with the default allocator and must be destroyed as follows:
 
 ```c