feat(value): introduce Array storage abstraction

Add an opaque `Array` newtype paralleling `Object`, living under
`src/value/array/` with the same module structure (`mod.rs` /
`iter.rs` / `serde.rs`). `Array` wraps `Vec<Value>` today but exposes
only a curated surface: constructors, indexed access, push/pop/insert/
remove/truncate/sort/dedup/reverse, iteration, serde, conversion to
`Value`, and a hand-written lexicographic `Ord`. The cursor type is
re-exported behind the `rvm` feature so the follow-up
`IterationState::Array` swap can land additively.

No crate-root `Array` re-export is added; the new type lives under
`regorus::value::Array`, matching the storage-abstraction namespace
strategy for `Object` and `Set`.

`Value::Array` is unchanged in this commit (still wraps
`Rc<Vec<Value>>`); the payload swap and call-site migration ship in the
next PR.

Also repair pre-existing doctest examples that `cargo test --doc
--all-features` exercises, so the required validation suite passes with
this branch.

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

Author: anakrish

docs/value/array.md

@@ -0,0 +1,35 @@
+# Array
+
+Opaque container for `Value::Array`'s element storage, enabling alternative
+backends without call-site changes. Pairs with [`Object`](object.md) under a
+shared design philosophy.
+
+## Design
+
+`Array` wraps a `Vec<Value>` today but exposes only a curated method surface
+(`get`, `get_mut`, `push`, `pop`, `insert`, `remove`, `iter`, `iter_mut`,
+`cursor`, serde). The inner vector is private — callers cannot pattern-match it
+or hand out mutable references to the backing store, so the backend can change
+without churn at call sites that currently assume `Vec<Value>`.
+
+Iteration follows sequence order. Cursor types support incremental traversal
+needed by the RVM iteration state without exposing iterator internals.
+
+`Ord` is hand-written against the sequence iterator rather than derived from the
+storage, so future backends compare exactly like today's `Vec<Value>` payload.
+
+## Scenarios enabled
+
+- **Inline-small storage** — store short arrays inline and spill to heap only for
+  larger values.
+- **Lazy/streaming** — wrap a provider over JSON/CBOR/host data and materialize
+  elements on demand.
+- **Arena allocation** — bumpalo-backed arrays for eval-time temporaries; drop
+  the whole arena at query end with zero per-element free cost.
+- **FFI-backed** — host-language lists or arrays without copying into Rust on
+  every binding boundary.
+
+## Notes
+
+`Value::Array` is not migrated by the foundation PR that introduces this type;
+it still wraps `Rc<Vec<Value>>` until the follow-up migration.

src/compiled_policy.rs

