1 files changed, 68 insertions, 0 deletions
diff --git a/docs/ccdjit-improvements.md b/docs/ccdjit-improvements.md
new file mode 100644
index 0000000..4b48589
--- /dev/null
+++ b/docs/ccdjit-improvements.md
@@ -0,0 +1,68 @@
+# CCDJIT improvements status for Ecex plugins
+
+Ecex now treats plugin state as a host-owned capability, but several plugin API
+constraints still exist because the JIT-to-host boundary is fragile in places.
+
+## Resolved in current CCDJIT
+
+- Multidimensional numeric arrays are usable from plugin code again.
+- Ecex added `ecex_plugin_slot_i32_get_2d` and
+  `ecex_plugin_slot_i32_set_2d` for host-owned board/grid state.
+- Higher-arity host calls are usable again; Ecex now exposes
+  `ecex_draw_plugin_text_rect_i` as a richer integer/text helper.
+- Normal allocation lowering is fixed. Ecex still requires durable plugin state
+  to live in plugin slots, plugin objects, or plugin text so cleanup and
+  cross-plugin access stay host-owned.
+- Ecex config loading now uses `ccdjit_compile_file_module` and looks up
+  `ecex_config_init` directly instead of appending a synthetic `main`.
+
+## ABI conformance tests
+
+Add a small CCDJIT test suite that calls host functions through generated code
+and covers:
+
+- integer and pointer arguments and return values;
+- float and double arguments and return values;
+- callbacks with six or more arguments;
+- structs and struct-field reads/writes;
+- arrays of string literals and `const char *` array indexing;
+- long-lived callback function pointers retained after compile-time setup.
+
+These should be standalone CCDJIT tests, not only Ecex integration tests.
+
+## Safe ABI profile
+
+Document or expose a safe host-call profile that embedders can target. Ecex
+currently favors integer-only plugin helpers, host-owned objects, and copy-based
+text because those paths are predictable.
+
+Static completion lists should use `ecex_define_word_completion_provider` plus
+`ecex_completion_provider_add_words`. That passes one string literal blob over
+the host boundary and avoids depending on JIT-side `const char *` array
+indexing.
+
+Runtime plugin callbacks should avoid variadic C library calls such as
+`snprintf`. Build strings with fixed-arity helpers or host APIs instead; the C
+tools plugin uses append helpers for this reason.
+
+## Diagnostics
+
+Improve diagnostics for:
+
+- unresolved host symbols;
+- unsafe implicit symbol resolution;
+- callback signatures that cannot be called reliably;
+- sandbox failures versus compile/type failures.
+
+## Module loading shape
+
+Ecex now uses CCDJIT's module-oriented compile path for config files. The
+remaining upstream opportunity is a first-class example/test for this embedder
+flow: compile a module, validate an init symbol, call it, retain callback code
+for later renderer/animation/mouse dispatch, and release it after host cleanup.
+
+## Capability registration
+
+Ecex has a large flat host symbol table. CCDJIT should provide examples or
+helpers for registering named capability groups so hosts can expose smaller,
+auditable APIs to plugin code.