refactor(value): migrate Array storage abstraction (#785)

* feat(value): introduce Array storage abstraction

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

docs(value): document Array storage abstraction

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9ac07e53-88fc-4050-bd56-c0d9761b911b

* refactor(value): migrate Array storage abstraction

Wire Value::Array to the opaque Array wrapper and update all call sites to use explicit APIs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9ac07e53-88fc-4050-bd56-c0d9761b911b

---------

Copilot-Session: 9ac07e53-88fc-4050-bd56-c0d9761b911b

Author: anakrish

bindings/wasm/src/lib.rs

@@ -523,7 +523,8 @@ mod tests {
         assert_eq!(
             r["files"][0]["covered"]
                 .as_array()
-                .map_err(crate::error_to_jsvalue)?,
+                .map_err(crate::error_to_jsvalue)?
+                .as_slice(),
             &vec![regorus::Value::from(3)]
         );
 

docs/value/array.md

@@ -0,0 +1,33 @@
+# Array
+
+Opaque container for `Value::Array`'s ordered element storage, enabling
+alternative backends without call-site changes. It follows the same
+abstraction pattern as [`Object`](object.md) and [`Set`](set.md).
+
+## Design
+
+`Array` wraps a `Vec<Value>` today but exposes only a curated method surface
+(`get`, `get_mut`, `first`, `last`, `contains`, `iter`, `iter_mut`, `push`,
+`append`, `extend`, `extend_from_slice`, `retain`, `clear`, `reverse`, `sort`,
+`cursor`, and serde). The inner vector is private, and `Array` does not
+implement `Deref`, so callers cannot depend on the backing representation.
+
+Indexing uses `Index<usize>` and returns `Value::Undefined` for an out-of-range
+index, matching `Value` indexing semantics. Use `get` when distinguishing a
+missing element from an element whose value is explicitly `Undefined`.
+
+Iteration follows sequence order. The opaque cursor supports incremental
+traversal needed by RVM iteration state without exposing iterator internals.
+`Ord` is implemented against the sequence iterator so alternative backends can
+preserve the current array comparison behavior.
+
+## Scenarios enabled
+
+- **Inline-small storage** — store short arrays inline and spill to the heap
+  only for larger values.
+- **Lazy/streaming storage** — materialize elements from JSON, CBOR, or a host
+  provider on demand.
+- **Arena allocation** — use bump allocation for evaluation-time temporaries
+  and release them together at query end.
+- **FFI-backed storage** — access host-language lists or arrays without
+  copying at every binding boundary.

src/builtins/arrays.rs

@@ -65,6 +65,6 @@ fn slice(span: &Span, params: &[Ref<Expr>], args: &[Value], _strict: bool) -> Re
         return Ok(Value::new_array());
     }
 
-    let slice = &array[start..stop];
+    let slice = array.as_slice().get(start..stop).unwrap_or_default();
     Ok(Value::from(slice.to_vec()))
 }

src/builtins/azure_policy/template_functions_collection.rs

