shape_vm/executor/

printing.rs

//! VM-native value formatting (ADR-006 §2.7.4 — output adapter).
//!
//! Formats runtime values held in a [`KindedSlot`] for `print()` /
//! `format()` / REPL display. The pre-bulldozer implementation keyed off
//! the deleted `ValueWord` carrier and `tag_bits::*` decode helpers; per
//! ADR-006 §2.7.4 the formatter moves to a kinded carrier — `NativeKind`
//! drives inline-scalar dispatch, and heap arms are read via
//! `slot.as_heap_value()` + `HeapValue` match (Q8 ruling, preserves
//! ADR-005 §1 single-discriminator).
//!
//! [`PrintResult`] and [`PrintSpan`] live in `shape_runtime::print_result`
//! per §2.7.4; consumers of this formatter pair its output with those
//! span-metadata carriers when feeding the output adapter.
//!
//! # Phase-1b-vm migration scope (E-printing close)
//!
//! Wave 6.5 / Wave-α `E-printing` ports the formatter SHAPE off the
//! deleted `ValueWord` API: the public surface now takes `&KindedSlot`,
//! dispatches on `NativeKind` for the inline-scalar arms (Int*, UInt*,
//! IntSize, UIntSize, Bool, Float64), and reads heap-bearing kinds via
//! the typed `Arc<T>` payload reconstruction shared with
//! `KindedSlot::Drop` / `clone_with_kind`. Heap arms whose payload
//! formatting depends on Phase-2c surfaces (TypedObject schema lookup,
//! Content rendering, Temporal/DateTime formatting, TableView, Iterator
//! / Generator state) surface as `todo!("phase-2c — see ADR-006
//! §2.7.4")` placeholders rather than papering over with ValueWord-shape
//! recovery, per the playbook's surface-and-stop discipline.

use shape_runtime::type_schema::{EnumVariantKind, TypeSchema, TypeSchemaRegistry};
use shape_value::heap_value::{
    HeapKind, HeapValue, TypedObjectStorage,
};
use shape_value::{KindedSlot, NativeKind, ValueSlot};
use std::sync::Arc;

// Re-export the runtime-tier `PrintResult`/`PrintSpan` carriers for
// formatter consumers — keeps the post-§2.7.4 import path coherent for
// callers that still reach into `shape_vm::executor::printing` for the
// output-adapter types.
pub use shape_runtime::print_result::{PrintResult, PrintSpan};

/// Formatter for runtime values represented as [`KindedSlot`].
///
/// Uses [`TypeSchemaRegistry`] to format `TypedObject` payloads with
/// their schema-declared field names. Optionally accepts a reference
/// resolver (Phase-2c) that dereferences ref-kind slots to their target
/// values; absent the resolver, refs print as `<ref>`.
///
/// ADR-005 §1 single-discriminator preserved: heap arms are read via
/// the slot's typed pointer + `HeapValue` match (Q8 ruling). No
/// per-heap-variant accessors on `KindedSlot`; no parallel sum types.
pub struct ValueFormatter<'a> {
    /// Type schema registry for `TypedObject` field resolution.
    schema_registry: &'a TypeSchemaRegistry,
    /// Optional reference-resolver hook. Phase-2c wire-up: when present,
    /// `Ref`-kind slots are dereferenced and the target formatted in
    /// their place; when absent, refs print as `<ref>`.
    deref_fn: Option<&'a dyn Fn(&KindedSlot) -> Option<KindedSlot>>,
}

impl<'a> ValueFormatter<'a> {
    /// Create a formatter without a reference resolver — `Ref`-kind
    /// slots will print as `<ref>`.
    pub fn new(schema_registry: &'a TypeSchemaRegistry) -> Self {
        Self {
            schema_registry,
            deref_fn: None,
        }
    }

    /// Create a formatter with a reference resolver. The resolver is
    /// invoked when a ref-kind slot is encountered; if it returns
    /// `Some(target)` the target is formatted in place, otherwise the
    /// ref prints as `<ref>`.
    pub fn with_deref(
        schema_registry: &'a TypeSchemaRegistry,
        deref_fn: &'a dyn Fn(&KindedSlot) -> Option<KindedSlot>,
    ) -> Self {
        Self {
            schema_registry,
            deref_fn: Some(deref_fn),
        }
    }

    /// Primary entry point: format a runtime value to a string.
    ///
    /// At the top level, raw strings render unquoted (so `print("hi")`
    /// prints `hi`, not `"hi"`). Inside containers (TypedObject fields,
    /// HashMap values, heap-array elements) strings are quoted via
    /// [`Self::format_kinded_nested`].
    pub fn format_kinded(&self, slot: &KindedSlot) -> String {
        self.format_kinded_inner(slot, 0, false)
    }

    /// Format a runtime value as it appears nested inside another
    /// container — quotes string values to disambiguate `{name: "alice"}`
    /// vs `{name: alice}`.
    pub fn format_kinded_nested(&self, slot: &KindedSlot) -> String {
        self.format_kinded_inner(slot, 0, true)
    }

    /// Recursive helper with depth tracking. Caps recursion at depth 50
    /// to bound output for cyclic / deeply nested values.
    ///
    /// `quote_strings` controls whether `String`-kind slots render as
    /// `"hello"` (true, nested) or `hello` (false, top-level).
    fn format_kinded_inner(&self, slot: &KindedSlot, depth: usize, quote_strings: bool) -> String {
        if depth > 50 {
            return "[max depth reached]".to_string();
        }

        let bits = slot.slot.raw();
        match slot.kind {
            // ── Inline scalars ──────────────────────────────────────────
            // R5b-2-bool-null-sentinel-cluster (ADR-006 §2.7 +
            // §2.7.7/Q9, 2026-05-19): canonical absence-of-value
            // discriminator — prints as `null` (mirror of the
            // pre-disposition `(0, NativeKind::Bool)` sentinel's
            // intended display surface).
            NativeKind::Null => "null".to_string(),
            NativeKind::Bool => slot.slot.as_bool().to_string(),
            NativeKind::Int8
            | NativeKind::NullableInt8
            | NativeKind::Int16
            | NativeKind::NullableInt16
            | NativeKind::Int32
            | NativeKind::NullableInt32
            | NativeKind::Int64
            | NativeKind::NullableInt64
            | NativeKind::IntSize
            | NativeKind::NullableIntSize => slot.slot.as_i64().to_string(),
            // r5c-2-β-CKPT-C u64-carrier-disambiguation (2026-05-20): a
            // `UInt64` slot is now unambiguously a genuine scalar `u64` —
            // the v2-typed-array pointer carrier moved to
            // `NativeKind::Ptr(HeapKind::TypedArray)` (formatted in
            // `format_heap_kind`'s `HeapKind::TypedArray` arm). The pre-fix
            // `as_v2_typed_array(bits, UInt64)` probe dereferenced an
            // arbitrary scalar `u64` value (e.g. `u64::MAX`) as a
            // `*const HeapHeader` → SIGSEGV on `print(x)`. Render directly.
            NativeKind::UInt64 | NativeKind::NullableUInt64 => {
                slot.slot.as_u64().to_string()
            }
            NativeKind::UInt8
            | NativeKind::NullableUInt8
            | NativeKind::UInt16
            | NativeKind::NullableUInt16
            | NativeKind::UInt32
            | NativeKind::NullableUInt32
            | NativeKind::UIntSize
            | NativeKind::NullableUIntSize => slot.slot.as_u64().to_string(),
            NativeKind::Float64 | NativeKind::NullableFloat64 => {
                format_number(slot.slot.as_f64())
            }
            // Round 19 S1.5 W12-nativekind-scalar-additions (2026-05-14):
            // ADR-006 §2.7.5 amendment adds F32 + Char as 4-byte scalar
            // variants. F32 prints via `format_number(f64::from(f32))`
            // (lossless widening, same numeric formatting as F64); Char
            // prints its codepoint as a single character (mirror of the
            // pre-amendment `HeapKind::Char` printing arm).
            NativeKind::Float32 => format_number(f64::from(f32::from_bits(bits as u32))),
            NativeKind::Char => match char::from_u32(bits as u32) {
                Some(c) if quote_strings => format!("'{}'", c),
                Some(c) => c.to_string(),
                None => format!("<invalid-char:0x{:x}>", bits),
            },
            // ── String (top-level NativeKind::String) ───────────────────
            NativeKind::String => {
                if bits == 0 {
                    return "None".to_string();
                }
                // SAFETY: per the construction-side contract on every
                // `KindedSlot::from_string_arc`-shaped producer, `String`
                // kind means the slot stores `Arc::into_raw::<String>`
                // bits and the slot owns one strong-count share. Read
                // the inner `&str` for the lifetime of `&self`.
                let s: &String = unsafe { &*(bits as *const String) };
                if quote_strings {
                    format!("\"{}\"", s)
                } else {
                    s.clone()
                }
            }
            // ── Wave 2 Agent B v2-raw carriers ───────────────────────────
            // W12-StringV2-DecimalV2-NativeKind-additions (2026-05-14): the
            // v2-raw `*const StringObj` / `*const DecimalObj` carriers print
            // with the same surface as their Arc-wrapped siblings. The
            // carrier shape (HeapHeader-equipped 24-byte `repr(C)` struct
            // per `v2/string_obj.rs` / `v2/decimal_obj.rs`) is invisible to
            // the print output — only the inner payload (UTF-8 bytes /
            // Decimal value) is rendered.
            NativeKind::StringV2 => {
                if bits == 0 {
                    return "None".to_string();
                }
                // SAFETY: per the §2.7.5 amendment construction contract,
                // kind=StringV2 means bits = `ptr as u64` pointing to a live
                // `StringObj` with bumped refcount.
                let ptr = bits as *const shape_value::v2::string_obj::StringObj;
                let s: &str = unsafe { shape_value::v2::string_obj::StringObj::as_str(ptr) };
                if quote_strings {
                    format!("\"{}\"", s)
                } else {
                    s.to_string()
                }
            }
            NativeKind::DecimalV2 => {
                if bits == 0 {
                    return "None".to_string();
                }
                // SAFETY: per the §2.7.5 amendment construction contract,
                // kind=DecimalV2 means bits = `ptr as u64` pointing to a live
                // `DecimalObj` with bumped refcount.
                let ptr = bits as *const shape_value::v2::decimal_obj::DecimalObj;
                let value = unsafe { shape_value::v2::decimal_obj::DecimalObj::value(ptr) };
                value.to_string()
            }
            // ── Heap-pointer kinds: dispatch via HeapKind ───────────────
            NativeKind::Ptr(hk) => self.format_heap_kind(bits, hk, depth, quote_strings),
        }
    }