@@ -96,7 +96,8 @@ impl CompiledPolicy {
     /// # // Register a target for the example
     /// # #[cfg(feature = "azure_policy")]
     /// # {
-    /// #    let target = regorus::target::Target::from_json_file("tests/interpreter/cases/target/definitions/sample_target.json")?;
+    /// #    let target_json = std::fs::read_to_string("tests/interpreter/cases/target/definitions/sample_target.json")?;
+    /// #    let target = regorus::target::Target::from_json_str(&target_json)?;
     /// #    regorus::registry::targets::register(std::sync::Arc::new(target))?;
     /// # }
     ///

src/engine.rs

@@ -1402,7 +1402,7 @@ impl Engine {
     /// let ast = engine.get_ast_as_json()?;
     /// let value = Value::from_json_str(&ast)?;
     ///
-    /// assert_eq!(value[0]["ast"]["package"]["refr"]["Var"][1].as_string()?.as_ref(), "test");
+    /// assert_eq!(value[0]["ast"]["package"]["refr"]["Var"]["value"].as_string()?.as_ref(), "test");
     /// # Ok(())
     /// # }
     /// ```

src/schema.rs

@@ -216,6 +216,7 @@ pub mod validate;
 /// Schemas are typically created by deserializing from JSON Schema format:
 ///
 /// ```rust
+/// use regorus::Schema;
 /// use serde_json::json;
 ///
 /// // Create a schema from JSON
@@ -255,12 +256,18 @@ pub mod validate;
 ///
 /// ## Simple String Schema
 /// ```rust
+/// use regorus::Schema;
+/// use serde_json::json;
+///
 /// let schema = json!({ "type": "string", "minLength": 1 });
 /// let parsed: Schema = serde_json::from_value(schema).unwrap();
 /// ```
 ///
 /// ## Complex Object Schema
 /// ```rust
+/// use regorus::Schema;
+/// use serde_json::json;
+///
 /// let schema = json!({
 ///     "type": "object",
 ///     "properties": {
@@ -282,6 +289,9 @@ pub mod validate;
 ///
 /// ## Union Types with anyOf
 /// ```rust
+/// use regorus::Schema;
+/// use serde_json::json;
+///
 /// let schema = json!({
 ///     "anyOf": [
 ///         { "type": "string" },
@@ -337,8 +347,7 @@ impl Schema {
     ///
     /// # Example
     /// ```rust
-    /// use regorus::schema::Schema;
-    /// use regorus::Value;
+    /// use regorus::{Schema, Value};
     /// use serde_json::json;
     ///
     /// let schema_json = json!({

src/schema/validate.rs

@@ -31,8 +31,7 @@ impl SchemaValidator {
     ///
     /// # Example
     /// ```rust
-    /// use regorus::schema::{Schema, validate::SchemaValidator};
-    /// use regorus::Value;
+    /// use regorus::{Schema, SchemaValidator, Value};
     /// use serde_json::json;
     ///
     /// let schema_json = json!({

src/value/array/iter.rs

@@ -0,0 +1,168 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! Opaque iterator types for [`Array`].
+//!
+//! These newtypes wrap the storage backend's iterators so the backend can be
+//! swapped without changing any iterator type signatures observed by callers.
+
+use alloc::vec;
+use core::iter::FusedIterator;
+use core::slice;
+
+use super::Array;
+use crate::value::Value;
+
+/// Owned iterator over `Value` elements.
+#[derive(Debug)]
+pub struct IntoIter {
+    pub(super) inner: vec::IntoIter<Value>,
+}
+
+impl Iterator for IntoIter {
+    type Item = Value;
+
+    #[inline]
+    fn next(&mut self) -> Option<Self::Item> {
+        self.inner.next()
+    }
+
+    #[inline]
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.inner.size_hint()
+    }
+}
+
+impl DoubleEndedIterator for IntoIter {
+    #[inline]
+    fn next_back(&mut self) -> Option<Self::Item> {
+        self.inner.next_back()
+    }
+}
+
+impl ExactSizeIterator for IntoIter {
+    #[inline]
+    fn len(&self) -> usize {
+        self.inner.len()
+    }
+}
+
+impl FusedIterator for IntoIter {}
+
+/// Borrowed iterator over `&Value` elements.
+#[derive(Debug, Clone)]
+pub struct Iter<'a> {
+    pub(super) inner: slice::Iter<'a, Value>,
+}
+
+impl<'a> Iterator for Iter<'a> {
+    type Item = &'a Value;
+
+    #[inline]
+    fn next(&mut self) -> Option<Self::Item> {
+        self.inner.next()
+    }
+
+    #[inline]
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.inner.size_hint()
+    }
+}
+
+impl<'a> DoubleEndedIterator for Iter<'a> {
+    #[inline]
+    fn next_back(&mut self) -> Option<Self::Item> {
+        self.inner.next_back()
+    }
+}
+
+impl<'a> ExactSizeIterator for Iter<'a> {
+    #[inline]
+    fn len(&self) -> usize {
+        self.inner.len()
+    }
+}
+
+impl<'a> FusedIterator for Iter<'a> {}
+
+/// Mutable borrowed iterator over `&mut Value` elements.
+#[derive(Debug)]
+pub struct IterMut<'a> {
+    pub(super) inner: slice::IterMut<'a, Value>,
+}
+
+impl<'a> Iterator for IterMut<'a> {
+    type Item = &'a mut Value;
+
+    #[inline]
+    fn next(&mut self) -> Option<Self::Item> {
+        self.inner.next()
+    }
+
+    #[inline]
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.inner.size_hint()
+    }
+}
+
+impl<'a> DoubleEndedIterator for IterMut<'a> {
+    #[inline]
+    fn next_back(&mut self) -> Option<Self::Item> {
+        self.inner.next_back()
+    }
+}
+
+impl<'a> ExactSizeIterator for IterMut<'a> {
+    #[inline]
+    fn len(&self) -> usize {
+        self.inner.len()
+    }
+}
+
+impl<'a> FusedIterator for IterMut<'a> {}
+
+/// Opaque resumable cursor over an [`Array`]'s elements.
+///
+/// Self-owned: holds no borrow on the `Array`, so it can be stored as a field
+/// of a long-lived state struct (e.g. an RVM iteration frame).
+#[cfg(feature = "rvm")]
+#[derive(Debug, Clone, Default)]
+pub struct Cursor {
+    pub(super) next: usize,
+}
+
+impl IntoIterator for Array {
+    type Item = Value;
+    type IntoIter = IntoIter;
+
+    #[inline]
+    fn into_iter(self) -> Self::IntoIter {
+        IntoIter {
+            inner: self.inner.into_iter(),
+        }
+    }
+}
+
+impl<'a> IntoIterator for &'a Array {
+    type Item = &'a Value;
+    type IntoIter = Iter<'a>;
+
+    #[inline]
+    fn into_iter(self) -> Self::IntoIter {
+        Iter {
+            inner: self.inner.iter(),
+        }
+    }
+}
+
+impl<'a> IntoIterator for &'a mut Array {
+    type Item = &'a mut Value;
+    type IntoIter = IterMut<'a>;
+
+    #[inline]
+    fn into_iter(self) -> Self::IntoIter {
+        IterMut {
+            inner: self.inner.iter_mut(),
+        }
+    }
+}