Introduce Object storage abstraction

Add an opaque Object type for the key→value storage backing
Value::Object. It exposes a small set of methods (get, insert, remove,
iter, iter_sorted, cursor, serde) and keeps the backing store private,
so future representations -- inline small-map, hash-backed, lazy,
arena, FFI-callback -- can plug in without touching the call sites
that name this type.

Nothing in the engine uses Object yet. Value::Object still wraps
Rc<BTreeMap<Value, Value>>; the payload swap and call-site migration
come in the next PR. Object stands on its own unit tests in the
meantime.

docs/value/object.md walks through the design, the precedents it
follows (serde_json::Map, toml::Table, simdjson DOM), and the
concrete workloads the abstraction is meant to unlock.

A matching Set abstraction follows in a separate PR.

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

Author: anakrish

docs/value/object.md

@@ -0,0 +1,84 @@
+# Object
+
+Opaque container for `Value::Object`'s key→value storage, enabling
+alternative backends without call-site changes.
+
+## Design
+
+`Object` wraps the storage for a key→value collection of `Value`s and
+provides a curated set of methods (`get`, `insert`, `remove`, `iter`,
+`iter_sorted`, `cursor`, serde). The backing store is private; callers
+never see or pattern-match on it, so the representation can change
+without rippling through call sites.
+
+Multiple backends can coexist at runtime. Because the backing store is
+private, different `Object` instances in the same process can use
+different implementations — e.g., a lazy DB-backed object for `input`,
+inline small-map objects for SARIF location records, and a regular
+sorted map elsewhere — all interoperating through the same opaque
+type. This is stronger than the typical Cargo-feature-selected backend
+seen in precedent crates.
+
+Iteration is split intentionally. `iter()` makes no ordering promise,
+which lets backends that don't keep entries sorted skip any sort work.
+`iter_sorted()` returns entries in `Value` order and is what
+serialization and `Ord` rely on for deterministic output. Cursor types
+add resumable, incremental traversal for the RVM iteration state
+without leaking iterator internals.
+
+`Ord` and `PartialOrd` are defined against `iter_sorted()` rather than
+derived from the storage. Two `Object`s built on different backends —
+or with different insertion histories — compare equal whenever their
+sorted entries match, so changing the backend never changes observable
+comparison results.
+
+## Precedents
+
+Other crates that hide storage behind a stable API so the implementation
+can change without breaking callers:
+
+- **`serde_json::Map`** — opaque newtype allowing cargo-feature based
+  swap between `BTreeMap` (canonical order) and `IndexMap` (insertion
+  order).
+- **`toml::Table`** — opaque newtype allowing cargo-feature based swap
+  between `BTreeMap` and `IndexMap`.
+- **`simdjson` DOM** — opaque tree that lazily materializes nodes on
+  access instead of parsing the whole document up front.
+
+## Use cases
+
+- **SARIF small-object pressure** — SARIF reports contain millions of
+  small objects (location records, rule references, message arguments),
+  most with 2-5 keys. A small-map-optimized backend (inline storage
+  for ≤N entries, heap above) eliminates per-object BTreeMap allocation
+  for the common case.
+
+- **Kubernetes admission policies** — large, deeply-nested resource
+  objects (Pod specs, CRDs) where policies typically touch a handful
+  of paths. A lazy-materializing backend (`LazyObjectProvider` over
+  the incoming JSON) parses only the accessed subtrees.
+
+- **Azure Policy aliases** — ARM exposes the same logical property
+  under multiple aliases (e.g. paths like
+  `Microsoft.Compute/virtualMachines/storageProfile.osDisk.managedDisk.id`).
+  An alias-aware backend resolves lookups across canonical and alias
+  forms without rewriting every policy.
+
+- **Azure Policy case-insensitive compare** — ARM property names are
+  case-preserving but case-insensitive on lookup (`tags.Environment`
+  and `tags.environment` resolve identically). A case-insensitive
+  backend centralizes this once at the storage layer instead of at
+  every comparison site.
+
+- **External data sources** — `input` or `data` backed by a database
+  query, CBOR slice, REST endpoint, or other streaming source via a
+  `LazyObjectProvider`. Entries materialize on demand; the policy
+  only pays for what it touches.
+
+- **Eval-time temporaries** — objects constructed during evaluation
+  (comprehensions, intermediate rule results) on a bumpalo arena.
+  The whole arena drops at query end with zero per-entry free cost.
+
+- **Host-language interop** — Python dicts or JS objects accessed via
+  FFI callbacks from the embedding application, without copying into
+  Rust on every binding boundary.