    /// Heap-arm formatter: dispatches on `HeapKind` directly to read the
    /// matching typed `Arc<T>` payload (Q8 — no per-heap-variant accessor
    /// on the carrier; the kind discriminant is local).
    ///
    /// `quote_strings` propagates from the entry point — when this heap
    /// arm is itself a child of a TypedObject/HashMap/array and the parent
    /// asked for nested formatting, the leaf string render quotes.
    fn format_heap_kind(
        &self,
        bits: u64,
        hk: HeapKind,
        depth: usize,
        quote_strings: bool,
    ) -> String {
        if bits == 0 {
            return "None".to_string();
        }
        match hk {
            HeapKind::String => {
                // SAFETY: typed-Arc payload per §2.4.
                let s: &String = unsafe { &*(bits as *const String) };
                if quote_strings {
                    format!("\"{}\"", s)
                } else {
                    s.clone()
                }
            }
            HeapKind::Decimal => {
                let d: &rust_decimal::Decimal =
                    unsafe { &*(bits as *const rust_decimal::Decimal) };
                format!("{}D", d)
            }
            HeapKind::BigInt => {
                let i: &i64 = unsafe { &*(bits as *const i64) };
                i.to_string()
            }
            HeapKind::Char => {
                // `Char`-kind stores codepoint bits inline (no Arc<T>).
                match char::from_u32(bits as u32) {
                    Some(c) => c.to_string(),
                    None => "[Invalid char]".to_string(),
                }
            }
            HeapKind::TypedArray => {
                // r5c-2-β-CKPT-C u64-carrier-disambiguation (2026-05-20):
                // `Ptr(HeapKind::TypedArray)` is the canonical carrier for
                // every v2-raw `*mut TypedArray<T>` pointer (the
                // `NewTypedArray*` direct carrier + the refcounted
                // struct-field / closure-capture carrier — both hold the
                // identical pointer shape). Detect the array via the
                // on-header kind + `_pad` element-type byte and render via
                // the per-element walker. The legacy `Arc<TypedArrayData>`
                // boxed carrier this ordinal once labelled is deleted; the
                // pointee is unambiguously a v2-raw `TypedArray<T>`.
                let _ = depth;
                match crate::executor::v2_handlers::v2_array_detect::as_v2_typed_array(
                    bits,
                    NativeKind::Ptr(HeapKind::TypedArray),
                ) {
                    Some(view) => self.format_v2_typed_array(&view),
                    // Kind says TypedArray but the bits failed v2 detection
                    // (missing `HEAP_KIND_V2_TYPED_ARRAY` header). Render an
                    // opaque tag rather than dereferencing further.
                    None => "[TypedArray:?]".to_string(),
                }
            }
            HeapKind::TypedObject => {
                // ADR-006 §2.7.4 / §2.7.6 / Q8 — walk the per-field slots,
                // dispatch each on `field_kinds[i]` (the per-schema
                // `Arc<[NativeKind]>` co-located with the storage), and
                // resolve field names via the schema registry. SAFETY:
                // construction-side contract on `KindedSlot::from_typed_object`
                // — `TypedObject`-kind bits are `Arc::into_raw(Arc<TypedObjectStorage>)`.
                let storage: &TypedObjectStorage =
                    unsafe { &*(bits as *const TypedObjectStorage) };
                self.format_typed_object(storage, depth)
            }
            HeapKind::HashMap => {
                // Wave 2 Round 3b C2-joint ckpt-2 (2026-05-14): bits are
                // `Arc::into_raw(Arc<HashMapKindedRef>)` per ADR-006
                // §2.7.24 Q25.B SUPERSEDED. Cast through the kinded ref
                // wrapper; per-V Display dispatch lives at
                // `format_hashmap(kref, depth)`.
                let kref: &shape_value::heap_value::HashMapKindedRef =
                    unsafe { &*(bits as *const shape_value::heap_value::HashMapKindedRef) };
                self.format_hashmap(kref, depth)
            }
            HeapKind::HashSet => {
                // Wave 13 W13-hashset-rebuild (ADR-006 §2.7.15 / Q16,
                // 2026-05-10): HashSetData stores a single
                // `Vec<Arc<String>>` keys buffer (mirror of HashMapData
                // with the values buffer dropped). Render as
                // `{"a", "b", ...}`. SAFETY: construction-side contract
                // on `KindedSlot::from_hashset`.
                let _ = depth;
                let set: &shape_value::heap_value::HashSetData =
                    unsafe { &*(bits as *const shape_value::heap_value::HashSetData) };
                self.format_hashset(set)
            }
            HeapKind::DataTable => {
                let dt: &shape_value::DataTable =
                    unsafe { &*(bits as *const shape_value::DataTable) };
                format!("{}", dt)
            }
            HeapKind::Content => {
                // W18.2 (R8 — output-adapter integration): route the
                // Content payload through the kind-threaded
                // `slot_extract_content` host-boundary helper and render
                // via the adapter selected for `print()`. The audit
                // dispatch pins TERMINAL as the default for `print()` —
                // the per-adapter capabilities table at
                // `content_dispatch::capabilities_for_adapter` keys off
                // the same adapter constants (TERMINAL / HTML /
                // MARKDOWN / JSON / PLAIN) and the surviving
                // 6-renderer infrastructure projects the node per its
                // own `ContentRenderer::render` impl. Pre-rebuild this
                // arm called `ContentNode::Display` directly, which
                // emitted plain text with no ANSI styling; the
                // TerminalRenderer now resolves the per-span style
                // (bold / italic / fg / bg) into escape codes that the
                // `print()`-stdout sink renders directly. The
                // `quote_strings` flag is unused for Content nodes —
                // they're a self-contained renderable tree, not a leaf
                // string that needs quoting in a parent container.
                let _ = quote_strings;
                let node: &shape_value::content::ContentNode =
                    unsafe { &*(bits as *const shape_value::content::ContentNode) };
                let adapter = shape_runtime::content_dispatch::adapters::TERMINAL;
                let _capabilities =
                    shape_runtime::content_dispatch::capabilities_for_adapter(adapter);
                // The capabilities are passed implicitly via the
                // renderer constructor — `TerminalRenderer::new()`
                // builds a `RenderContext::terminal()` with ANSI on by
                // default. The `_capabilities` lookup is kept as the
                // documented dispatch surface per the audit
                // (`capabilities_for_adapter` is the public selector);
                // hooking it into the renderer constructors landed via
                // the per-renderer `new`/`Default` shape — additional
                // renderer constructors that take an explicit
                // `RendererCapabilities` would replace the implicit
                // construction here.
                use shape_runtime::content_renderer::ContentRenderer;
                let renderer = shape_runtime::renderers::terminal::TerminalRenderer::new();
                renderer.render(node)
            }
            HeapKind::Instant => {
                let t: &std::time::Instant =
                    unsafe { &*(bits as *const std::time::Instant) };
                format!("<instant:{:?}>", t.elapsed())
            }
            HeapKind::IoHandle => {
                let data: &shape_value::heap_value::IoHandleData =
                    unsafe { &*(bits as *const shape_value::heap_value::IoHandleData) };
                let status = if data.is_open() { "open" } else { "closed" };
                format!("<io_handle:{}:{}>", data.path, status)
            }
            HeapKind::NativeView => {
                let v: &shape_value::heap_value::NativeViewData =
                    unsafe { &*(bits as *const shape_value::heap_value::NativeViewData) };
                format!(
                    "<{}:{}@0x{:x}>",
                    if v.mutable { "cmut" } else { "cview" },
                    v.layout.name,
                    v.ptr
                )
            }
            HeapKind::Temporal => {
                // C1-temporal-lowering (Phase 2d Wave 2): Temporal carrier
                // dispatch per ADR-006 §2.7.4. Slot bits are
                // `Arc::into_raw::<TemporalData>` (set by
                // `compiler/expressions/temporal.rs::compile_expr_duration`
                // + `op_push_const`'s Duration arm in `stack_ops/mod.rs`
                // and by the `TIMESPAN_METHODS` / `DATETIME_METHODS`
                // PHF result construction in
                // `objects/datetime_methods.rs::temporal_result`).
                // `TemporalData`'s own `Display` impl already handles
                // every arm (DateTime / Duration / TimeSpan / Timeframe /
                // TimeReference / DateTimeExpr / DataDateTimeRef); we
                // dispatch through it preserving ADR-005 §1's
                // single-discriminator discipline (no per-arm peek at
                // the `TemporalData` payload here).
                let td: &shape_value::heap_value::TemporalData =
                    unsafe { &*(bits as *const shape_value::heap_value::TemporalData) };
                format!("{}", td)
            }
            HeapKind::TableView => {
                let tv: &shape_value::heap_value::TableViewData =
                    unsafe { &*(bits as *const shape_value::heap_value::TableViewData) };
                format!("{}", tv)
            }
            HeapKind::TaskGroup => {
                let tg: &shape_value::heap_value::TaskGroupData =
                    unsafe { &*(bits as *const shape_value::heap_value::TaskGroupData) };
                let kind_str = match tg.kind {
                    0 => "All",
                    1 => "Race",
                    2 => "Any",
                    3 => "Settle",
                    _ => "Unknown",
                };
                format!("[TaskGroup:{}({})]", kind_str, tg.task_ids.len())
            }
            HeapKind::Closure => {
                // ClosureRaw payload uses `OwnedClosureBlock` rather than
                // `Arc<HeapValue>`; the formatter walked the legacy
                // `HeapValue::ClosureRaw` arm via `as_closure_handle()`.
                // The kinded read needs the §2.7.8 cell-storage rebuild
                // (`B7-closure-cells`) before the closure's `function_id`
                // can be reached without going through ValueWord.
                todo!(
                    "phase-2c — see ADR-006 §2.7.4 / §2.7.8: closure \
                     formatting needs kinded ClosureRaw read (§2.7.8 / Q10 \
                     B7-closure-cells extension)"
                );
            }
            HeapKind::Future => {
                // Future-id is an inline scalar payload on its `HeapKind`;
                // a `KindedSlot` flagged `Ptr(HeapKind::Future)` carries
                // the future id directly in `bits`.
                format!("[Future:{}]", bits)
            }
            HeapKind::NativeScalar => {
                // NativeScalar is `Copy`/inline (≤ 16 bytes); the kinded
                // surface for the `repr(C)` packed payload lands with
                // Wave 5c native-interop body migration.
                let _ = bits;
                todo!(
                    "phase-2c — see ADR-006 §2.7.4: NativeScalar formatting \
                     needs the kinded native-interop carrier (Wave 5c \
                     dispatch_native_interop_builtin)"
                );
            }
            HeapKind::FilterExpr => {
                // Wave-γ G-heap-filter-expr (ADR-006 §2.3 / §2.7.6 / Q8
                // amendment): FilterExpr trees are a transient query-DSL
                // value; they don't have a user-facing print form. Render
                // as an opaque tag for diagnostics.
                let _ = bits;
                "<filter_expr>".to_string()
            }
            HeapKind::Reference => {
                // ADR-006 §2.7.13 / Q14 (Wave 8 W8-T26, 2026-05-10):
                // Reference values are within-program data emitted by the
                // `MakeRef` family and consumed locally by `DerefLoad` /
                // `DerefStore` / `SetIndexRef`. They don't have a
                // user-facing print form; render as an opaque tag.
                let _ = bits;
                "<ref>".to_string()
            }
            HeapKind::SharedCell => {
                // Wave 8 W8-T25 (ADR-006 §2.7.12 / Q13 amendment,
                // 2026-05-10): `SharedCell` cell-pointer slots are an
                // interior-only cell-pointer shape; user-facing prints
                // go through `op_load_shared_local` /
                // `op_load_shared_capture` which strip the SharedCell
                // outer label and dispatch on the cell's interior kind.
                // Reaching this arm with a SharedCell-labeled slot at
                // a print surface is a kind-source bug. Render as an
                // opaque tag for diagnostics.
                let _ = bits;
                "<shared_cell>".to_string()
            }
            HeapKind::Iterator => {
                // W13-iterator-state (ADR-006 §2.7.16 / Q17,
                // 2026-05-10): iterator pipelines have no user-facing
                // print form — terminals materialise their elements;
                // an Iterator slot reaching the Display surface is
                // "still lazy" by construction. Render as an opaque
                // tag.
                let _ = bits;
                "<iterator>".to_string()
            }
            HeapKind::Deque => {
                // Wave 15 W15-deque (ADR-006 §2.7.19 / Q20,
                // 2026-05-10): DequeData stores a single
                // `VecDeque<Arc<HeapValue>>` items buffer. Render as
                // `Deque[elem1, elem2, ...]` front-to-back. SAFETY:
                // construction-side contract on `KindedSlot::from_deque`
                // — slot bits are `Arc::into_raw(Arc<DequeData>)`.
                let deque: &shape_value::heap_value::DequeData =
                    unsafe { &*(bits as *const shape_value::heap_value::DequeData) };
                self.format_deque(deque, depth)
            }
            HeapKind::Channel => {
                // Wave 15 W15-channel-rebuild (ADR-006 §2.7.20 / Q21,
                // 2026-05-10): channels are concurrency primitives
                // with no user-facing literal; render as an opaque
                // tag annotated with current queue length and closed
                // flag for diagnostics. SAFETY: construction-side
                // contract on `KindedSlot::from_channel` —
                // `Channel`-kind bits are
                // `Arc::into_raw(Arc<ChannelData>)`.
                let ch: &shape_value::heap_value::ChannelData =
                    unsafe { &*(bits as *const shape_value::heap_value::ChannelData) };
                let state = if ch.is_closed() { "closed" } else { "open" };
                format!("<channel:{}:{}>", state, ch.len())
            }
            HeapKind::PriorityQueue => {
                // Wave 15 W15-priority-queue (ADR-006 §2.7.18 / Q19,
                // 2026-05-10): PriorityQueueData stores i64
                // priorities heap-ordered in `Arc<TypedBuffer<i64>>`
                // (mirror of HashSetData with the keys buffer carrying
                // i64 instead of `Arc<String>`). Render as
                // `PriorityQueue[1, 3, 2, ...]` in heap-array order
                // (NOT sorted; for sorted output the user must call
                // `pq.toSortedArray()`). SAFETY: construction-side
                // contract on `KindedSlot::from_priority_queue`.
                let pq: &shape_value::heap_value::PriorityQueueData =
                    unsafe { &*(bits as *const shape_value::heap_value::PriorityQueueData) };
                self.format_priority_queue(pq)
            }
            HeapKind::Range => {
                // W15-range (ADR-006 §2.7.23 / Q24, 2026-05-10):
                // user-visible literal form `start..end` (exclusive)
                // or `start..=end` (inclusive). Matches the surface
                // syntax round-trip and the `HeapValue::Range` Display
                // impl in `heap_value.rs`. SAFETY: construction-side
                // contract on `KindedSlot::from_range` — Range-kind
                // bits are `Arc::into_raw(Arc<RangeData>)`.
                let r: &shape_value::heap_value::RangeData =
                    unsafe { &*(bits as *const shape_value::heap_value::RangeData) };
                if r.inclusive {
                    format!("{}..={}", r.start, r.end)
                } else {
                    format!("{}..{}", r.start, r.end)
                }
            }
            HeapKind::Result => {
                // Wave 14 W14-variant-codegen (ADR-006 §2.7.17 / Q18,
                // 2026-05-10): render as `Ok(<inner>)` /
                // `Err(<inner>)`. The inner-value formatter recurses
                // through the kinded value-formatter on the payload's
                // `KindedSlot`. SAFETY: construction-side contract on
                // `KindedSlot::from_result` — Result-kind bits are
                // `Arc::into_raw(Arc<ResultData>)`.
                let r: &shape_value::heap_value::ResultData =
                    unsafe { &*(bits as *const shape_value::heap_value::ResultData) };
                let inner = self.format_kinded_inner(&r.payload, depth + 1, true);
                if r.is_ok {
                    format!("Ok({})", inner)
                } else {
                    format!("Err({})", inner)
                }
            }
            HeapKind::Option => {
                // Wave 14 W14-variant-codegen (ADR-006 §2.7.17 / Q18,
                // 2026-05-10): render as `Some(<inner>)` / `None`.
                // SAFETY: construction-side contract on
                // `KindedSlot::from_option`.
                let o: &shape_value::heap_value::OptionData =
                    unsafe { &*(bits as *const shape_value::heap_value::OptionData) };
                if o.is_some {
                    let inner = self.format_kinded_inner(&o.payload, depth + 1, true);
                    format!("Some({})", inner)
                } else {
                    "None".to_string()
                }
            }
            // W17-concurrency (ADR-006 §2.7.25, 2026-05-11):
            // concurrency primitives have no user-facing literal —
            // render as opaque tags annotated with diagnostic state.
            // Mirror of Channel's `<channel:state:len>` shape.
            // SAFETY: construction-side contract on
            // `KindedSlot::from_mutex / from_atomic / from_lazy` —
            // bits are `Arc::into_raw(Arc<MutexData / AtomicData /
            // LazyData>)`.
            HeapKind::Mutex => {
                let _ = bits;
                "<mutex>".to_string()
            }
            HeapKind::Atomic => {
                let a: &shape_value::heap_value::AtomicData =
                    unsafe { &*(bits as *const shape_value::heap_value::AtomicData) };
                format!("<atomic:{}>", a.load())
            }
            HeapKind::Lazy => {
                let l: &shape_value::heap_value::LazyData =
                    unsafe { &*(bits as *const shape_value::heap_value::LazyData) };
                if l.is_initialized() {
                    "<lazy:initialized>".to_string()
                } else {
                    "<lazy:pending>".to_string()
                }
            }
            // W17-trait-object-storage (ADR-006 §2.7.24 / Q25.C,
            // 2026-05-11): a `dyn Trait` carrier renders as
            // `<dyn TraitName #schema>` for diagnostics. Pretty-print
            // via the boxed receiver's user-defined `Display`-style
            // method is the compiler-emission tier's concern (call
            // the trait's display method through the vtable); the
            // storage-tier formatter is diagnostic-only. SAFETY:
            // construction-side contract on
            // `KindedSlot::from_trait_object` — TraitObject-kind
            // bits are `Arc::into_raw(Arc<TraitObjectStorage>)`.
            HeapKind::TraitObject => {
                let t: &shape_value::heap_value::TraitObjectStorage = unsafe {
                    &*(bits as *const shape_value::heap_value::TraitObjectStorage)
                };
                let trait_name = t
                    .vtable
                    .trait_names
                    .first()
                    .map(|s| s.as_str())
                    .unwrap_or("?");
                // Wave 2 Round 4 D4 ckpt-3 (2026-05-14): t.value is now
                // `*const TypedObjectStorage` (raw); deref to read
                // schema_id. SAFETY: t holds one v2-raw refcount share so
                // t.value points to a live storage.
                let schema_id = unsafe { (*t.value).schema_id };
                format!("<dyn {} #{}>", trait_name, schema_id)
            }
            // W17-comptime-vm-dispatch (ADR-006 §2.7.26, 2026-05-12):
            // ModuleFn references render as `<module_fn:id>`. Same
            // inline-scalar pattern as Future — bits are the
            // module_fn_id directly, no heap dispatch.
            HeapKind::ModuleFn => {
                format!("<module_fn:{}>", bits)
            }
            // ADR-006 §2.7.22 amendment (Round 18 S3, 2026-05-13):
            // Matrix renders as `<Mat<number>:rows x cols>`; MatrixSlice
            // renders as a flat `Vec<number>[...]` over the projection
            // slice — preserves the pre-amendment user-facing print
            // shape. SAFETY: construction-side contract on
            // `KindedSlot::from_matrix` / `from_matrix_slice` — bits are
            // `Arc::into_raw(Arc<MatrixData>) as u64` /
            // `Arc::into_raw(Arc<MatrixSliceData>) as u64`.
            HeapKind::Matrix => {
                let m: &shape_value::heap_value::MatrixData =
                    unsafe { &*(bits as *const shape_value::heap_value::MatrixData) };
                format!("<Mat<number>:{}x{}>", m.rows, m.cols)
            }
            HeapKind::MatrixSlice => {
                let s: &shape_value::heap_value::MatrixSliceData =
                    unsafe { &*(bits as *const shape_value::heap_value::MatrixSliceData) };
                let slice = s.as_slice();
                let elems: Vec<String> =
                    slice.iter().map(|v| format_array_float(*v)).collect();
                format!("[{}]", elems.join(", "))
            }
        }
    }

