Split core package; align root API; tighten Fixed buffer semantics

Author: Milky2018

.beads/issues.jsonl

@@ -6,9 +6,11 @@ Pinned upstream reference: see `UPSTREAM.md`.
 
 ## Status
 
-- `Milky2018/moon_cpal`: core CPAL-like types (configs, heuristics, timestamps, sample helpers).
-- `Milky2018/moon_cpal/spec`: CPAL-like host/device/stream API backed by `platform` dynamic dispatch.
-- `Milky2018/moon_cpal/traits`: CPAL-like `HostTrait`/`DeviceTrait`/`StreamTrait` implemented for `spec`.
+- `Milky2018/moon_cpal`: public CPAL-like API (native-only): host/device/stream + core type re-exports.
+- `Milky2018/moon_cpal/core`: pure core types/errors (configs, heuristics, timestamps, sample helpers).
+- `Milky2018/moon_cpal/platform`: dynamic dispatch host/device/stream (backend selection).
+- `Milky2018/moon_cpal/spec`: root API implementation backed by `platform`.
+- `Milky2018/moon_cpal/traits`: CPAL-like `HostTrait`/`DeviceTrait`/`StreamTrait` implemented for the root types.
 - Native backends (real I/O, callback-thread model):
   - macOS: CoreAudio (AudioQueue)
   - Linux: ALSA + JACK

README.mbt.md

@@ -25,7 +25,7 @@ MoonBit port.
 
 Top-level:
 
-- `lib.rs` — **PARTIAL** (core types + some heuristics/tests exist; high-level host API lives in `spec`)
+- `lib.rs` — **PARTIAL** (root API now re-exports platform + core via `core/` split; remaining: iterator-style APIs + docs)
 - `traits.rs` — **PARTIAL** (MoonBit `traits` package exists; iterator-associated types pending)
 - `error.rs` — **DONE** (Display-equivalent `to_string` parity + tests)
 - `device_description.rs` — **DONE** (`direction_from_counts` parity + tests)

UPSTREAM_PARITY.md