src/lib.rs

@@ -177,7 +177,7 @@ pub use utils::limits::{
     global_memory_limit, set_global_memory_limit, set_thread_flush_threshold_override,
     thread_memory_flush_threshold,
 };
-pub use value::Value;
+pub use value::{Object, Value};
 
 /// Compiled-pattern caches for the `regex.*` and `glob.*` Rego builtins.
 ///

src/scheduler.rs

@@ -569,7 +569,7 @@ impl Analyzer {
                         }
                         Ok(false)
                     }
-                    Array { .. } | Object { .. } => Ok(true),
+                    Expr::Array { .. } | Expr::Object { .. } => Ok(true),
                     _ => Ok(false),
                 })?;
                 Ok(true)
@@ -666,7 +666,7 @@ impl Analyzer {
                 Ok(false)
             }
             // TODO: key vs value for object binding
-            Array { .. } | Object { .. } => Ok(true),
+            Expr::Array { .. } | Expr::Object { .. } => Ok(true),
             _ => Ok(false),
         })?;
         Ok(vars)
@@ -853,7 +853,7 @@ impl Analyzer {
                 Ok(false)
             }
             // TODO: Object key/value
-            Array { .. } | Object { .. } => Ok(true),
+            Expr::Array { .. } | Expr::Object { .. } => Ok(true),
             _ => {
                 non_vars.push(e.clone());
                 Ok(false)

src/value.rs src/value/mod.rssrc/value.rs renamed to src/value/mod.rs

@@ -11,6 +11,18 @@
     clippy::as_conversions
 )] // value helpers index paths directly for performance
 
+mod object;
+
+#[cfg(test)]
+mod tests;
+
+#[allow(unused_imports)] // surface for downstream PRs
+pub use object::{IntoIter, Iter, IterMut, Object};
+
+#[cfg(feature = "rvm")]
+#[allow(unused_imports)] // surface for downstream PRs
+pub use object::ObjectCursor;
+
 use crate::number::Number;
 
 use alloc::collections::{BTreeMap, BTreeSet};

src/value/object/iter.rs

@@ -0,0 +1,148 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! Opaque iterator types for [`Object`].
+//!
+//! 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::collections::btree_map;
+use core::iter::FusedIterator;
+
+use super::Object;
+use crate::value::Value;
+
+/// Owned iterator over `(Value, Value)` entries.
+#[derive(Debug)]
+pub struct IntoIter {
+    pub(super) inner: btree_map::IntoIter<Value, Value>,
+}
+
+impl Iterator for IntoIter {
+    type Item = (Value, 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, &Value)` entries.
+#[derive(Debug, Clone)]
+pub struct Iter<'a> {
+    pub(super) inner: btree_map::Iter<'a, Value, Value>,
+}
+
+impl<'a> Iterator for Iter<'a> {
+    type Item = (&'a Value, &'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> {}
+
+/// Borrowed iterator over `(&Value, &mut Value)` entries.
+#[derive(Debug)]
+pub struct IterMut<'a> {
+    pub(super) inner: btree_map::IterMut<'a, Value, Value>,
+}
+
+impl<'a> Iterator for IterMut<'a> {
+    type Item = (&'a Value, &'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> {}
+
+impl IntoIterator for Object {
+    type Item = (Value, Value);
+    type IntoIter = IntoIter;
+    #[inline]
+    fn into_iter(self) -> Self::IntoIter {
+        IntoIter {
+            inner: self.inner.into_iter(),
+        }
+    }
+}
+
+impl<'a> IntoIterator for &'a Object {
+    type Item = (&'a Value, &'a Value);
+    type IntoIter = Iter<'a>;
+    #[inline]
+    fn into_iter(self) -> Self::IntoIter {
+        Iter {
+            inner: self.inner.iter(),
+        }
+    }
+}
+
+impl<'a> IntoIterator for &'a mut Object {
+    type Item = (&'a Value, &'a mut Value);
+    type IntoIter = IterMut<'a>;
+    #[inline]
+    fn into_iter(self) -> Self::IntoIter {
+        IterMut {
+            inner: self.inner.iter_mut(),
+        }
+    }
+}