    /// Format a v2 typed array (raw `*mut TypedArray<T>` pointer) as
    /// `[1, 2, 3]`. Element type comes from the heap-header `_pad` byte
    /// stamped at allocation time; element bits / kind come from the
    /// canonical kinded read helper
    /// (`v2_array_detect::read_element`).
    fn format_v2_typed_array(
        &self,
        view: &crate::executor::v2_handlers::v2_array_detect::V2TypedArrayView,
    ) -> String {
        use crate::executor::v2_handlers::v2_array_detect::read_element;
        let mut out = String::with_capacity(2 + view.len as usize * 4);
        out.push('[');
        for i in 0..view.len {
            if i > 0 {
                out.push_str(", ");
            }
            // Per-element rendering — the element kind is one of
            // Float64 / Int64 / Int32 / Bool per the v2 typed-array
            // contract. Format each through the canonical scalar arms.
            if let Some((bits, kind)) = read_element(view, i) {
                let elem_slot =
                    KindedSlot::new(ValueSlot::from_raw(bits), kind);
                out.push_str(&self.format_kinded_inner(&elem_slot, 0, true));
                std::mem::forget(elem_slot);
            } else {
                out.push_str("?");
            }
        }
        out.push(']');
        out
    }

    // V3-S5 ckpt-5 (2026-05-15): `format_typed_array` DELETED. The
    // function dispatched on `TypedArrayData::*` variants (deleted at
    // ckpt-1) per W12-typed-array-data-deletion audit §3.5 + §3.6. The
    // two callers (HeapKind::TypedArray arm in `format_kinded_inner` +
    // HeapValue::TypedArray arm in `format_heap_value`) are both updated
    // to a structured placeholder. Rebuild lands at ckpt-6 STRICT close
    // per the per-T v2-raw `TypedArray<T>` direct-access target.

