zingcore 2.5 ABI

Author: eldiablolives

src/zem/zingcore2.2_final/zingcore/README.md

@@ -3,7 +3,8 @@
 This folder defines the **new final micro ABI** for Zing hosts and runtimes.
 
 - Spec: `zingcore/ABI_V2.md`
-- C header (canonical signatures): `zingcore/include/zi_abi_v2.h`
+- C header (native shim API): `zingcore/include/zi_abi_v2.h`
+- System ABI header (wire contract): `zingcore/include/zi_sysabi_v2.h`
 
 Design goals:
 - Pure `zi_*` C ABI calls (no framed control-plane protocols).

src/zem/zingcore2.2_final/zingcore/include/zi_abi_v2.h

@@ -9,6 +9,13 @@ extern "C" {
 
 typedef int32_t zi_handle_t;
 
+/*
+ * NOTE:
+ *   This header is a C-friendly API surface (native shim).
+ *   For the fixed-width system ABI (wire contract), use:
+ *     zi_sysabi_v2.h
+ */
+
 /* ------------------------------------------------------------------------- */
 /* ZASM note: "core ABI" vs optional capability surfaces                     */
 /*

src/zem/zingcore2.2_final/zingcore/include/zi_sysabi_v2.h

@@ -0,0 +1,122 @@
+#pragma once
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * System ABI (wire contract) — v2.x
+ *
+ * This header defines the *wire-level* signatures at the system boundary.
+ * It is suitable for both native shims and WASM hosts.
+ *
+ * Key rules for ABI stability:
+ * - All integers are fixed-width.
+ * - Guest memory pointers are carried as 64-bit values (zi_ptr_t).
+ *   WASM32 runtimes typically interpret these as zero-extended 32-bit offsets
+ *   into linear memory; higher bits must be rejected.
+ * - Lengths/capacities are 32-bit.
+ * - Error returns are negative int32_t values.
+ *
+ * Minimal core ABI (always present):
+ *   zi_abi_version, zi_abi_features
+ *   zi_ctl
+ *   zi_read, zi_write, zi_end
+ *   zi_alloc, zi_free
+ *   zi_telemetry
+ *
+ * Optional extension (caps model):
+ *   If a runtime exposes any capabilities, it must also provide zi_cap_* and
+ *   zi_handle_hflags.
+ */
+
+typedef int32_t zi_handle_t;
+
+typedef uint64_t zi_ptr_t;   /* guest memory address/offset */
+typedef uint32_t zi_size32_t;/* byte counts (req_len, resp_cap, etc.) */
+
+enum {
+  ZI_OK = 0,
+
+  ZI_E_INVALID  = -1,
+  ZI_E_BOUNDS   = -2,
+  ZI_E_NOENT    = -3,
+  ZI_E_DENIED   = -4,
+  ZI_E_CLOSED   = -5,
+  ZI_E_AGAIN    = -6,
+  ZI_E_NOSYS    = -7,
+  ZI_E_OOM      = -8,
+  ZI_E_IO       = -9,
+  ZI_E_INTERNAL = -10,
+};
+
+enum {
+  /* Non-normative feature bits; see runtime pack policy. */
+  ZI_FEAT_FS    = 1ull << 0,
+  ZI_FEAT_ASYNC = 1ull << 1,
+  ZI_FEAT_TIME  = 1ull << 2,
+  ZI_FEAT_EXEC  = 1ull << 3,
+  ZI_FEAT_PROC  = 1ull << 4,
+};
+
+enum {
+  /* ZCL1 framing ops (control plane). */
+  ZI_CTL_OP_CAPS_LIST     = 1,
+  ZI_CTL_OP_CAPS_DESCRIBE = 2,
+  ZI_CTL_OP_CAPS_OPEN     = 3,
+};
+
+enum {
+  ZI_CAP_CAN_OPEN  = 1u << 0,
+  ZI_CAP_PURE      = 1u << 1,
+  ZI_CAP_MAY_BLOCK = 1u << 2,
+};
+
+enum {
+  ZI_H_READABLE = 1u << 0,
+  ZI_H_WRITABLE = 1u << 1,
+  ZI_H_ENDABLE  = 1u << 2,
+  ZI_H_SEEKABLE = 1u << 3,
+};
+
+typedef struct {
+  zi_ptr_t kind_ptr;
+  int32_t  kind_len;
+  zi_ptr_t name_ptr;
+  int32_t  name_len;
+  uint32_t mode;
+  zi_ptr_t params_ptr;
+  int32_t  params_len;
+} zi_cap_open_req_v2;
+
+/* --- Minimal core surface (expected everywhere) --- */
+
+uint32_t zi_abi_version(void);
+uint64_t zi_abi_features(void);
+
+int32_t zi_ctl(zi_ptr_t req_ptr, zi_size32_t req_len,
+               zi_ptr_t resp_ptr, zi_size32_t resp_cap);
+
+int32_t  zi_read(zi_handle_t h, zi_ptr_t dst_ptr, zi_size32_t cap);
+int32_t  zi_write(zi_handle_t h, zi_ptr_t src_ptr, zi_size32_t len);
+int32_t  zi_end(zi_handle_t h);
+
+zi_ptr_t  zi_alloc(zi_size32_t size);
+int32_t  zi_free(zi_ptr_t ptr);
+
+int32_t  zi_telemetry(zi_ptr_t topic_ptr, zi_size32_t topic_len,
+                      zi_ptr_t msg_ptr, zi_size32_t msg_len);
+
+/* --- Caps extension (optional; required if any caps exist) --- */
+
+int32_t zi_cap_count(void);
+int32_t zi_cap_get_size(int32_t index);
+int32_t zi_cap_get(int32_t index, zi_ptr_t out_ptr, zi_size32_t out_cap);
+zi_handle_t zi_cap_open(zi_ptr_t req_ptr);
+uint32_t zi_handle_hflags(zi_handle_t h);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif

src/zingcore/2.5/Makefile

@@ -17,19 +17,29 @@ LIB := $(BUILD)/libzingcore25.a
 
 SRC := \
 	$(SRCDIR)/zingcore25.c \
+	$(SRCDIR)/zi_runtime25.c \
+	$(SRCDIR)/zi_handles25.c \
+	$(SRCDIR)/zi_zcl1.c \
+	$(SRCDIR)/zi_syscalls_core25.c \
+	$(SRCDIR)/zi_syscalls_caps25.c \
 	$(SRCDIR)/zi_caps.c \
 	$(SRCDIR)/zi_async.c \
 	$(SRCDIR)/zi_problem.c \
 	$(SRCDIR)/zi_telemetry.c
 
 OBJ := \
 	$(BUILD)/zingcore25.o \
+	$(BUILD)/zi_runtime25.o \
+	$(BUILD)/zi_handles25.o \
+	$(BUILD)/zi_zcl1.o \
+	$(BUILD)/zi_syscalls_core25.o \
+	$(BUILD)/zi_syscalls_caps25.o \
 	$(BUILD)/zi_caps.o \
 	$(BUILD)/zi_async.o \
 	$(BUILD)/zi_problem.o \
 	$(BUILD)/zi_telemetry.o
 
-TESTS := test_caps test_async_registry test_zingcore25_api test_problem test_telemetry_jsonl
+TESTS := test_caps test_async_registry test_zingcore25_api test_problem test_telemetry_jsonl test_sysabi25_min_core test_sysabi25_ctl_caps_list
 
 .PHONY: test
 

src/zingcore/2.5/dist/debug/include/README.md

@@ -1,11 +1,24 @@
-# zingcore2.5 public headers (WIP)
+# zingcore 25-family public headers
 
-This directory will contain the **public** headers for the zABI 2.5 runtime.
+This folder contains the public headers for the zingcore **25-family** implementation.
 
-Rules:
+## Naming policy
 
-- Headers in this folder define the stable API surface.
-- Keep includes minimal and C11-friendly.
-- Avoid leaking internal structs; prefer opaque handles.
+- **Wire/system ABI:** the stable syscall surface is `zi_*` as declared by the family’s sysabi header
+	(for 2.5 that is `zi_sysabi25.h`). These names are *not* family-suffixed.
+- **Wiring/implementation:** process-global wiring and convenience APIs are family-namespaced
+	(e.g. `zingcore25_*`, `zi_runtime25_*`).
+
+## What “25” means
+
+“25” is a **family namespace**, not “ABI version digits in a function name”.
 
-Status: placeholder (not yet wired into the build).
+The intent is that 2.5 / 2.6 / 2.7 / … stay within the same wiring family without renaming exported
+wiring symbols on every minor bump. We only introduce a new family number when we make a truly
+incompatible wiring break.
+
+## General rules
+
+- Keep includes minimal and C11-friendly.
+- Prefer fixed-width integer types at ABI boundaries.
+- Avoid leaking internal structs; prefer opaque handles where practical.