From 757638d6a03ba8deded7a518d54f7f10b2b56a72 Mon Sep 17 00:00:00 2001
From: Piotr Sikora <code@piotrsikora.dev>
Date: Thu, 24 Sep 2026 11:56:16 -0400
Subject: [PATCH] Use enums in custom functions.

Signed-off-by: Piotr Sikora <code@piotrsikora.dev>
---
 abi-versions/vNEXT/README.md                  | 14 +++++++-----
 .../vNEXT/registries/CUSTOM_FUNCTIONS.md      | 22 +++++++++++++++++++
 2 files changed, 30 insertions(+), 6 deletions(-)
 create mode 100644 abi-versions/vNEXT/registries/CUSTOM_FUNCTIONS.md

diff --git a/abi-versions/vNEXT/README.md b/abi-versions/vNEXT/README.md
index ab5289c..56f3b03 100644
--- a/abi-versions/vNEXT/README.md
+++ b/abi-versions/vNEXT/README.md
@@ -2095,8 +2095,7 @@ This function is gated on [`HAS_PROPERTIES`] host feature.
 #### `proxy_call_foreign_function`
 
 * params:
-  - `i32 (const char *) name_data`
-  - `i32 (size_t) name_size`
+  - `i32 (uint32_t) custom_function_id`
   - `i32 (const uint8_t *) arguments_data`
   - `i32 (size_t) arguments_size`
   - `i32 (uint8_t **) return_results_data`
@@ -2104,8 +2103,8 @@ This function is gated on [`HAS_PROPERTIES`] host feature.
 * returns:
   - `i32 (`[`proxy_status_t`]`) status`
 
-Calls registered foreign function (`name_data`, `name_size`)
-with arguments (`arguments_data`, `arguments_size`).
+Calls [custom function] `custom_function_id` with arguments
+(`arguments_data`, `arguments_size`).
 
 Return value(s) (`return_results_data`, `return_results_size`)
 are optional.
@@ -2126,12 +2125,12 @@ This function is gated on [`HAS_CUSTOM_FUNCTIONS`] host feature.
 
 * params:
   - `i32 (uint32_t) plugin_context_id`
-  - `i32 (uint32_t) function_id`
+  - `i32 (uint32_t) custom_callback_id`
   - `i32 (size_t) arguments_size`
 * returns:
   - none
 
-Called when a registered foreign callback `function_id` is called.
+Called when a [custom callback] `custom_callback_id` is called.
 
 Its arguments (of `arguments_size`) can be retrieved using
 [`proxy_get_buffer_bytes`] with `buffer_id` set to
@@ -2414,6 +2413,9 @@ changes to unrelated connections/requests.
 [`HAS_CUSTOM_FUNCTIONS`]: ./registries/HOST_FEATURES.md
 [`HAS_WASI_PREVIEW1_CORE`]: ./registries/HOST_FEATURES.md
 
+[custom function]: ./registries/CUSTOM_FUNCTIONS.md
+[custom callbacks]: ./registries/CUSTOM_FUNCTIONS.md
+
 [`proxy_abi_version_0_x_x`]: #proxy_abi_version_0_x_x
 [`_initialize`]: #_initialize
 [`main`]: #main
diff --git a/abi-versions/vNEXT/registries/CUSTOM_FUNCTIONS.md b/abi-versions/vNEXT/registries/CUSTOM_FUNCTIONS.md
new file mode 100644
index 0000000..9b73dab
--- /dev/null
+++ b/abi-versions/vNEXT/registries/CUSTOM_FUNCTIONS.md
@@ -0,0 +1,22 @@
+# Custom functions and callbacks
+
+#### Custom functions
+
+| Identifier | Name             | Arguments | Return value | Description                                                   |
+|:----------:|:-----------------|:---------:|:------------:|:--------------------------------------------------------------|
+
+
+#### Custom callbacks
+
+| Identifier | Name             | Arguments | Return value | Description                                                   |
+|:----------:|:-----------------|:---------:|:------------:|:--------------------------------------------------------------|
+
+
+Identifiers below 0x2000 are reserved for standardized functions and callbacks.
+
+Numbers above that range are considered private and can be used without assignment in the registry.
+
+Random number in the private range should be used for private extensions and functions and callbacks under active development.
+
+Once the custom function or callback is finalized and implemented in a subset of hosts and SDKs, it will be assigned identifier
+in the standardized range.