    /// Apply a reference-resolver if configured, formatting the
    /// dereferenced target. Returns `<ref>` when no resolver is wired up.
    ///
    /// Reserved for the Phase-2c ref-kind landing — until refs gain
    /// their own NativeKind variant (or the kinded-ref ABI lands), this
    /// helper is unused by the dispatch path above and stays here so the
    /// resolver hook on `with_deref` keeps a coherent signature.
    #[allow(dead_code)]
    fn format_ref(&self, slot: &KindedSlot, depth: usize) -> String {
        if let Some(deref) = &self.deref_fn {
            if let Some(resolved) = deref(slot) {
                return self.format_kinded_inner(&resolved, depth + 1, true);
            }
        }
        "<ref>".to_string()
    }

    // ──────────────────────────────────────────────────────────────────────
    // TypedObject + HashMap helpers (ADR-006 §2.7.4 / §2.7.6 / Q8)
    // ──────────────────────────────────────────────────────────────────────

    /// Format a `TypedObjectStorage` as `{field1: val1, field2: val2}`.
    ///
    /// Field names come from the schema registry when the storage's
    /// `schema_id` resolves; otherwise positional `_0`, `_1` placeholders
    /// are used so the formatter degrades gracefully when the registry is
    /// not populated for a runtime-built object (e.g. anonymous record
    /// literals before schema registration).
    ///
    /// Each slot is reified as a `KindedSlot { slot, kind: field_kinds[i] }`
    /// and recursed through `format_kinded_inner` with `quote_strings = true`
    /// so nested string fields render `"…"`. Slots are *borrowed*: we do
    /// NOT clone the slot bits or transfer ownership; the parent
    /// `TypedObjectStorage` keeps holding all heap shares for the
    /// lifetime of `&self`.
    fn format_typed_object(&self, storage: &TypedObjectStorage, depth: usize) -> String {
        let schema = self.schema_registry.get_by_id(storage.schema_id as u32);
        // W18.0 (User 2026-05-23 Item 1): enum-typed TypedObjects render
        // as `Variant(payload)` / `Variant { field: v }` / `Variant`
        // rather than the synthetic `{__variant: N, __payload_0: ...}`
        // shape. Fallback to the generic record walk only when the
        // schema lookup genuinely fails (rare — runtime-built objects
        // without registered schema).
        if let Some(s) = schema {
            if s.is_enum() {
                return self.format_enum_typed_object(s, storage, depth);
            }
        }
        let n = storage.slots.len().min(storage.field_kinds.len());
        let mut out = String::with_capacity(2 + n * 8);
        out.push('{');
        for i in 0..n {
            if i > 0 {
                out.push_str(", ");
            }
            // Field name: prefer the schema-resolved name; fall back to
            // a positional placeholder so the formatter still produces
            // human-readable output for schema-less objects.
            let name: &str = schema
                .and_then(|s| s.fields.get(i).map(|f| f.name.as_str()))
                .unwrap_or("_");
            if name == "_" {
                out.push_str(&format!("_{}", i));
            } else {
                out.push_str(name);
            }
            out.push_str(": ");
            // Reify the slot as a borrowed `KindedSlot` for the recursive
            // formatter call. This carrier never owns a strong-count share
            // — it is dropped via `mem::forget` at the end of the loop
            // iteration so the parent storage retains every payload.
            let slot = ValueSlot::from_raw(storage.slots[i].raw());
            let kinded = KindedSlot::new(slot, storage.field_kinds[i]);
            let rendered = self.format_kinded_inner(&kinded, depth + 1, true);
            out.push_str(&rendered);
            std::mem::forget(kinded);
        }
        out.push('}');
        out
    }

