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,83 @@
+# 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.
+
+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.
+
+## Scenarios enabled
+
+- **Hash-backed storage** — for policies where keys aren't compared
+  ordinally; swap to FxHashMap-backed inner without touching call sites.
+- **Lazy/streaming** — wrap a `LazyObjectProvider` (DB query, CBOR slice,
+  REST endpoint) and materialize entries on demand.
+- **Arena allocation** — bumpalo-backed inner for eval-time temporaries;
+  drop the whole arena at query end with zero per-entry free cost.
+- **FFI-backed** — host-language callbacks (Python dict, JS object) without
+  copying into Rust.
+- **Small-map optimization** — inline storage for ≤N entries, heap above;
+  eliminates per-object BTreeMap heap allocation for the common case.
+
+## Known use cases
+
+- **Azure Policy aliases** — policy authors write paths like
+  `Microsoft.Compute/virtualMachines/storageProfile.osDisk.managedDisk.id`;
+  the same logical property is exposed under multiple aliases by ARM.
+  An alias-aware Object backend resolves lookups across canonical and
+  alias forms without rewriting every policy.
+- **Azure Policy case-insensitive compare** — resource property names in
+  ARM are case-preserving but case-insensitive on lookup
+  (`tags.Environment` vs `tags.environment` resolve identically). A
+  case-insensitive Object backend implements this once at the storage
+  layer instead of every comparison site in policies.
+- **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 eliminates per-object
+  BTreeMap heap 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 Object backend parses only accessed
+  subtrees from the incoming JSON.
+- **Cloud config drift detection** — comparing current vs desired
+  resource state requires structural equality that's tolerant of
+  key-order differences and provider-specific casing. Centralizing this
+  in the Object backend keeps policies portable across cloud providers.
+
+## Notes
+
+Cursor types are `pub` (referenced by public `IterationState`) but not
+re-exported at the crate root. Future Array and String abstractions
+follow the same shape — see `docs/value/array.md` and `docs/value/string.md`
+when they land.

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;