Introduce Object storage abstraction

Adds an opaque `Object` type that wraps the `BTreeMap<Value, Value>`
backing `Value::Object`. The wrapper hides the inner map and exposes a
curated method surface (get, insert, remove, iter, iter_sorted, cursor,
serde), so future backends -- small-map inline, hash-backed, lazy,
arena, FFI -- can swap in without call-site churn.

This change is purely additive. `Value::Object` still wraps
`Rc<BTreeMap<Value, Value>>`; the payload swap and call-site migration
ship in the follow-up PR. `Object` is fully covered by its own tests
but is not yet used by the engine.

`docs/value/object.md` describes the design, enabled scenarios, known
use cases (Azure Policy aliases and case-insensitive compare, SARIF
small-object pressure, Kubernetes admission, cloud drift detection),
and precedents (`serde_json::Map`, `toml::Table`, `simdjson` DOM,
`indexmap`).

The 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/collections/mod.rs

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! Storage abstraction for `Value::Object`.
+//!
+//! [`Object`] is an opaque wrapper around the current backing storage
+//! (`BTreeMap<Value, Value>`). Its inner field is private so that future
+//! storage representations (two-tier inline+hash, lazy, schema-shared,
+//! projection-aware) can swap in without touching call sites.
+//!
+//! ## Iteration order
+//!
+//! - [`Object::iter`] is **implementation-defined order** (mirroring
+//!   `HashMap::iter`). Today it happens to iterate in sorted order because
+//!   storage is BTree-backed, but callers MUST NOT depend on that.
+//! - [`Object::iter_sorted`] is **sorted by `Value::Ord`**. Use this whenever
+//!   deterministic order is required (serialization, snapshots, hashing,
+//!   `Debug`, the `object.keys` builtin, RVM↔interpreter parity).
+//!
+//! ## Resumable iteration
+//!
+//! Use [`Object::cursor`] / [`Object::next`] when callers must yield
+//! mid-iteration and resume later (e.g. the RVM `IterationState`). The
+//! cursor types are crate-internal so future storage variants can change
+//! their resume-state representation. Use plain [`Object::iter`] /
+//! [`Object::iter_sorted`] for one-shot consumption.
+
+mod object;
+
+#[cfg(test)]
+mod tests;
+
+#[allow(unused_imports)] // surface for downstream PRs; cursor used internally in PR1b
+pub use object::{IntoIter, Iter, IterMut, Object};
+
+#[cfg(feature = "rvm")]
+#[allow(unused_imports)] // surface for downstream PRs
+pub use object::ObjectCursor;