@@ -59,7 +59,7 @@ fn fn_intersection(
     match *first {
         Value::Array(ref first) => {
             // Intersection of arrays: keep elements from first that appear in all others.
-            let mut result: Vec<Value> = first.as_ref().clone();
+            let mut result: Vec<Value> = first.as_slice().to_vec();
             for arg in rest {
                 let Value::Array(ref other) = *arg else {
                     return Ok(Value::Undefined);
@@ -149,7 +149,9 @@ fn fn_take(_span: &Span, _params: &[Ref<Expr>], args: &[Value], _strict: bool) -
     match *original {
         Value::Array(ref arr) => {
             let n = count.min(arr.len());
-            Ok(Value::from(arr.get(..n).unwrap_or_default().to_vec()))
+            Ok(Value::from(
+                arr.as_slice().get(..n).unwrap_or_default().to_vec(),
+            ))
         }
         Value::String(ref s) => {
             let taken: alloc::string::String = s.chars().take(count).collect();
@@ -172,7 +174,9 @@ fn fn_skip(_span: &Span, _params: &[Ref<Expr>], args: &[Value], _strict: bool) -
     match *original {
         Value::Array(ref arr) => {
             let n = count.min(arr.len());
-            Ok(Value::from(arr.get(n..).unwrap_or_default().to_vec()))
+            Ok(Value::from(
+                arr.as_slice().get(n..).unwrap_or_default().to_vec(),
+            ))
         }
         Value::String(ref s) => {
             let skipped: alloc::string::String = s.chars().skip(count).collect();

src/builtins/azure_policy/template_functions_misc.rs

@@ -90,7 +90,7 @@ fn fn_items(_span: &Span, _params: &[Ref<Expr>], args: &[Value], _strict: bool)
         entry.insert(Value::from("value"), v.clone());
         result.push(Value::Object(Rc::new(entry)));
     }
-    Ok(Value::Array(Rc::new(result)))
+    Ok(Value::from_array(result))
 }
 
 // ── indexFromEnd ──────────────────────────────────────────────────────

src/builtins/json_patch.rs

@@ -79,7 +79,7 @@ impl EditNode {
                     array.push(value.render()?);
                     enforce_limit()?;
                 }
-                Value::Array(crate::Rc::new(array))
+                Value::Array(crate::Rc::new(crate::value::Array::from(array)))
             }
             Self::Set(members) => {
                 let mut set = BTreeSet::new();

src/builtins/net.rs

@@ -153,7 +153,7 @@ fn _cidr_expand(cidr: Arc<str>) -> Result<Value> {
         enforce_limit()?;
     }
 
-    Ok(Value::Array(Arc::from(hosts)))
+    Ok(Value::from_array(hosts))
 }
 
 #[cfg(test)]

src/builtins/objects.rs

@@ -354,7 +354,10 @@ fn is_subset(sup: &Value, sub: &Value) -> bool {
             })
         }
         (Value::Set(sup), Value::Set(sub)) => sub.is_subset(sup),
-        (Value::Array(sup), Value::Array(sub)) => sup.windows(sub.len()).any(|w| w == &sub[..]),
+        (Value::Array(sup), Value::Array(sub)) => sup
+            .as_slice()
+            .windows(sub.len())
+            .any(|w| w == sub.as_slice()),
         (Value::Array(sup), Value::Set(_)) => {
             let sup = Value::from_set(sup.iter().cloned().collect());
             is_subset(&sup, sub)
@@ -504,7 +507,7 @@ fn json_patch(span: &Span, params: &[Ref<Expr>], args: &[Value], _strict: bool)
 
     let ops = args[1].as_array()?;
 
-    let patched = super::json_patch::apply(&args[0], ops);
+    let patched = super::json_patch::apply(&args[0], ops.as_slice());
     match patched {
         Ok(patched) => Ok(patched),
         // Resource-limit errors must propagate rather than look like an

src/builtins/utils.rs

@@ -5,7 +5,7 @@
 use crate::ast::{Expr, Ref};
 use crate::lexer::Span;
 use crate::number::Number;
-use crate::value::{Object, Set};
+use crate::value::{Array, Object, Set};
 use crate::Rc;
 use crate::Value;
 use crate::*;
@@ -147,7 +147,7 @@ pub fn ensure_string_collection<'a>(fcn: &str, arg: &Expr, v: &'a Value) -> Resu
     Ok(collection)
 }
 
-pub fn ensure_array(fcn: &str, arg: &Expr, v: Value) -> Result<Rc<Vec<Value>>> {
+pub fn ensure_array(fcn: &str, arg: &Expr, v: Value) -> Result<Rc<Array>> {
     Ok(match v {
         Value::Array(a) => a,
         _ => {

src/interpreter.rs

@@ -3918,7 +3918,7 @@ impl Interpreter {
                         if value != Value::Undefined {
                             for (path, value_in_map) in value.as_object()? {
                                 let mut full_path = package_components.clone();
-                                full_path.append(&mut path.as_array()?.clone());
+                                full_path.append(&mut path.as_array()?.to_vec());
                                 self.check_rule_path(refr, &full_path, value_in_map, is_set)?;
                                 self.update_rule_value(
                                     span,