Release 0.3.1 — sync to ktav 0.3.1 + spec 0.1.1

Backward-compatible feature release tracking ktav 0.3.1 and spec 0.1.1.

Added
- Top-level Array support (spec 0.1.1) — Ktav.loads now returns
  Value.Arr when the document begins with array-item shapes; Ktav.dumps
  accepts Value.Arr at the top level.
- Ktav.toStringForceStrings(Value) — render with every leaf scalar
  coerced to a String via the raw marker (::).

Changed
- Picked up ktav 0.3.1 (workspace dep + cabi).
- spec submodule synced to 7256816 (spec 0.1.1).
- NativeLoader.LIB_VERSION bumped 0.1.2 -> 0.3.1 to track the matching
  GitHub Release asset (cabi adds ktav_dumps_force_strings).

Author: PHPCraftdream

CHANGELOG.md

@@ -11,6 +11,34 @@ This changelog tracks **binding releases**, not changes to the Ktav format
 itself — for the latter see
 [`ktav-lang/spec`](https://github.com/ktav-lang/spec/blob/main/CHANGELOG.md).
 
+## 0.3.1 — 2026-05-10
+
+### Added
+
+- **Top-level Array support** (spec § 5.0.1, ktav 0.3.1) — first
+  content line decides Object vs Array. `Ktav.loads` now returns
+  `Value.Arr` when the document begins with array-item shapes (bare
+  scalars, typed/raw markers, lone openers, multi-line openers); all
+  prior 0.3.0-valid documents still parse to the same `Value`.
+  `Ktav.dumps` accepts a `Value.Arr` at the top level as well.
+- **`Ktav.toStringForceStrings(Value)`** — render any Value with every
+  leaf scalar (typed integers `:i`, typed floats `:f`, booleans, and
+  `null`) coerced to a String via the raw marker (`::`). Compounds
+  preserve their structure. Useful for "everything is a string"
+  dumps. Round-trips back through `loads` as the same set of String
+  scalars.
+
+### Changed
+
+- **Picked up `ktav 0.3.1`** — tracks ktav 0.3.1 (additive). Spec
+  submodule synced to `7256816` (spec 0.1.1).
+
+### Native binary cache
+
+- `NativeLoader.LIB_VERSION` bumped to `0.3.1`. Fresh download from the
+  matching GitHub Release on first call after upgrade.
+
+
 ## 0.3.0 — 2026-05-08
 
 ### Changed

Cargo.toml

@@ -3,14 +3,14 @@ resolver = "2"
 members = ["crates/cabi"]
 
 [workspace.package]
-version = "0.3.0"
+version = "0.3.1"
 edition = "2021"
 license = "MIT"
 repository = "https://github.com/ktav-lang/java"
 rust-version = "1.70"
 
 [workspace.dependencies]
-ktav = "0.3.0"
+ktav = "0.3.1"
 serde = { version = "1", features = ["derive"] }
 serde_json = { version = "1", features = ["preserve_order"] }
 indexmap = "2"

build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 
 allprojects {
     group = "io.github.ktav-lang"
-    version = "0.3.0"
+    version = "0.3.1"
 }
 
 subprojects {

crates/cabi/Cargo.toml

@@ -9,7 +9,7 @@ rust-version.workspace = true
 publish = false
 
 [package.metadata.ktav]
-spec-version = "0.1.0"
+spec-version = "0.1.1"
 
 [lib]
 name = "ktav_cabi"

crates/cabi/src/lib.rs

@@ -22,11 +22,12 @@
 //!
 //! ## C ABI
 //!
-//! Four functions, all use the same "caller-owned pointer, callee-owned
+//! Five functions, all use the same "caller-owned pointer, callee-owned
 //! buffer" pattern:
 //!
 //! - `ktav_loads(src, src_len, out_buf, out_len, out_err) -> i32`
 //! - `ktav_dumps(src, src_len, out_buf, out_len, out_err) -> i32`
+//! - `ktav_dumps_force_strings(src, src_len, out_buf, out_len, out_err) -> i32`
 //! - `ktav_free(ptr, len)` — free a buffer returned by loads/dumps.
 //! - `ktav_version()` — NUL-terminated static string, for sanity checks.
 //!
@@ -153,9 +154,9 @@ pub unsafe extern "C" fn ktav_dumps(
         }
     };
 
-    if !matches!(value, Value::Object(_)) {
+    if !matches!(value, Value::Object(_) | Value::Array(_)) {
         emit_err(
-            "top-level Ktav document must be an object".to_string(),
+            "top-level Ktav document must be an object or array".to_string(),
             out_err,
             out_err_len,
         );
@@ -174,6 +175,65 @@ pub unsafe extern "C" fn ktav_dumps(
     0
 }
 
+/// Render a JSON document to Ktav text, coercing every leaf scalar to a
+/// String (typed integers, typed floats, booleans, and `null` are
+/// flattened to their textual form via the `::` raw marker). Compounds
+/// preserve their structure. See `ktav::to_string_force_strings`.
+///
+/// # Safety
+/// Same as [`ktav_loads`].
+#[no_mangle]
+pub unsafe extern "C" fn ktav_dumps_force_strings(
+    src: *const u8,
+    src_len: usize,
+    out_buf: *mut *mut u8,
+    out_len: *mut usize,
+    out_err: *mut *mut c_char,
+    out_err_len: *mut usize,
+) -> c_int {
+    *out_buf = ptr::null_mut();
+    *out_len = 0;
+    *out_err = ptr::null_mut();
+    *out_err_len = 0;
+
+    let bytes = slice::from_raw_parts(src, src_len);
+    let wire: WireValue = match serde_json::from_slice(bytes) {
+        Ok(w) => w,
+        Err(e) => {
+            emit_err(format!("input JSON: {e}"), out_err, out_err_len);
+            return 1;
+        }
+    };
+
+    let value = match wire.into_value() {
+        Ok(v) => v,
+        Err(e) => {
+            emit_err(e, out_err, out_err_len);
+            return 1;
+        }
+    };
+
+    if !matches!(value, Value::Object(_) | Value::Array(_)) {
+        emit_err(
+            "top-level Ktav document must be an object or array".to_string(),
+            out_err,
+            out_err_len,
+        );
+        return 1;
+    }
+
+    let text = match ktav::to_string_force_strings(&value) {
+        Ok(s) => s,
+        Err(e) => {
+            emit_err(e.to_string(), out_err, out_err_len);
+            return 1;
+        }
+    };
+
+    emit(text.into_bytes(), out_buf, out_len);
+    0
+}
+
 /// Free a buffer returned by `ktav_loads` / `ktav_dumps` (success or
 /// error). `ptr`/`len` is a no-op when null/zero.
 ///

lib/src/main/java/lang/ktav/Ktav.java

@@ -45,8 +45,10 @@ public static Value loads(String src) {
 
     /**
      * Render a {@link Value} back to Ktav text. The top-level value must
-     * be a {@link Value.Obj} — other shapes are rejected by the native
-     * side. Throws {@link KtavException} on render error.
+     * be a {@link Value.Obj} or {@link Value.Arr} — other shapes are
+     * rejected by the native side. Top-level arrays are supported as of
+     * spec 0.1.1 (binding 0.3.1). Throws {@link KtavException} on render
+     * error.
      */
     public static String dumps(Value value) {
         if (value == null) {
@@ -57,6 +59,33 @@ public static String dumps(Value value) {
         return new String(output, StandardCharsets.UTF_8);
     }
 
+    /**
+     * Render a {@link Value} back to Ktav text with every leaf scalar
+     * coerced to a String. Typed integers ({@code :i}), typed floats
+     * ({@code :f}), booleans, and {@code null} are flattened to their
+     * textual form via the raw-marker ({@code ::}). Compounds (objects
+     * and arrays) preserve their structure; only leaf scalars are
+     * coerced. The output round-trips back through {@link #loads} as the
+     * same set of String scalars.
+     *
+     * <p>Useful for "everything is a string" dumps — e.g. for downstream
+     * consumers that don't understand typed markers, or for diff-friendly
+     * canonical text.
+     *
+     * <p>The top-level value must be a {@link Value.Obj} or
+     * {@link Value.Arr}. Throws {@link KtavException} on render error.
+     *
+     * @since 0.3.1
+     */
+    public static String toStringForceStrings(Value value) {
+        if (value == null) {
+            throw new NullPointerException("value");
+        }
+        byte[] input = WireJson.encode(value);
+        byte[] output = callNative(NativeOp.DUMPS_FORCE_STRINGS, input);
+        return new String(output, StandardCharsets.UTF_8);
+    }
+
     /**
      * Version of the loaded {@code ktav_cabi} native library. Useful for
      * sanity checks.
@@ -68,7 +97,8 @@ public static String nativeVersion() {
 
     private enum NativeOp {
         LOADS,
-        DUMPS
+        DUMPS,
+        DUMPS_FORCE_STRINGS
     }
 
     private static byte[] callNative(NativeOp op, byte[] input) {
@@ -96,6 +126,8 @@ private static byte[] callNative(NativeOp op, byte[] input) {
                         outBuf, outLen, outErr, outErrLen);
                 case DUMPS -> lib.ktav_dumps(srcPtr, input.length,
                         outBuf, outLen, outErr, outErrLen);
+                case DUMPS_FORCE_STRINGS -> lib.ktav_dumps_force_strings(srcPtr, input.length,
+                        outBuf, outLen, outErr, outErrLen);
             };
 
             if (rc != 0) {

lib/src/main/java/lang/ktav/internal/NativeLib.java

@@ -32,6 +32,14 @@ int ktav_dumps(
             PointerByReference outErr,
             LongByReference outErrLen);
 
+    int ktav_dumps_force_strings(
+            Pointer src,
+            long srcLen,
+            PointerByReference outBuf,
+            LongByReference outLen,
+            PointerByReference outErr,
+            LongByReference outErrLen);
+
     void ktav_free(Pointer ptr, long len);
 
     String ktav_version();

lib/src/main/java/lang/ktav/internal/NativeLoader.java

@@ -31,7 +31,7 @@
 public final class NativeLoader {
 
     /** Version of {@code ktav_cabi} this build expects. Bump per release. */
-    static final String LIB_VERSION = "0.1.2";
+    static final String LIB_VERSION = "0.3.1";
 
     private static final String RELEASE_BASE =
             "https://github.com/ktav-lang/java/releases/download/v";

lib/src/test/java/lang/ktav/SmokeTest.java

@@ -102,9 +102,104 @@ void parseErrorThrows() {
     }
 
     @Test
-    void dumpsRejectsNonObjectTopLevel() {
-        Value arr = new Value.Arr(List.of(new Value.Str("x")));
-        assertThrows(KtavException.class, () -> Ktav.dumps(arr));
+    void dumpsRejectsScalarTopLevel() {
+        // Top-level Array is now valid (spec 0.1.1) — only bare scalars
+        // are still rejected by the native side.
+        assertThrows(KtavException.class, () -> Ktav.dumps(new Value.Str("just a string")));
+    }
+
+    @Test
+    void loadsTopLevelArrayBareScalars() {
+        // spec 0.1.1: first content line decides Object vs Array.
+        String src = """
+                alpha
+                beta
+                gamma
+                """;
+        Value v = Ktav.loads(src);
+        Value.Arr arr = assertInstanceOf(Value.Arr.class, v);
+        assertEquals(List.of(
+                new Value.Str("alpha"),
+                new Value.Str("beta"),
+                new Value.Str("gamma")), arr.items());
+    }
+
+    @Test
+    void loadsTopLevelArrayTypedItems() {
+        String src = """
+                :i 1
+                :i 2
+                :f 3.5
+                """;
+        Value v = Ktav.loads(src);
+        Value.Arr arr = assertInstanceOf(Value.Arr.class, v);
+        assertEquals(3, arr.items().size());
+        assertEquals(new Value.Int("1"), arr.items().get(0));
+        assertEquals(new Value.Int("2"), arr.items().get(1));
+        Value.Flt third = assertInstanceOf(Value.Flt.class, arr.items().get(2));
+        assertEquals(3.5, third.toDouble());
+    }
+
+    @Test
+    void roundTripTopLevelArray() {
+        Value.Arr arr = new Value.Arr(List.of(
+                new Value.Str("one"),
+                new Value.Str("two"),
+                Value.Int.of(3)));
+        String out = Ktav.dumps(arr);
+        assertNotNull(out);
+        Value back = Ktav.loads(out);
+        Value.Arr bArr = assertInstanceOf(Value.Arr.class, back);
+        assertEquals(3, bArr.items().size());
+        assertEquals(new Value.Str("one"), bArr.items().get(0));
+        assertEquals(new Value.Str("two"), bArr.items().get(1));
+        assertEquals(new Value.Int("3"), bArr.items().get(2));
+    }
+
+    @Test
+    void toStringForceStringsCoercesScalars() {
+        LinkedHashMap<String, Value> entries = new LinkedHashMap<>();
+        entries.put("count", Value.Int.of(42));
+        entries.put("ratio", Value.Flt.of(0.5));
+        entries.put("flag", Value.Bool.TRUE);
+        entries.put("nothing", Value.Null.NULL);
+        entries.put("name", new Value.Str("demo"));
+
+        String out = Ktav.toStringForceStrings(new Value.Obj(entries));
+        assertNotNull(out);
+
+        // Round-trip — every leaf scalar must come back as Value.Str.
+        Value back = Ktav.loads(out);
+        Value.Obj b = assertInstanceOf(Value.Obj.class, back);
+        assertInstanceOf(Value.Str.class, b.entries().get("count"));
+        assertInstanceOf(Value.Str.class, b.entries().get("ratio"));
+        assertInstanceOf(Value.Str.class, b.entries().get("flag"));
+        assertInstanceOf(Value.Str.class, b.entries().get("nothing"));
+        assertInstanceOf(Value.Str.class, b.entries().get("name"));
+
+        assertEquals(new Value.Str("42"), b.entries().get("count"));
+        assertEquals("true", ((Value.Str) b.entries().get("flag")).value());
+        assertEquals("null", ((Value.Str) b.entries().get("nothing")).value());
+        assertEquals("demo", ((Value.Str) b.entries().get("name")).value());
+    }
+
+    @Test
+    void toStringForceStringsAcceptsTopLevelArray() {
+        Value.Arr arr = new Value.Arr(List.of(
+                Value.Int.of(1),
+                Value.Bool.FALSE,
+                Value.Null.NULL));
+        String out = Ktav.toStringForceStrings(arr);
+        assertNotNull(out);
+        Value back = Ktav.loads(out);
+        Value.Arr bArr = assertInstanceOf(Value.Arr.class, back);
+        assertEquals(3, bArr.items().size());
+        for (Value item : bArr.items()) {
+            assertInstanceOf(Value.Str.class, item);
+        }
+        assertEquals("1", ((Value.Str) bArr.items().get(0)).value());
+        assertEquals("false", ((Value.Str) bArr.items().get(1)).value());
+        assertEquals("null", ((Value.Str) bArr.items().get(2)).value());
     }
 
     @Test