microsandbox-rb 0.9.2 → 0.10.0

data/README.md

@@ -229,6 +229,55 @@ Microsandbox::Sandbox.create("obs", image: "public.ecr.aws/docker/library/alpine
 end
 ```
 
+### Live modification & health
+
+Resize, reconfigure, or rotate secrets on a sandbox **without recreating it**,
+and probe the guest agent's liveness. To leave headroom for a live CPU/memory
+resize, reserve a ceiling at create time with `max_cpus:`/`max_memory:`:
+
+```ruby
+Microsandbox::Sandbox.create("live", image: "public.ecr.aws/docker/library/alpine:latest",
+  cpus: 1, max_cpus: 4, memory: 512, max_memory: 2048) do |sb|
+  # Health check — does NOT refresh the idle timer:
+  ping = sb.ping                       # => Microsandbox::PingResult
+  ping.latency_ms                      # round-trip latency
+
+  # Explicitly refresh the idle-activity timer (resets any idle_timeout:):
+  sb.touch.activity_seq                # => Microsandbox::TouchResult
+
+  # Preview a change without applying it:
+  plan = sb.modify(cpus: 2, memory: 1024, dry_run: true)
+  plan.applied?                        # => false
+  plan.changes                         # => [{ kind: "config", field: "cpus", ... }, ...]
+
+  # Live resize — applies to the running VM under the default :no_restart policy:
+  sb.modify(cpus: 2, memory: 1024)
+
+  # env/labels/workdir changes on a *running* sandbox require a restart, so the
+  # default :no_restart policy rejects the whole apply (it raises rather than
+  # partially applying). Persist them for the next start — or restart now —
+  # by saying so explicitly:
+  sb.modify(env: { "TIER" => "prod" }, remove_env: ["DEBUG"],
+    labels: { "role" => "worker" }, policy: :next_start)  # or policy: :restart
+
+  # Rotating/removing an *existing* secret (or updating its allowed hosts) is
+  # live; *adding* a new secret is restart-required, like env. Specs are keyed
+  # by name; env:/store:/value: are mutually exclusive:
+  sb.modify(
+    secrets: { "API_KEY" => { env: "HOST_API_KEY", allowed_hosts: ["api.example.com"] } },
+    remove_secrets: ["OLD_TOKEN"],
+  )
+end
+```
+
+The apply is **all-or-nothing**: under a given `policy:` every planned change
+must be applicable, or the whole `modify` raises — nothing is partially
+applied. Use `dry_run: true` to inspect each change's `disposition` (`"live"`,
+`"next start"`, `"requires restart"`) before committing.
+
+`SandboxHandle` (from `Sandbox.get`/`list`) carries the same `#ping`/`#touch`/
+`#modify`; on a stopped sandbox `#ping`/`#touch` raise `SandboxNotRunningError`.
+
 ### Streaming output
 
 For long-running commands, stream events as they arrive instead of waiting:
@@ -393,8 +442,8 @@ change diverged the two numbers — the gem version is **not** a reliable indica
 of the embedded runtime version. To learn which runtime a build wraps, ask it:
 
 ```ruby
-Microsandbox::VERSION          # => "0.9.2"  (the gem's own version)
-Microsandbox.runtime_version   # => "v0.6.3"  (the embedded upstream runtime tag)
+Microsandbox::VERSION          # => "0.10.0"  (the gem's own version)
+Microsandbox.runtime_version   # => "v0.6.6"  (the embedded upstream runtime tag)
 ```
 
 | Gem version | Upstream runtime | Notes |
@@ -413,6 +462,8 @@ Microsandbox.runtime_version   # => "v0.6.3"  (the embedded upstream runtime tag
 | `0.9.0`  | `v0.6.1` | adopts upstream `v0.6.0`+`v0.6.1` (zombie-runtime wait fix, secret substitution through CONNECT proxies, stale-sandbox cleanup); upstream public API is additive — no Ruby surface change |
 | `0.9.1`  | `v0.6.2` | adopts upstream `v0.6.2` (faster image loads/pulls via early cache gate + zlib-rs); upstream API unchanged — no Ruby surface change |
 | `0.9.2`  | `v0.6.3` | adopts upstream `v0.6.3` (v4-only sandboxes stop advertising AAAA DNS answers — fixes guest gRPC/c-ares preferring unreachable IPv6; scoped upstream TLS verification); glue moves to `*_local` SDK variants — no Ruby surface change |
+| `0.9.3`  | `v0.6.6` | adopts upstream `v0.6.4`+`v0.6.6` (`v0.6.5` was yanked upstream): snapshot restore by pinned digest — fixes fatal restore-after-tag-republish bug, fragmented-UDP/PMTU relay fixes, exec kills the whole process group, ephemeral stop-wait tolerance, readdir RSS-leak fix; upstream API growth is additive-only — no Ruby surface change |
+| `0.10.0` | `v0.6.6` | `v0.6.6` API parity: live `modify`/resize, `ping`/`touch`, create `max_cpus`/`max_memory` |
 
 **Going forward** — the gem version moves on its own semver track and no longer
 mirrors the upstream tag:

data/ext/microsandbox/Cargo.toml

@@ -6,8 +6,8 @@ name = "microsandbox_rb"
 description = "Ruby SDK native extension for microsandbox — secure, fast microVM-based sandboxing."
 # Must equal Microsandbox::VERSION (lib/microsandbox/version.rb) — Native.version
 # returns this via env!("CARGO_PKG_VERSION") and version_spec.rb asserts equality.
-# The core-crate dependency below stays pinned at its own tag (v0.6.3).
-version = "0.9.2"
+# The core-crate dependency below stays pinned at its own tag (v0.6.6).
+version = "0.10.0"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"
@@ -35,8 +35,8 @@ rb-sys = "0.9"
 # `.cargo/config.toml.example`). "ssh" matches the feature set the Python/Node
 # SDKs ship with; default features add "prebuilt" (provisions msb + libkrunfw at
 # build time), "net", and "keyring".
-microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.3", default-features = true, features = ["ssh"] }
-microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.3" }
+microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.6", default-features = true, features = ["ssh"] }
+microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.6" }
 
 # Async core bridged to Ruby's synchronous API via a blocking tokio runtime.
 tokio = { version = "1", features = ["rt-multi-thread", "sync", "time"] }

data/ext/microsandbox/src/error.rs

@@ -17,6 +17,12 @@ fn class_name(err: &MicrosandboxError) -> &'static str {
         SandboxNotFound(_) => "SandboxNotFoundError",
         SandboxAlreadyExists(_) => "SandboxAlreadyExistsError",
         SandboxStillRunning(_) => "SandboxStillRunningError",
+        // v0.6.6 (#1099): the sandbox exists but isn't running. Raised by the
+        // handle's exec/attach/ping/touch not-running guards and the fs
+        // agent-endpoint lookup. The `SandboxNotRunningError` class already
+        // existed (mirroring the Python SDK); this wires the new core variant to
+        // it instead of letting it collapse to the base `Error`.
+        SandboxNotRunning(_) => "SandboxNotRunningError",
         ExecTimeout(_) => "ExecTimeoutError",
         ExecFailed(_) => "ExecFailedError",
         SandboxFsOps(_) => "FilesystemError",

data/ext/microsandbox/src/sandbox.rs

@@ -18,10 +18,11 @@ use microsandbox::logs::{
     LogCursor, LogEntry, LogOptions, LogSource, LogStreamOptions, LogStreamStart,
 };
 use microsandbox::sandbox::{
-    AttachOptionsBuilder, DiskImageFormat, FsEntry, FsEntryKind, FsMetadata, HostPermissions,
-    Patch, PullPolicy, PullProgress, PullProgressHandle, RlimitResource, SandboxBuilder,
-    SandboxFilter, SandboxHandle, SandboxMetrics, SandboxStatus, SandboxStopResult, SecretBuilder,
-    SecurityProfile, StatVirtualization,
+    AttachOptionsBuilder, DiskImageFormat, EnvVar, FsEntry, FsEntryKind, FsMetadata,
+    HostPermissions, Patch, PullPolicy, PullProgress, PullProgressHandle, RlimitResource,
+    SandboxBuilder, SandboxFilter, SandboxHandle, SandboxMetrics, SandboxModificationBuilder,
+    SandboxModificationPatch, SandboxStatus, SandboxStopResult, SecretBuilder,
+    SecretModificationPatch, SecretSource, SecurityProfile, StatVirtualization,
 };
 use microsandbox::LogLevel;
 use microsandbox::MicrosandboxResult;
@@ -92,9 +93,19 @@ impl Sandbox {
         if let Some(v) = conv::opt_u8(opts, "cpus")? {
             b = b.cpus(v);
         }
+        // v0.6.6 (#1099): boot-time maximum vCPU / memory ceilings that a later
+        // live `modify` can grow up to. `cpus`/`memory` above already raise these
+        // to their own value if lower, so a bare `cpus`/`memory` still works;
+        // setting these explicitly reserves headroom for a live resize.
+        if let Some(v) = conv::opt_u8(opts, "max_cpus")? {
+            b = b.max_cpus(v);
+        }
         if let Some(v) = conv::opt_u32(opts, "memory")? {
             b = b.memory(v);
         }
+        if let Some(v) = conv::opt_u32(opts, "max_memory")? {
+            b = b.max_memory(v);
+        }
         if let Some(v) = conv::opt_string(opts, "workdir")? {
             b = b.workdir(v);
         }
@@ -584,6 +595,34 @@ impl Sandbox {
         Ok(metrics_to_hash(&m))
     }
 
+    //----------------------------------------------------------------------
+    // Health & modification (v0.6.6 / #1099)
+    //----------------------------------------------------------------------
+
+    /// Health-check the guest agent without refreshing the idle timer. Returns
+    /// `{ name, latency_secs }` (round-trip latency as f64 seconds; the Ruby
+    /// layer exposes both seconds and milliseconds).
+    fn ping(&self) -> Result<RHash, Error> {
+        let result = block_on(self.inner.ping()).map_err(error::to_ruby)?;
+        Ok(ping_result_to_hash(&result))
+    }
+
+    /// Explicitly refresh the idle-activity timer. Returns
+    /// `{ name, activity_seq }`.
+    fn touch(&self) -> Result<RHash, Error> {
+        let result = block_on(self.inner.touch()).map_err(error::to_ruby)?;
+        Ok(touch_result_to_hash(&result))
+    }
+
+    /// Plan or apply a live sandbox modification. `opts` is the string-keyed
+    /// modify Hash normalized by the Ruby layer; returns the resulting
+    /// `SandboxModificationPlan` as a JSON string, which the Ruby layer parses
+    /// into a `ModificationPlan`. Mirrors the Node native binding (native returns
+    /// JSON, the wrapper shapes it).
+    fn modify(&self, opts: RHash) -> Result<String, Error> {
+        run_modify(self.inner.modify(), opts)
+    }
+
     /// Read captured logs as an Array of Hashes. `opts`: tail, since_ms,
     /// until_ms, sources (Array of "stdout"/"stderr"/"output"/"system"/"all").
     fn logs(&self, opts: RHash) -> Result<RArray, Error> {
@@ -1736,6 +1775,133 @@ fn stop_result_to_hash(result: &SandboxStopResult) -> RHash {
     hash
 }
 
+//--------------------------------------------------------------------------------------------------
+// Health & live modification (v0.6.6 / #1099)
+//--------------------------------------------------------------------------------------------------
+
+/// A `SandboxPingResult` as `{ name, latency_secs }`. Latency is a `Duration`;
+/// we hand it to Ruby as f64 seconds and let the Ruby layer derive milliseconds
+/// (the Python/Node SDKs expose only `latency_ms`).
+fn ping_result_to_hash(result: &microsandbox::sandbox::SandboxPingResult) -> RHash {
+    let hash = ruby().hash_new();
+    let _ = hash.aset("name", result.name.clone());
+    let _ = hash.aset("latency_secs", result.latency.as_secs_f64());
+    hash
+}
+
+/// A `SandboxTouchResult` as `{ name, activity_seq }`.
+fn touch_result_to_hash(result: &microsandbox::sandbox::SandboxTouchResult) -> RHash {
+    let hash = ruby().hash_new();
+    let _ = hash.aset("name", result.name.clone());
+    let _ = hash.aset("activity_seq", result.activity_seq);
+    hash
+}
+
+/// Drive a modify builder to a plan (dry-run or apply) and return it serialized
+/// as a JSON string. Shared by `Sandbox::modify` and `SbHandle::modify`. The
+/// canonical `SandboxModificationPlan` serde shape (snake_case keys, literal-space
+/// enum strings) is parsed verbatim by the Ruby layer — matching the Python SDK's
+/// raw-dict contract rather than re-casing it.
+fn run_modify(builder: SandboxModificationBuilder, opts: RHash) -> Result<String, Error> {
+    let patch = build_modify_patch(opts)?;
+    let policy = conv::opt_string(opts, "policy")?.unwrap_or_else(|| "no_restart".to_string());
+    let dry_run = conv::opt_bool(opts, "dry_run")?;
+    let builder = apply_modify_policy(builder.with_patch(patch), &policy)?;
+    let plan = block_on(async move {
+        if dry_run {
+            builder.dry_run().await
+        } else {
+            builder.apply().await
+        }
+    })
+    .map_err(error::to_ruby)?;
+    serde_json::to_string(&plan)
+        .map_err(|e| error::base_error(format!("failed to serialize modification plan: {e}")))
+}
+
+/// Build the canonical `SandboxModificationPatch` from the modify Hash. Env and
+/// label pairs are sorted so repeated calls with the same arguments produce the
+/// same patch (and plan) ordering, mirroring the Python binding. `oci_upper_size`
+/// is deliberately not surfaced (CLI-only upstream; the Python/Node SDKs omit it
+/// too), so it stays unset via `..Default::default()`.
+fn build_modify_patch(opts: RHash) -> Result<SandboxModificationPatch, Error> {
+    let mut env_pairs = conv::opt_string_map(opts, "env")?;
+    env_pairs.sort();
+    let mut label_pairs = conv::opt_string_map(opts, "labels")?;
+    label_pairs.sort();
+
+    Ok(SandboxModificationPatch {
+        cpus: conv::opt_u8(opts, "cpus")?,
+        max_cpus: conv::opt_u8(opts, "max_cpus")?,
+        memory_mib: conv::opt_u32(opts, "memory")?,
+        max_memory_mib: conv::opt_u32(opts, "max_memory")?,
+        env: env_pairs
+            .into_iter()
+            .map(|(k, v)| EnvVar::new(k, v))
+            .collect(),
+        env_remove: conv::opt_string_vec(opts, "remove_env")?,
+        labels: label_pairs,
+        labels_remove: conv::opt_string_vec(opts, "remove_labels")?,
+        workdir: conv::opt_string(opts, "workdir")?,
+        secrets: parse_modify_secrets(opts)?,
+        secrets_remove: conv::opt_string_vec(opts, "remove_secrets")?,
+        ..Default::default()
+    })
+}
+
+/// Parse the `secrets` modify option (an Array of string-keyed Hashes normalized
+/// by the Ruby layer) into canonical `SecretModificationPatch`es. Each Hash
+/// carries `name` plus at most one of `env`/`store` (source) or `value` (raw
+/// material) — the Ruby layer enforces that mutual exclusion — plus optional
+/// `placeholder` and `allowed_hosts`. The raw `value` moves straight into the
+/// `Zeroizing` field; it is never echoed in an error.
+fn parse_modify_secrets(opts: RHash) -> Result<Vec<SecretModificationPatch>, Error> {
+    let mut out = Vec::new();
+    for h in conv::opt_hash_vec(opts, "secrets")? {
+        let name = conv::opt_string(h, "name")?
+            .ok_or_else(|| error::base_error("secret modification spec requires :name"))?;
+        let env = conv::opt_string(h, "env")?;
+        let store = conv::opt_string(h, "store")?;
+        let value = conv::opt_string(h, "value")?;
+        let source = match (env, store) {
+            (Some(var), None) => Some(SecretSource::Env { var }),
+            (None, Some(reference)) => Some(SecretSource::Store { reference }),
+            (None, None) => None,
+            // The Ruby layer rejects >1 source; guard defensively without
+            // echoing any value.
+            (Some(_), Some(_)) => {
+                return Err(error::base_error(format!(
+                    "secret {name:?}: \"env\" and \"store\" are mutually exclusive"
+                )))
+            }
+        };
+        out.push(SecretModificationPatch {
+            name,
+            source,
+            value: value.unwrap_or_default().into(),
+            placeholder: conv::opt_string(h, "placeholder")?,
+            allowed_hosts: conv::opt_string_vec(h, "allowed_hosts")?,
+        });
+    }
+    Ok(out)
+}
+
+/// Apply the parsed `policy` string to a modify builder. `no_restart` (default)
+/// leaves the builder untouched; `next_start`/`restart` select those policies.
+fn apply_modify_policy(
+    builder: SandboxModificationBuilder,
+    policy: &str,
+) -> Result<SandboxModificationBuilder, Error> {
+    match policy {
+        "no_restart" => Ok(builder),
+        "next_start" => Ok(builder.next_start()),
+        "restart" => Ok(builder.restart()),
+        other => Err(error::base_error(format!(
+            "unknown policy {other:?}; expected \"no_restart\", \"next_start\", or \"restart\""
+        ))),
+    }
+}
+
 //--------------------------------------------------------------------------------------------------
 // Pull progress (streaming image-pull during create_with_progress)
 //--------------------------------------------------------------------------------------------------
@@ -1987,6 +2153,27 @@ impl SbHandle {
         let snap = block_on(self.inner.snapshot_to(path)).map_err(error::to_ruby)?;
         Ok(crate::snapshot::snapshot_to_hash(&snap))
     }
+
+    /// Health-check the guest agent without refreshing the idle timer. A stopped
+    /// sandbox raises `SandboxNotRunningError` (the handle does not start it
+    /// implicitly). Returns `{ name, latency_secs }`.
+    fn ping(&self) -> Result<RHash, Error> {
+        let result = block_on(self.inner.ping()).map_err(error::to_ruby)?;
+        Ok(ping_result_to_hash(&result))
+    }
+
+    /// Explicitly refresh the idle-activity timer. A stopped sandbox raises
+    /// `SandboxNotRunningError`. Returns `{ name, activity_seq }`.
+    fn touch(&self) -> Result<RHash, Error> {
+        let result = block_on(self.inner.touch()).map_err(error::to_ruby)?;
+        Ok(touch_result_to_hash(&result))
+    }
+
+    /// Plan or apply a live sandbox modification (see `Sandbox::modify`). Returns
+    /// the `SandboxModificationPlan` as a JSON string.
+    fn modify(&self, opts: RHash) -> Result<String, Error> {
+        run_modify(self.inner.modify(), opts)
+    }
 }
 
 //--------------------------------------------------------------------------------------------------
@@ -2100,6 +2287,9 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_method("owns_lifecycle", method!(Sandbox::owns_lifecycle, 0))?;
     class.define_method("detach", method!(Sandbox::detach, 0))?;
     class.define_method("metrics", method!(Sandbox::metrics, 0))?;
+    class.define_method("ping", method!(Sandbox::ping, 0))?;
+    class.define_method("touch", method!(Sandbox::touch, 0))?;
+    class.define_method("modify", method!(Sandbox::modify, 1))?;
     class.define_method("metrics_stream", method!(Sandbox::metrics_stream, 1))?;
     class.define_method("logs", method!(Sandbox::logs, 1))?;
     class.define_method("log_stream", method!(Sandbox::log_stream, 1))?;
@@ -2148,6 +2338,9 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     handle.define_method("config_json", method!(SbHandle::config_json, 0))?;
     handle.define_method("snapshot", method!(SbHandle::snapshot, 1))?;
     handle.define_method("snapshot_to", method!(SbHandle::snapshot_to, 1))?;
+    handle.define_method("ping", method!(SbHandle::ping, 0))?;
+    handle.define_method("touch", method!(SbHandle::touch, 0))?;
+    handle.define_method("modify", method!(SbHandle::modify, 1))?;
 
     let session = native.define_class("PullSession", ruby.class_object())?;
     session.define_method("recv", method!(PullSession::recv, 0))?;

data/lib/microsandbox/modification.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # The result of {Sandbox#ping} / {SandboxHandle#ping}: a lightweight health
+  # check that confirms the guest agent is reachable without refreshing the
+  # sandbox idle timer. Mirrors the official SDKs' `SandboxPingResult`.
+  #
+  # The native layer reports latency as seconds; {#latency} is the canonical
+  # value and {#latency_ms} the convenience the Python/Node SDKs expose.
+  class PingResult
+    # @return [String] the sandbox name that was pinged
+    attr_reader :name
+    # @return [Float] round-trip latency in seconds
+    attr_reader :latency
+
+    def initialize(data)
+      @name = data["name"]
+      @latency = data["latency_secs"]
+    end
+
+    # @return [Float] round-trip latency in milliseconds
+    def latency_ms
+      @latency * 1000.0
+    end
+
+    def inspect
+      "#<Microsandbox::PingResult name=#{@name.inspect} latency_ms=#{format("%.3f", latency_ms)}>"
+    end
+  end
+
+  # The result of {Sandbox#touch} / {SandboxHandle#touch}: an explicit refresh of
+  # the sandbox idle-activity timer. Mirrors the official SDKs' `SandboxTouchResult`.
+  class TouchResult
+    # @return [String] the sandbox name that was touched
+    attr_reader :name
+    # @return [Integer] the agent activity sequence after this touch was recorded
+    attr_reader :activity_seq
+
+    def initialize(data)
+      @name = data["name"]
+      @activity_seq = data["activity_seq"]
+    end
+
+    def inspect
+      "#<Microsandbox::TouchResult name=#{@name.inspect} activity_seq=#{@activity_seq}>"
+    end
+  end
+
+  # The plan produced by {Sandbox#modify} / {SandboxHandle#modify}: the classified
+  # set of changes a modification requested, and (for a non-dry-run apply) whether
+  # they were applied plus any live-resize convergence outcomes. Mirrors the
+  # official SDKs' `SandboxModificationPlan`.
+  #
+  # The nested collections ({#changes}, {#conflicts}, {#warnings},
+  # {#resize_status}) are frozen Arrays of frozen, symbol-keyed Hashes carrying
+  # the canonical snake_case fields verbatim (e.g. a config change is
+  # `{ kind: "config", field:, change:, before:, after:, disposition:, reason: }`;
+  # a secret change adds `name:`, `before_ref:`, `after_ref:`, `allow_hosts:`).
+  # Enum values stay as the runtime's strings (e.g. a `disposition` of
+  # `"next start"`, a `state` of `"guest-refused"`).
+  class ModificationPlan
+    # @return [String] the sandbox the plan applies to
+    attr_reader :sandbox
+    # @return [String] the sandbox status used to classify the changes
+    attr_reader :status
+    # @return [Symbol] :no_restart, :next_start, or :restart
+    attr_reader :policy
+    # @return [Array<Hash>] the planned changes (config and secret)
+    attr_reader :changes
+    # @return [Array<Hash>] conflicts that must be resolved before applying
+    attr_reader :conflicts
+    # @return [Array<Hash>] non-fatal warnings about the patch
+    attr_reader :warnings
+    # @return [Array<Hash>] live resource-resize outcomes (populated by an apply)
+    attr_reader :resize_status
+
+    def initialize(data)
+      @sandbox = data["sandbox"]
+      @status = data["status"]
+      @applied = data["applied"]
+      @policy = data["policy"]&.to_sym
+      @changes = freeze_items(data["changes"])
+      @conflicts = freeze_items(data["conflicts"])
+      @warnings = freeze_items(data["warnings"])
+      @resize_status = freeze_items(data["resize_status"])
+    end
+
+    # @return [Boolean] whether the changes were applied (false for a dry run)
+    def applied?
+      @applied
+    end
+
+    def inspect
+      "#<Microsandbox::ModificationPlan sandbox=#{@sandbox.inspect} applied=#{@applied} " \
+        "policy=#{@policy} changes=#{@changes.size} conflicts=#{@conflicts.size} " \
+        "warnings=#{@warnings.size}>"
+    end
+
+    private
+
+    # Convert a JSON array of plan entries (string-keyed Hashes) into a frozen
+    # Array of frozen, symbol-keyed Hashes. The entries are shallow (all values
+    # are scalars or string arrays), so a single `transform_keys` suffices.
+    def freeze_items(items)
+      Array(items).map { |item| item.transform_keys(&:to_sym).freeze }.freeze
+    end
+  end
+end