    /// Format an enum-typed `TypedObjectStorage` as `Variant(payload)` /
    /// `Variant { field: v }` / `Variant` per W18.0 (User 2026-05-23
    /// Item 1).
    ///
    /// Reads slot 0 (`__variant` discriminator, I64) to recover the
    /// variant ID, then dispatches on the variant's [`EnumVariantKind`]
    /// to choose the render shape:
    ///
    /// - `Unit`   → `Red`
    /// - `Tuple`  → `Blue(42)` / `Pair(1, 2)`
    /// - `Struct` → `Point { x: 1, y: 2 }` (field names from
    ///              `EnumVariantKind::Struct(names)`)
    ///
    /// Falls through to the generic `{__variant: N, __payload_0: V}`
    /// shape ONLY if the variant ID fails to resolve (e.g. enum_info
    /// missing or discriminator out of range — should be rare since
    /// compiler emits matched discriminators per audit §2.D).
    fn format_enum_typed_object(
        &self,
        schema: &TypeSchema,
        storage: &TypedObjectStorage,
        depth: usize,
    ) -> String {
        let n = storage.slots.len().min(storage.field_kinds.len());
        // Slot 0 is `__variant` (I64) per `new_enum`'s layout.
        if n == 0 {
            return schema.name.clone();
        }
        let variant_id = storage.slots[0].raw() as i64;
        let info = schema
            .get_enum_info()
            .and_then(|ei| ei.variant_by_id(variant_id as u16));
        let Some(info) = info else {
            // Schema missing enum_info OR variant_id out of range.
            // Fall back to the generic record walk so the formatter
            // degrades visibly without lying about variant names.
            return self.format_typed_object_generic(schema, storage, depth);
        };

        // Render the i-th payload slot through the canonical kinded
        // formatter (same borrow pattern as `format_typed_object`).
        let render_payload = |i: usize, out: &mut String| {
            let slot_idx = i + 1; // skip __variant
            if slot_idx >= n {
                out.push_str("?");
                return;
            }
            let slot = ValueSlot::from_raw(storage.slots[slot_idx].raw());
            let kinded = KindedSlot::new(slot, storage.field_kinds[slot_idx]);
            let rendered = self.format_kinded_inner(&kinded, depth + 1, true);
            out.push_str(&rendered);
            std::mem::forget(kinded);
        };

        match &info.kind {
            EnumVariantKind::Unit => info.name.clone(),
            EnumVariantKind::Tuple => {
                let count = info.payload_fields as usize;
                let mut out = String::with_capacity(info.name.len() + 2 + count * 4);
                out.push_str(&info.name);
                out.push('(');
                for i in 0..count {
                    if i > 0 {
                        out.push_str(", ");
                    }
                    render_payload(i, &mut out);
                }
                out.push(')');
                out
            }
            EnumVariantKind::Struct(field_names) => {
                let count = field_names.len();
                let mut out = String::with_capacity(info.name.len() + 4 + count * 8);
                out.push_str(&info.name);
                if count == 0 {
                    // Defensive: a zero-field struct variant renders
                    // identically to a unit variant.
                    return out;
                }
                out.push_str(" { ");
                for (i, fname) in field_names.iter().enumerate() {
                    if i > 0 {
                        out.push_str(", ");
                    }
                    out.push_str(fname);
                    out.push_str(": ");
                    render_payload(i, &mut out);
                }
                out.push_str(" }");
                out
            }
        }
    }

    /// Generic `{field: value, ...}` walk extracted from
    /// `format_typed_object` so the enum-fallback path can reuse it
    /// without re-running the enum check.
    fn format_typed_object_generic(
        &self,
        schema: &TypeSchema,
        storage: &TypedObjectStorage,
        depth: usize,
    ) -> String {
        let n = storage.slots.len().min(storage.field_kinds.len());
        let mut out = String::with_capacity(2 + n * 8);
        out.push('{');
        for i in 0..n {
            if i > 0 {
                out.push_str(", ");
            }
            let name: &str = schema
                .fields
                .get(i)
                .map(|f| f.name.as_str())
                .unwrap_or("_");
            if name == "_" {
                out.push_str(&format!("_{}", i));
            } else {
                out.push_str(name);
            }
            out.push_str(": ");
            let slot = ValueSlot::from_raw(storage.slots[i].raw());
            let kinded = KindedSlot::new(slot, storage.field_kinds[i]);
            let rendered = self.format_kinded_inner(&kinded, depth + 1, true);
            out.push_str(&rendered);
            std::mem::forget(kinded);
        }
        out.push('}');
        out
    }