@@ -1,6 +1,6 @@
 ///|
 test "alsa default config matches supported configs (best-effort)" {
-  if @moon_cpal.native_os() != @moon_cpal.NativeOs::Linux {
+  if @core.native_os() != @core.NativeOs::Linux {
     inspect(true, content="true")
     return
   }
@@ -44,7 +44,7 @@ test "alsa default config matches supported configs (best-effort)" {
 
 ///|
 test "alsa supported configs include sane buffer size ranges (best-effort)" {
-  if @moon_cpal.native_os() != @moon_cpal.NativeOs::Linux {
+  if @core.native_os() != @core.NativeOs::Linux {
     inspect(true, content="true")
     return
   }

alsa/alsa_config_test.mbt

@@ -1,6 +1,6 @@
 ///|
 test "alsa: devices includes default (linux-only)" {
-  if @moon_cpal.native_os() != @moon_cpal.NativeOs::Linux {
+  if @core.native_os() != @core.NativeOs::Linux {
     return
   }
   let h = default_host()
@@ -18,7 +18,7 @@ test "alsa: devices includes default (linux-only)" {
 
 ///|
 test "alsa: default devices are always Some (linux-only)" {
-  if @moon_cpal.native_os() != @moon_cpal.NativeOs::Linux {
+  if @core.native_os() != @core.NativeOs::Linux {
     inspect(true, content="true")
     return
   }

alsa/alsa_enumerate_test.mbt

@@ -1,6 +1,6 @@
 ///|
-test "alsa fixed buffer 0 is invalid argument (best-effort)" {
-  if @moon_cpal.native_os() != @moon_cpal.NativeOs::Linux {
+test "alsa fixed buffer 0 is stream_config_not_supported (best-effort)" {
+  if @core.native_os() != @core.NativeOs::Linux {
     inspect(true, content="true")
     return
   }
@@ -16,10 +16,10 @@ test "alsa fixed buffer 0 is invalid argument (best-effort)" {
       } noraise {
         x => x
       }
-      let sc = @moon_cpal.StreamConfig::new(
+      let sc = @core.StreamConfig::new(
         cfg.channels(),
         cfg.sample_rate(),
-        @moon_cpal.BufferSize::fixed(0),
+        @core.BufferSize::fixed(0),
       )
       try
         dev.build_output_stream_raw(
@@ -32,7 +32,7 @@ test "alsa fixed buffer 0 is invalid argument (best-effort)" {
       catch {
         e =>
           match e {
-            @moon_cpal.BuildStreamError::InvalidArgument =>
+            @core.BuildStreamError::StreamConfigNotSupported =>
               inspect(true, content="true")
             _ => inspect(false, content="true")
           }
@@ -48,7 +48,7 @@ test "alsa fixed buffer 0 is invalid argument (best-effort)" {
 
 ///|
 test "alsa fixed buffer larger than supported range fails (best-effort)" {
-  if @moon_cpal.native_os() != @moon_cpal.NativeOs::Linux {
+  if @core.native_os() != @core.NativeOs::Linux {
     inspect(true, content="true")
     return
   }
@@ -64,11 +64,23 @@ test "alsa fixed buffer larger than supported range fails (best-effort)" {
       } noraise {
         x => x
       }
-      let big = 1000000000
-      let sc = @moon_cpal.StreamConfig::new(
+      let max_buf = match cfg.buffer_size() {
+        @core.SupportedBufferSize::Unknown => {
+          inspect(true, content="true")
+          return
+        }
+        @core.SupportedBufferSize::Range(max=mx, ..) => mx
+      }
+      // Avoid overflow when buffer size is effectively unbounded.
+      if max_buf >= 2147483647 {
+        inspect(true, content="true")
+        return
+      }
+      let want = max_buf + 1
+      let sc = @core.StreamConfig::new(
         cfg.channels(),
         cfg.sample_rate(),
-        @moon_cpal.BufferSize::fixed(big),
+        @core.BufferSize::fixed(want),
       )
       let got = try
         dev.build_output_stream_raw(
@@ -79,7 +91,11 @@ test "alsa fixed buffer larger than supported range fails (best-effort)" {
           None,
         )
       catch {
-        _ => None
+        e =>
+          match e {
+            @core.BuildStreamError::StreamConfigNotSupported => None
+            _ => None
+          }
       } noraise {
         s => Some(s)
       }

alsa/buffer_fixed_semantics_wbtest.mbt

@@ -1,11 +1,11 @@
 ///|
 test "alsa callback timestamps + format tags" {
-  let want_cb = @moon_cpal.StreamInstant::new(1, 2)
-  let want_pb = @moon_cpal.StreamInstant::new(3, 4)
+  let want_cb = @core.StreamInstant::new(1, 2)
+  let want_pb = @core.StreamInstant::new(3, 4)
   let got = FixedArray::make(3, false)
   call_output_data_callback(
     fn(d, info) {
-      got[0] = d.sample_format() == @moon_cpal.SampleFormat::F32
+      got[0] = d.sample_format() == @core.SampleFormat::F32
       got[1] = info.timestamp().callback() == want_cb
       got[2] = info.timestamp().playback() == want_pb
     },
@@ -19,12 +19,12 @@ test "alsa callback timestamps + format tags" {
   inspect(got[0], content="true")
   inspect(got[1], content="true")
   inspect(got[2], content="true")
-  let want_cb2 = @moon_cpal.StreamInstant::new(5, 6)
-  let want_cap = @moon_cpal.StreamInstant::new(7, 8)
+  let want_cb2 = @core.StreamInstant::new(5, 6)
+  let want_cap = @core.StreamInstant::new(7, 8)
   let got2 = FixedArray::make(3, false)
   call_input_data_callback(
     fn(d, info) {
-      got2[0] = d.sample_format() == @moon_cpal.SampleFormat::I16
+      got2[0] = d.sample_format() == @core.SampleFormat::I16
       got2[1] = info.timestamp().callback() == want_cb2
       got2[2] = info.timestamp().capture() == want_cap
     },

alsa/callback_timing_wbtest.mbt

@@ -1,6 +1,6 @@
 ///|
 test "alsa errno mapping (unit)" {
-  if @moon_cpal.native_os() != @moon_cpal.NativeOs::Linux {
+  if @core.native_os() != @core.NativeOs::Linux {
     inspect(true, content="true")
     return
   }

alsa/error_mapping_wbtest.mbt

@@ -58,28 +58,28 @@ pub fn device_name_utf8(id : String) -> String? {
   if id.length() == 0 {
     return None
   }
-  let b1 = @moon_cpal.string_to_utf8_bytes(id)
+  let b1 = @core.string_to_utf8_bytes(id)
   let id_len = b1.length()
   let n = alsa_device_name_utf8_len(b1, id_len)
   if n <= 0 {
     return None
   }
   let out = Bytes::make(n, (0 : Int).to_byte())
-  let b2 = @moon_cpal.string_to_utf8_bytes(id)
+  let b2 = @core.string_to_utf8_bytes(id)
   let used = alsa_device_name_utf8(b2, id_len, out, out.length())
   if used <= 0 {
     return None
   }
   let need = if used > out.length() { out.length() } else { used }
-  Some(@moon_cpal.utf8_bytes_to_string(out, need))
+  Some(@core.utf8_bytes_to_string(out, need))
 }
 
 ///|
 pub fn supported_configs_bin(id : String, is_input : Bool) -> Bytes {
   if id.length() == 0 {
     return Bytes::make(0, (0 : Int).to_byte())
   }
-  let b = @moon_cpal.string_to_ascii_bytes(id)
+  let b = @core.string_to_ascii_bytes(id)
   alsa_supported_configs_bin(
     b,
     b.length(),