    /// Format a `PriorityQueueData` as `PriorityQueue[v1, v2, ...]` in
    /// heap-array order. Wave 15 W15-priority-queue (ADR-006 §2.7.18 /
    /// Q19) — i64-priority min-heap render shape (mirror of HashSet's
    /// render shape with the values column carrying i64 instead of
    /// quoted strings).
    fn format_priority_queue(
        &self,
        pq: &shape_value::heap_value::PriorityQueueData,
    ) -> String {
        let n = pq.heap.len();
        let mut out = String::with_capacity(16 + n * 4);
        out.push_str("PriorityQueue[");
        for (i, v) in pq.heap.iter().enumerate() {
            if i > 0 {
                out.push_str(", ");
            }
            out.push_str(&format!("{}", v));
        }
        out.push(']');
        out
    }

    /// Format a `HashSetData` as `{"a", "b", ...}`. Wave 13
    /// W13-hashset-rebuild (ADR-006 §2.7.15) — one-keyspace mirror of
    /// HashMap's render shape with the values column dropped.
    fn format_hashset(&self, set: &shape_value::heap_value::HashSetData) -> String {
        let n = set.keys.len();
        let mut out = String::with_capacity(2 + n * 6);
        out.push('{');
        for (i, k) in set.keys.iter().enumerate() {
            if i > 0 {
                out.push_str(", ");
            }
            out.push_str(&format!("\"{}\"", k));
        }
        out.push('}');
        out
    }

    /// Format a `DequeData` as `Deque[elem1, elem2, ...]` front-to-back.
    /// Wave 15 W15-deque (ADR-006 §2.7.19) — heterogeneous-element mirror
    /// of HashSet's render shape, dispatching per element through the
    /// canonical ADR-005 §1 single-discriminator `HeapValue` Display.
    fn format_deque(&self, deque: &shape_value::heap_value::DequeData, depth: usize) -> String {
        let n = deque.items.len();
        let mut out = String::with_capacity(8 + n * 4);
        out.push_str("Deque[");
        for (i, v) in deque.items.iter().enumerate() {
            if i > 0 {
                out.push_str(", ");
            }
            out.push_str(&self.format_heap_value(v, depth + 1));
        }
        out.push(']');
        out
    }

    /// Format a `HashMapKindedRef` as `{"key1": val1, "key2": val2}`.
    ///
    /// **Wave 2 Round 3b C2-joint ckpt-3 (2026-05-14):** full per-V
    /// keys/values walk. The keys buffer is `*mut TypedArray<*const StringObj>`;
    /// the values buffer is per-V (`*mut TypedArray<V>`). Each entry's
    /// value is rendered via the per-V Display shape (matching the
    /// HeapValue::HashMap Display impl at `heap_value.rs:hashmap_kref_display`).
    /// For TypedObject / TraitObject value variants we recurse through the
    /// canonical `format_typed_object` / opaque tag path. ADR-006 §2.7.24
    /// Q25.B SUPERSEDED + audit §C.4.
    fn format_hashmap(
        &self,
        map: &shape_value::heap_value::HashMapKindedRef,
        depth: usize,
    ) -> String {
        use shape_value::heap_value::HashMapKindedRef;
        let mut out = String::with_capacity(2 + map.len() * 8);
        out.push('{');

        // Walk keys buffer; per-V dispatch the value rendering.
        unsafe {
            // The keys buffer + values buffer come from each variant's inner Arc.
            // SAFETY: HashMapData<V>'s contract — keys is a live
            // *mut TypedArray<*const StringObj>; *(arc.values) is a live
            // TypedArray<V>.
            let render_key = |out: &mut String, i: usize, k: &str| {
                if i > 0 {
                    out.push_str(", ");
                }
                out.push('"');
                out.push_str(k);
                out.push_str("\": ");
            };

            // Read all keys generically.
            let read_keys = |keys_ptr: *const shape_value::v2::typed_array::TypedArray<
                *const shape_value::v2::string_obj::StringObj,
            >|
             -> Vec<&'static str> {
                let n = shape_value::v2::typed_array::TypedArray::len(keys_ptr) as usize;
                let mut ks = Vec::with_capacity(n);
                for i in 0..n {
                    let ptr =
                        shape_value::v2::typed_array::TypedArray::get_unchecked(keys_ptr, i as u32);
                    ks.push(shape_value::v2::string_obj::StringObj::as_str(ptr));
                }
                ks
            };

            match map {
                HashMapKindedRef::I64(arc) => {
                    let keys = read_keys(arc.keys);
                    for (i, k) in keys.iter().enumerate() {
                        render_key(&mut out, i, k);
                        let v = *(*arc.values).data.add(i);
                        out.push_str(&v.to_string());
                    }
                }
                HashMapKindedRef::F64(arc) => {
                    let keys = read_keys(arc.keys);
                    for (i, k) in keys.iter().enumerate() {
                        render_key(&mut out, i, k);
                        let v: f64 = *(*arc.values).data.add(i);
                        out.push_str(&v.to_string());
                    }
                }
                HashMapKindedRef::Bool(arc) => {
                    let keys = read_keys(arc.keys);
                    for (i, k) in keys.iter().enumerate() {
                        render_key(&mut out, i, k);
                        let v: u8 = *(*arc.values).data.add(i);
                        out.push_str(if v != 0 { "true" } else { "false" });
                    }
                }
                HashMapKindedRef::Char(arc) => {
                    let keys = read_keys(arc.keys);
                    for (i, k) in keys.iter().enumerate() {
                        render_key(&mut out, i, k);
                        let v: char = *(*arc.values).data.add(i);
                        out.push('\'');
                        out.push(v);
                        out.push('\'');
                    }
                }
                HashMapKindedRef::String(arc) => {
                    let keys = read_keys(arc.keys);
                    for (i, k) in keys.iter().enumerate() {
                        render_key(&mut out, i, k);
                        let v_ptr: *const shape_value::v2::string_obj::StringObj =
                            *(*arc.values).data.add(i);
                        let s = shape_value::v2::string_obj::StringObj::as_str(v_ptr);
                        out.push('"');
                        out.push_str(s);
                        out.push('"');
                    }
                }
                HashMapKindedRef::Decimal(arc) => {
                    let keys = read_keys(arc.keys);
                    for (i, k) in keys.iter().enumerate() {
                        render_key(&mut out, i, k);
                        let v_ptr: *const shape_value::v2::decimal_obj::DecimalObj =
                            *(*arc.values).data.add(i);
                        let d = (*v_ptr).value;
                        out.push_str(&format!("{}D", d));
                    }
                }
                HashMapKindedRef::TypedObject(arc) => {
                    let keys = read_keys(arc.keys);
                    for (i, k) in keys.iter().enumerate() {
                        render_key(&mut out, i, k);
                        let v_ref: &shape_value::heap_value::TypedObjectPtr =
                            &*(*arc.values).data.add(i);
                        if v_ref.is_null() {
                            out.push_str("null");
                        } else {
                            let storage = &**v_ref;
                            out.push_str(&self.format_typed_object(storage, depth + 1));
                        }
                    }
                }
                HashMapKindedRef::TraitObject(arc) => {
                    let keys = read_keys(arc.keys);
                    for (i, k) in keys.iter().enumerate() {
                        render_key(&mut out, i, k);
                        let v_ref: &shape_value::heap_value::TraitObjectPtr =
                            &*(*arc.values).data.add(i);
                        out.push_str(&format!("<trait_object:{:p}>", v_ref.as_ptr()));
                    }
                }
                HashMapKindedRef::HashMap(arc) => {
                    // Recursive carrier (Wave N hashmap-value-v-arm
                    // follow-up, cluster-2 closure-wave-C, 2026-05-16).
                    // Each inner element is itself a HashMapKindedRef;
                    // recurse through format_hashmap.
                    let keys = read_keys(arc.keys);
                    for (i, k) in keys.iter().enumerate() {
                        render_key(&mut out, i, k);
                        let inner_ref: &shape_value::heap_value::HashMapKindedRef =
                            &*(*arc.values).data.add(i);
                        out.push_str(&self.format_hashmap(inner_ref, depth + 1));
                    }
                }
            }
        }
        out.push('}');
        out
    }

    /// Format a `HeapValue` reference (the value side of `HashMapData`'s
    /// `TypedBuffer<Arc<HeapValue>>` and the heterogeneous element arm of
    /// `the-deleted-heterogeneous-element-carrier`). Dispatches via the ADR-005 §1
    /// single-discriminator `HeapValue` match.
    fn format_heap_value(&self, hv: &HeapValue, depth: usize) -> String {
        if depth > 50 {
            return "[max depth reached]".to_string();
        }
        match hv {
            HeapValue::String(s) => format!("\"{}\"", s),
            HeapValue::Decimal(d) => format!("{}D", d),
            HeapValue::BigInt(b) => b.as_ref().to_string(),
            HeapValue::Char(c) => format!("'{}'", c),
            HeapValue::Future(id) => format!("[Future:{}]", id),
            // V3-S5 ckpt-5: HeapValue::TypedArray outer arm DELETED at
            // ckpt-4 in lockstep with `TypedArrayData` enum + `TypedBuffer<T>`
            // wrapper layer per W12 audit §3.6. The arm is gone from the
            // exhaustive `match hv` (match remains exhaustive on remaining
            // HeapValue variants).
            //   HeapValue::TypedArray(arr) => self.format_typed_array(arr.as_ref(), depth),
            // Wave 2 Round 4 D4 ckpt-final-prime² (2026-05-14): TypedObjectPtr
            // derefs to &TypedObjectStorage; use `&**o` to bridge through the
            // outer `&` and the wrapper's Deref impl.
            HeapValue::TypedObject(o) => self.format_typed_object(&**o, depth),
            // Wave 2 Round 3b C2-joint ckpt-2 (2026-05-14): payload flipped
            // to `HashMapKindedRef`; pass the borrowed kinded ref directly.
            HeapValue::HashMap(m) => self.format_hashmap(m, depth),
            HeapValue::HashSet(s) => self.format_hashset(s.as_ref()),
            HeapValue::Deque(d) => self.format_deque(d.as_ref(), depth),
            HeapValue::DataTable(t) => format!("{}", t),
            HeapValue::Content(n) => {
                // W18.2 (R8 — output-adapter integration): mirror the
                // `format_heap_kind`'s `HeapKind::Content` arm. A
                // Content node reached via a HashMap-value /
                // heterogeneous-element walk renders through the
                // TerminalRenderer per the TERMINAL-as-default
                // print() dispatch.
                use shape_runtime::content_renderer::ContentRenderer;
                let renderer =
                    shape_runtime::renderers::terminal::TerminalRenderer::new();
                renderer.render(n)
            }
            HeapValue::Instant(t) => format!("<instant:{:?}>", t.elapsed()),
            HeapValue::IoHandle(h) => {
                let status = if h.is_open() { "open" } else { "closed" };
                format!("<io_handle:{}:{}>", h.path, status)
            }
            HeapValue::NativeView(v) => format!(
                "<{}:{}@0x{:x}>",
                if v.mutable { "cmut" } else { "cview" },
                v.layout.name,
                v.ptr
            ),
            HeapValue::TableView(tv) => format!("{}", tv),
            HeapValue::TaskGroup(tg) => {
                let kind_str = match tg.kind {
                    0 => "All",
                    1 => "Race",
                    2 => "Any",
                    3 => "Settle",
                    _ => "Unknown",
                };
                format!("[TaskGroup:{}({})]", kind_str, tg.task_ids.len())
            }
            HeapValue::NativeScalar(_) => "<native_scalar>".to_string(),
            HeapValue::Temporal(_) => "<temporal>".to_string(),
            HeapValue::ClosureRaw(_) => "<closure>".to_string(),
            HeapValue::FilterExpr(_) => "<filter_expr>".to_string(),
            HeapValue::Reference(_) => "<ref>".to_string(),
            HeapValue::Iterator(_) => "<iterator>".to_string(),
            HeapValue::Channel(c) => {
                let state = if c.is_closed() { "closed" } else { "open" };
                format!("<channel:{}:{}>", state, c.len())
            }
            HeapValue::PriorityQueue(p) => self.format_priority_queue(p.as_ref()),
            // W15-range (ADR-006 §2.7.23 / Q24, 2026-05-10): user-visible
            // literal form `start..end` / `start..=end` matching the
            // surface syntax round-trip.
            HeapValue::Range(r) => {
                if r.inclusive {
                    format!("{}..={}", r.start, r.end)
                } else {
                    format!("{}..{}", r.start, r.end)
                }
            }
            // Wave 14 W14-variant-codegen (ADR-006 §2.7.17 / Q18,
            // 2026-05-10): Result/Option carriers — render as
            // Ok/Err/Some/None tags. Inner is opaque at this fallback
            // path (the kinded formatter at the format_heap_kind site
            // handles full pretty-print).
            HeapValue::Result(r) => {
                if r.is_ok {
                    "Ok(<...>)".to_string()
                } else {
                    "Err(<...>)".to_string()
                }
            }
            HeapValue::Option(o) => {
                if o.is_some {
                    "Some(<...>)".to_string()
                } else {
                    "None".to_string()
                }
            }
            // W17-concurrency (ADR-006 §2.7.25, 2026-05-11):
            // concurrency-primitive carriers — render as opaque tags.
            HeapValue::Mutex(_) => "<mutex>".to_string(),
            HeapValue::Atomic(a) => format!("<atomic:{}>", a.load()),
            HeapValue::Lazy(l) => {
                if l.is_initialized() {
                    "<lazy:initialized>".to_string()
                } else {
                    "<lazy:pending>".to_string()
                }
            }
            // W17-trait-object-storage (ADR-006 §2.7.24 / Q25.C,
            // 2026-05-11): `dyn Trait` carrier — render as
            // `<dyn TraitName #schema>` for diagnostics. Pretty-print
            // via the boxed receiver's user-defined `Display`-style
            // method is the compiler-emission tier's concern.
            HeapValue::TraitObject(t) => {
                let trait_name = t
                    .vtable
                    .trait_names
                    .first()
                    .map(|s| s.as_str())
                    .unwrap_or("?");
                // Wave 2 Round 4 D4 ckpt-3 (2026-05-14): t.value is now
                // `*const TypedObjectStorage` (raw); deref to read
                // schema_id. SAFETY: t holds one v2-raw refcount share so
                // t.value points to a live storage.
                let schema_id = unsafe { (*t.value).schema_id };
                format!("<dyn {} #{}>", trait_name, schema_id)
            }
            // W17-comptime-vm-dispatch (ADR-006 §2.7.26, 2026-05-12).
            HeapValue::ModuleFn(id) => format!("<module_fn:{}>", id),
            // ADR-006 §2.7.22 amendment (Round 18 S3, 2026-05-13):
            // Matrix renders as `<Mat<number>:rows x cols>`. MatrixSlice
            // renders as a flat `[v1, v2, ...]` over the projection slice
            // — preserves the pre-amendment FloatSlice Display shape.
            HeapValue::Matrix(m) => format!("<Mat<number>:{}x{}>", m.rows, m.cols),
            HeapValue::MatrixSlice(s) => {
                let slice = s.as_slice();
                let elems: Vec<String> =
                    slice.iter().map(|v| format_array_float(*v)).collect();
                format!("[{}]", elems.join(", "))
            }
        }
    }
}

/// Format a number, removing unnecessary decimal places.
fn format_number(n: f64) -> String {
    if n.is_nan() {
        "NaN".to_string()
    } else if n.is_infinite() {
        if n.is_sign_positive() {
            "Infinity".to_string()
        } else {
            "-Infinity".to_string()
        }
    } else if n.fract() == 0.0 && n.abs() < 1e15 {
        // Integer-like floats: always show .0 to distinguish from int.
        format!("{}.0", n as i64)
    } else {
        n.to_string()
    }
}

/// Format a single float for inclusion in a typed-array element list.
/// Mirrors `format_number` but returns the integer-shape (`{n}.0`) for
/// whole-number floats that fit comfortably in `i64`.
fn format_array_float(v: f64) -> String {
    if v == v.trunc() && v.abs() < 1e15 {
        format!("{}.0", v as i64)
    } else {
        format!("{}", v)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::sync::Arc;

    fn create_test_registry() -> TypeSchemaRegistry {
        TypeSchemaRegistry::new()
    }

    #[test]
    fn test_format_inline_scalars() {
        let reg = create_test_registry();
        let formatter = ValueFormatter::new(&reg);

        assert_eq!(
            formatter.format_kinded(&KindedSlot::from_int(42)),
            "42"
        );
        assert_eq!(
            formatter.format_kinded(&KindedSlot::from_int(-100)),
            "-100"
        );
        assert_eq!(
            formatter.format_kinded(&KindedSlot::from_bool(true)),
            "true"
        );
        assert_eq!(
            formatter.format_kinded(&KindedSlot::from_bool(false)),
            "false"
        );
        assert_eq!(
            formatter.format_kinded(&KindedSlot::from_number(3.14)),
            "3.14"
        );
    }

    #[test]
    fn test_format_integer_like_float_shows_decimal_point() {
        let reg = create_test_registry();
        let formatter = ValueFormatter::new(&reg);
        assert_eq!(
            formatter.format_kinded(&KindedSlot::from_number(1.0)),
            "1.0"
        );
        assert_eq!(
            formatter.format_kinded(&KindedSlot::from_number(-5.0)),
            "-5.0"
        );
        assert_eq!(
            formatter.format_kinded(&KindedSlot::from_number(100.0)),
            "100.0"
        );
    }

    #[test]
    fn test_format_special_floats() {
        assert_eq!(format_number(f64::NAN), "NaN");
        assert_eq!(format_number(f64::INFINITY), "Infinity");
        assert_eq!(format_number(f64::NEG_INFINITY), "-Infinity");
    }

    #[test]
    fn test_format_string() {
        let reg = create_test_registry();
        let formatter = ValueFormatter::new(&reg);

        let s = KindedSlot::from_string_arc(Arc::new("hello".to_string()));
        assert_eq!(formatter.format_kinded(&s), "hello");
    }

    #[test]
    fn test_format_decimal() {
        let reg = create_test_registry();
        let formatter = ValueFormatter::new(&reg);

        let d = KindedSlot::from_decimal(Arc::new(rust_decimal::Decimal::from(42)));
        assert_eq!(formatter.format_kinded(&d), "42D");

        let d2 = KindedSlot::from_decimal(Arc::new(rust_decimal::Decimal::new(314, 2)));
        assert_eq!(formatter.format_kinded(&d2), "3.14D");
    }

    #[test]
    fn test_format_bigint() {
        let reg = create_test_registry();
        let formatter = ValueFormatter::new(&reg);

        let b = KindedSlot::from_bigint(Arc::new(123_i64));
        assert_eq!(formatter.format_kinded(&b), "123");
    }

    #[test]
    fn test_format_char() {
        let reg = create_test_registry();
        let formatter = ValueFormatter::new(&reg);

        let c = KindedSlot::from_char('A');
        assert_eq!(formatter.format_kinded(&c), "A");

        let c2 = KindedSlot::from_char('λ');
        assert_eq!(formatter.format_kinded(&c2), "λ");
    }

    /// r5c-2-β-CKPT-C u64-carrier-disambiguation regression guard.
    ///
    /// A `NativeKind::UInt64` slot is a genuine scalar `u64` — the
    /// formatter must render it as the unsigned integer value and must NOT
    /// dereference the bits as a `*const HeapHeader` (the pre-fix
    /// `as_v2_typed_array(bits, UInt64)` probe SIGSEGV'd on
    /// `let x: u64 = 18446744073709551615; print(x)`). Covers small,
    /// mid-range and `u64::MAX` values — `u64::MAX` is the load-bearing
    /// case: as a pointer it is non-canonical and would fault on deref;
    /// as a signed integer it would render `-1`.
    #[test]
    fn test_format_u64_scalar_renders_unsigned_no_deref() {
        let reg = create_test_registry();
        let formatter = ValueFormatter::new(&reg);

        for &v in &[0u64, 42u64, 1000u64, u64::MAX, u64::MAX - 1] {
            let slot = KindedSlot::new(
                ValueSlot::from_raw(v),
                NativeKind::UInt64,
            );
            assert_eq!(formatter.format_kinded(&slot), v.to_string());
            std::mem::forget(slot);
        }
    }

    /// A v2 typed array now flows through the kinded API under the
    /// `NativeKind::Ptr(HeapKind::TypedArray)` carrier kind (r5c-2-β-CKPT-C
    /// u64-carrier-disambiguation). The formatter's `HeapKind::TypedArray`
    /// arm detects the v2-raw `*mut TypedArray<T>` via the on-header kind +
    /// element-type byte and renders the elements.
    #[test]
    fn test_format_typed_array_via_ptr_carrier() {
        use shape_value::v2::typed_array::{TypedArray, ELEM_TYPE_I64};
        use crate::executor::v2_handlers::v2_array_detect::stamp_elem_type;

        let reg = create_test_registry();
        let formatter = ValueFormatter::new(&reg);

        let arr = TypedArray::<i64>::from_slice(&[7, 8, 9]);
        unsafe { stamp_elem_type(arr as *mut u8, ELEM_TYPE_I64) };
        let slot = KindedSlot::new(
            ValueSlot::from_raw(arr as usize as u64),
            NativeKind::Ptr(HeapKind::TypedArray),
        );
        assert_eq!(formatter.format_kinded(&slot), "[7, 8, 9]");
        std::mem::forget(slot);
        unsafe { TypedArray::<i64>::drop_array(arr) };
    }

    /// W18.2 (R8 — output-adapter integration): a Content-kind slot
    /// renders through the TerminalRenderer per the TERMINAL-as-default
    /// adapter selection for `print()`. Pre-W18.2 the arm called
    /// `ContentNode::Display` directly, which emits plain text with no
    /// ANSI styling; the rebuilt arm projects through the surviving
    /// 6-renderer infrastructure so styled spans surface escape codes
    /// at the print() sink.
    ///
    /// W18.3 retired c-string syntax entirely (supervisor D2 2026-05-24);
    /// rich content is now produced via the builder-pattern `Content.*`
    /// namespace constructors. This test constructs the `ContentNode`
    /// directly to exercise the renderer surface.
    #[test]
    fn test_format_content_via_terminal_renderer() {
        use shape_value::content::{Color, ContentNode, NamedColor};

        let reg = create_test_registry();
        let formatter = ValueFormatter::new(&reg);

        // Plain text Content node — TerminalRenderer leaves un-styled
        // spans alone, so the surface should contain the literal text.
        let node = ContentNode::plain("hello");
        let arc = std::sync::Arc::new(node);
        let bits = std::sync::Arc::into_raw(arc) as u64;
        let slot = KindedSlot::new(
            ValueSlot::from_raw(bits),
            NativeKind::Ptr(HeapKind::Content),
        );
        let out = formatter.format_kinded(&slot);
        assert!(
            out.contains("hello"),
            "TerminalRenderer should surface plain Content text; got {:?}",
            out
        );
        std::mem::forget(slot);
        unsafe {
            let _ = std::sync::Arc::from_raw(
                bits as *const shape_value::content::ContentNode,
            );
        }

        // Styled Content node — TerminalRenderer should emit ANSI
        // escape sequences (`\x1b[...]`) for the bold-red span. This is
        // the load-bearing W18.2 evidence: pre-rebuild the arm called
        // `ContentNode::Display` which produces NO `\x1b[...]` bytes.
        let styled = ContentNode::plain("hi")
            .with_bold()
            .with_fg(Color::Named(NamedColor::Red));
        let arc2 = std::sync::Arc::new(styled);
        let bits2 = std::sync::Arc::into_raw(arc2) as u64;
        let slot2 = KindedSlot::new(
            ValueSlot::from_raw(bits2),
            NativeKind::Ptr(HeapKind::Content),
        );
        let styled_out = formatter.format_kinded(&slot2);
        assert!(
            styled_out.contains("\x1b["),
            "TerminalRenderer should emit ANSI escape codes for styled \
             Content nodes; got {:?}",
            styled_out
        );
        assert!(styled_out.contains("hi"));
        std::mem::forget(slot2);
        unsafe {
            let _ = std::sync::Arc::from_raw(
                bits2 as *const shape_value::content::ContentNode,
            );
        }
    }
}