polydat_core/kernel/

state.rs

// Copyright 2024-2026 Jonathan Shook
// SPDX-License-Identifier: Apache-2.0

//! PolydatKernel: a compiled Polydat Kernel pairing an `Arc<PolydatProgram>` with a PolydatState.

use std::collections::HashMap;
use std::sync::Arc;

use super::engines::{PolydatState, SharedCellEntry};
use super::program::PolydatProgram;
use super::{InputDef, WireSource};
use crate::ast::{PolydatNode, Value};

/// Auto-create `SharedCell`s for `shared`-modifier outputs that
/// have a backing input slot on this kernel. Call once at
/// construction so subsequent `materialize_wiring_from_outer` from inner
/// kernels can pick the cells up via `outer.shared_cell(idx)`
/// without mutating outer.
///
/// A `shared` output without a backing input slot is skipped,
/// since without a slot there's nothing to share. The DSL compiles
/// every `shared` binding to an input slot, its register
/// (scope_model.md §6).
fn seed_shared_cells(state: &mut PolydatState, program: &PolydatProgram) {
    for name in program.shared_outputs() {
        let Some(idx) = program.find_input(name) else {
            continue;
        };
        if state.shared_cell(idx).is_some() {
            continue;
        } // already seeded
        let init_value = state.get_input(idx);
        // `make_shared_cell` allocates the next bit position
        // from this scope's intent-dirty vector and constructs
        // the cell with the right validity-tracking handles
        // (cross_fiber_invalidation.md §3.1). The cell carries
        // its own intent_dirty Arc + bit so any fiber writing
        // through it publishes dirty intent to this scope's
        // vector — descendant kernels that later attach via
        // `materialize_wiring_from_outer` inherit the same
        // handles automatically.
        let cell = state.core.make_shared_cell(init_value);
        state.attach_shared_cell(idx, cell);
    }
}

/// Boundary-adapter helper: when the outer-scope binding's
/// runtime value type doesn't match the inner kernel's
/// declared slot type, consult the catalog
/// (`compile::assembly::boundary_adapter`) and apply the adapter
/// if one exists. Returns the (possibly adapted) value to set
/// in the slot.
///
/// When no catalog entry exists for the (from, to) type pair,
/// returns the value unchanged with a warning via the audit log,
/// and the caller's write refuses the mismatched value as a
/// `WriteError::FromParent` (input_variance.md §7).
///
/// Spec: `expression_engine.md` §5.4 (boundary adapter
/// polyfills); `composition_substrate.md` T2 (typed-mismatch
/// healing extended to synthesis sites).
pub(crate) fn adapt_boundary_value(
    slot_name: &str,
    slot_type: crate::ast::PortType,
    value: Value,
) -> Value {
    let value_type = value.port_type();
    if value_type == slot_type {
        return value;
    }
    // `Value::None` is the "absent" sentinel — pass through
    // without trying to adapt; downstream None-propagation
    // (none_semantics.md Rule 1) handles it.
    if matches!(value, Value::None) {
        return value;
    }
    match crate::compile::assembly::boundary_adapter(value_type, slot_type) {
        Some(adapter) => {
            // Adapter::eval reads inputs[0..N], writes outputs[0..M].
            // For the boundary case, every adapter is 1→1.
            let inputs = vec![value];
            let mut outputs = vec![Value::None];
            adapter.eval(&inputs, &mut outputs);
            outputs.remove(0)
        }
        None => {
            // Actionable warning surface — `Ext` as the slot
            // type is by far the most common landing point
            // here (it's the fallback when the auto-extern
            // inferrer couldn't resolve the binding's RHS
            // output type from the assembler or the surface
            // AST). The advice differs based on the slot's
            // declared type because the fix differs too:
            //
            // - Slot is `Ext`: the workload likely meant a
            //   primitive type. The inferrer surfaced its
            //   gap; the right fix is a registry update or
            //   an explicit `extern NAME: <type>` declaration
            //   so the slot's type matches the producer's.
            // - Slot is concrete: there's a real type
            //   mismatch the catalog can't bridge. The
            //   author wrote `extern NAME: <wrong_type>` or
            //   the consumer's declared port type doesn't
            //   match the actual cross-scope contract.
            let hint = if slot_type == crate::ast::PortType::Ext {
                "  - The slot's type is `Ext` (extension type), so the value the outer \
                 scope supplies has no adapter into it. Options:\n\
                 \x20   * Add an explicit `extern {slot_name}: <type>` declaration in the \
                 receiving scope so the slot's type is pinned at the source.\n\
                 \x20   * If the binding is set from YAML sugar (e.g. `set: {{ {slot_name}: \"{{ outer }}\" }}`), \
                 the desugared `const {slot_name} := \"{{ outer }}\"` evaluates to a Str — \
                 use the bare form `set: {{ {slot_name}: outer }}` to pass the original \
                 type through, or quote-encode if the consumer expects a string.\n\
                 \x20   * The slot takes its type from the compiled output of the binding \
                 that feeds it, so a node registered without an output `PortType` lands \
                 here — declare one on the node."
            } else {
                "  - The slot's declared type and the cross-scope provider's type don't match. \
                 Options:\n\
                 \x20   * Change the `extern {slot_name}: <type>` declaration to match the \
                 producer's actual type.\n\
                 \x20   * Convert at the consumer: wrap the read with the matching `as_*` / \
                 `*_from_*` adapter for the slot type."
            };
            let hint = hint.replace("{slot_name}", slot_name);
            crate::library::support::audit::warn(&format!(
                "boundary adapter: no catalog entry for {value_type:?} → {slot_type:?} \
                 at slot '{slot_name}'; passing value as-is (will likely produce a wire \
                 error or coerce silently at first read)\n\
                 {hint}"
            ));
            value
        }
    }
}

/// Write a value the binder copied from the parent into the child's
/// input `index` (input_variance.md §7). A declared input takes the
/// value as it is or refuses it; an input whose type the compiler
/// inferred takes a value the boundary adapter catalog converts into
/// its type. A refused copy is an error naming the input, both types,
/// and the parent as the value's source.
fn copy_from_parent(
    child: &mut dyn crate::kernel::Kernel,
    index: usize,
    name: &str,
    slot_type: crate::ast::PortType,
    value: Value,
) -> Result<(), crate::KernelError> {
    use crate::kernel::WriteError;
    let got = value.port_type();
    let value = match child.input_type_origin(name) {
        Some(crate::kernel::TypeOrigin::Inferred) if !value.satisfies_slot(slot_type) => {
            adapt_boundary_value(name, slot_type, value)
        }
        _ => value,
    };
    child.set_input_at(index, value).map_err(|e| {
        crate::KernelError::Write(match e {
            WriteError::TypeMismatch { slot, expected, .. } => WriteError::FromParent {
                slot,
                expected,
                got,
            },
            other => other,
        })
    })
}

/// A compiled Polydat Kernel: an `Arc<PolydatProgram>` plus one `PolydatState`.
///
/// ## Invariants
///
/// - **Scope coordinates are always populated.** After construction
///   `scope_coords` reflects this kernel's place in the comprehension
///   chain: leaf-first list of [`super::ScopeCoord`] from the kernel's
///   own scope up through every enclosing comprehension. Root-scope
///   kernels (no parent) start with their own coords (or empty).
///   `Self::materialize_wiring_from_outer` re-computes the path so post-bind it
///   includes the outer's chain. Consumers (presentation layer,
///   inspector, scope-aware diagnostics) call
///   [`Self::scope_coordinates`] without needing to walk the scope
///   tree themselves. See the scope model design document (`docs/design/scope_model.md`).
pub struct PolydatKernel {
    program: Arc<PolydatProgram>,
    state: PolydatState,
    /// Number of init-time constants folded during compilation.
    pub constants_folded: usize,
    /// Leaf-first scope-coordinate path. Maintained as an
    /// invariant — see struct docs.
    scope_coords: Vec<super::ScopeCoord>,
    /// Rule 2 write-through bindings carried alongside the kernel
    /// for per-cycle commit (subcontext_construction.md §3.1, §5).
    /// Each entry pairs an export name (which the kernel exposes as
    /// a cell-bound input slot) with the synthetic `__write_<name>`
    /// source output the rewrite emitted. Empty for the vast
    /// majority of kernels; populated by the subcontext builder when
    /// result-bindings or `shared` collisions trigger Rule 2.
    write_throughs: Vec<KernelWriteThrough>,
    /// Shared cells visible at this kernel's scope but with no
    /// matching input slot on this kernel's program (closure-
    /// binding economy elided the slot). Carried as a transit
    /// channel so a descendant whose program DOES declare the
    /// slot can attach the same cell handle.
    ///
    /// `materialize_wiring_from_outer` is the single writer: when binding
    /// child to parent, it attaches every parent-visible cell
    /// to whatever child input slot exists, and stores the
    /// remaining unattached cells here for further propagation.
    /// The activity layer never sees this directly — the typed
    /// `ScopeKernel::shared_cells_in_scope` returns the merged
    /// view.
    transit_cells: Vec<SharedCellEntry>,
}

/// Local data shape of a write-through binding
/// the kernel carries. Mirrors `subcontext::WriteThroughBinding`
/// but lives at this layer so [`PolydatKernel`] avoids a cyclic
/// dependency on the subcontext module (which already depends on
/// kernel types).
#[derive(Debug, Clone)]
pub(crate) struct KernelWriteThrough {
    pub export_name: String,
    pub source_output: String,
}

/// Type-stability boundary for shared-cell WRITE-THROUGHS
/// (scope_model.md §6.1). A matching type passes; a lossless
/// widening heals through the catalog adapter; an UNHEALABLE
/// mismatch — narrowing, kind change — is an `Err` AT THE WRITE
/// naming the cell, its declared type, the incoming type, and the
/// producing binding. Without this, a result-binding writing (say)
/// an F64 into a U64-declared cell would flip the cell's runtime
/// type, and a bridge compiled against the declared type would
/// panic `expected U64, got F64` at a READ tiers away from the
/// cause. Shared by both write-through commit paths
/// ([`PolydatKernel::commit_write_throughs`] and the subcontext
/// `ScopeKernel` variant).
pub(crate) fn check_write_through_type(
    export_name: &str,
    source_output: &str,
    slot_type: crate::ast::PortType,
    value: Value,
) -> Result<Value, String> {
    use crate::ast::PortType as P;
    let got = value.port_type();
    if got == slot_type || matches!(value, Value::None) {
        return Ok(value);
    }
    // Only LOSSLESS conversions may heal automatically at the CELL
    // boundary: numeric widenings, plus the Bool↔U64 0/1 convention
    // (GK comparisons and predicates produce U64 0/1, so a predicate
    // result written into a Bool cell is natural authoring). The
    // general auto-adapter catalog also carries narrowing entries
    // (F64→U64 truncation) for other boundaries — deliberately NOT
    // consulted here: a narrowing write silently changes semantics,
    // so it must be the author's explicit `trunc_u64(...)` /
    // `round_u64(...)`.
    let widening = matches!(
        (got, slot_type),
        (P::U64, P::F64)
            | (P::I64, P::F64)
            | (P::U32, P::F64)
            | (P::I32, P::F64)
            | (P::F32, P::F64)
            | (P::U32, P::U64)
            | (P::U32, P::I64)
            | (P::I32, P::I64)
            | (P::U64, P::Bool)
            | (P::Bool, P::U64),
    );
    if widening && let Some(adapter) = crate::compile::assembly::boundary_adapter(got, slot_type) {
        let inputs = vec![value];
        let mut outputs = vec![Value::None];
        adapter.eval(&inputs, &mut outputs);
        return Ok(outputs.remove(0));
    }
    Err(format!(
        "type-stable cell violation: shared cell `{export_name}` is \
         declared {slot_type:?}, but the result binding \
         `{export_name} := …` (via `{source_output}`) produced a \
         {got:?} value ({val}). A cell keeps ONE type for life — \
         declare the cell with a matching initializer (e.g. \
         `shared {export_name} := 1.0` for f64), or narrow \
         explicitly with `trunc_u64(...)` / `round_u64(...)`.",
        val = value.to_display_string(),
    ))
}

impl std::fmt::Debug for PolydatKernel {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PolydatKernel")
            .field("program", &self.program)
            .finish()
    }
}

impl PolydatKernel {
    /// Create with explicit input definitions. `strict` selects
    /// strict-mode const folding (config-wire violations become
    /// errors).
    ///
    /// Returns `Err` when a compile-constant step cannot be computed,
    /// or for a strict-mode violation.
    // Thirteen parameters describe one thing — a compiled program
    // definition. A params struct would reshape the construction
    // protocol rather than clean up a lint — this fn is the
    // walled-off construction chokepoint (subcontext/mod.rs).
    #[allow(clippy::too_many_arguments)]
    pub(crate) fn new_with_inputs(
        nodes: Vec<Box<dyn PolydatNode>>,
        wiring: Vec<Vec<WireSource>>,
        input_defs: Vec<InputDef>,
        coord_count: usize,
        output_map: HashMap<String, (usize, usize)>,
        output_order: Vec<String>,
        const_outputs: std::collections::HashSet<String>,
        output_modifiers: HashMap<String, crate::dsl::ast::BindingModifier>,
        source: &str,
        context: &str,
        log: Option<&mut crate::dsl::events::CompileEventLog>,
        strict: bool,
        ledger: Arc<crate::kernel::CompileLedger>,
    ) -> Result<Self, crate::compile::assembly::AssemblyError> {
        let mut program = PolydatProgram::with_inputs(
            nodes,
            wiring,
            input_defs,
            coord_count,
            output_map,
            output_order,
            source,
            context,
            ledger,
        );
        // Mark const bindings before the fold runs, so strict mode can
        // find them.
        for name in &const_outputs {
            program.mark_const_output(name);
        }
        // Install output modifiers BEFORE fold so the lifecycle
        // classifier sees `volatile`. Without this, a `volatile`
        // binding's producing node would default to CompileConst,
        // fold would replace it with a literal, and the workload's
        // `volatile` declaration would lose its "exclude from
        // program identity" guarantee.
        for (name, modifier) in &output_modifiers {
            program.set_output_modifier(name, *modifier);
        }
        let constants_folded = if strict {
            program.fold_init_constants_strict(log, true)?
        } else {
            program.fold_init_constants_with_log(log)?
        };
        let program = Arc::new(program);
        let mut state = program.create_state();
        // Populate buffers for folded constants so get_constant() works.
        // Seeded, not set: construction writes no input, so nothing
        // is invalidated by it.
        let dummy = vec![0u64; program.coord_count()];
        state.seed_inputs(&dummy);
        // Seed buffers for folded *constant* nullary nodes so
        // `get_constant()` works. Skip `Nondeterministic` nullary nodes
        // (live-metric readers, entropy, clocks): they have no
        // compile-time value, and pulling one here would evaluate it
        // against an empty/absent runtime source — mirrors the same
        // skip the fold pass makes (`fold_init_constants`).
        for name in program.output_names() {
            if let Some(&(node_idx, _)) = program.output_map.get(name)
                && program.wiring[node_idx].is_empty()
                && !matches!(
                    program.nodes[node_idx].purity(),
                    crate::ast::Purity::Nondeterministic { .. }
                )
            {
                state.pull(&program, name);
            }
        }
        seed_shared_cells(&mut state, &program);
        state.core.seed_output_cells(&program);
        let mut k = Self {
            program,
            state,
            constants_folded,
            scope_coords: Vec::new(),
            write_throughs: Vec::new(),
            transit_cells: Vec::new(),
        };
        k.refresh_scope_coordinates();
        Ok(k)
    }

    /// Mark a set of output names as inherited (cascade-only)
    /// on the program. Must be called immediately after
    /// construction, before the `Arc<PolydatProgram>` is shared.
    /// Panics if the Arc has other references.
    pub fn mark_inherited_outputs<I>(&mut self, names: I)
    where
        I: IntoIterator<Item = String>,
    {
        let program = Arc::get_mut(&mut self.program)
            .expect("mark_inherited_outputs called after program was shared");
        for name in names {
            program.mark_inherited(&name);
        }
    }

    /// Bake Rule 2 write-through bindings onto the underlying
    /// program. Must be called immediately after construction,
    /// before the `Arc<PolydatProgram>` is shared. Panics if the Arc
    /// has other references. Also updates this kernel's own
    /// `write_throughs` field so the just-built kernel matches
    /// what later `from_program` callers will see.
    ///
    /// The single legitimate caller is the subcontext builder's
    /// finalize step (subcontext_construction.md §3, step 9). Any
    /// kernel built from the program inherits the bindings via
    /// `from_program`'s automatic seeding.
    pub(crate) fn bake_write_throughs(&mut self, write_throughs: Vec<KernelWriteThrough>) {
        let program = Arc::get_mut(&mut self.program)
            .expect("bake_write_throughs called after program was shared");
        program.set_write_throughs(write_throughs.clone());
        self.write_throughs = write_throughs;
    }

    /// Construct a fresh kernel from a previously-compiled
    /// `Arc<PolydatProgram>`. The state is freshly created and seeded
    /// the same way the standard new-kernel path does, so callers
    /// can immediately `set_input(...)` for externs and execute.
    ///
    /// # Cache-and-rehydrate role
    ///
    /// This is the **rehydrate** primitive of the cache-and-
    /// rehydrate pattern documented on [`Self::for_iteration`].
    /// External callers use `for_iteration` (which composes
    /// this with parent-chain wiring); this method itself is
    /// `pub(crate)` because hydrating a kernel without
    /// installing parent-chain wiring would skip the load-
    /// bearing materialization step.
    ///
    /// Used by the cache-and-rebind path the host drives
    /// (scope_model.md §9): a phase scope compiles once, caches its
    /// program, and instantiates a fresh kernel per `run_phase` call
    /// against the cached program.
    pub(crate) fn from_program(program: Arc<PolydatProgram>) -> Self {
        let mut state = program.create_state();
        // Populate buffers for folded constants so get_constant()
        // works on the new kernel, as `new_with_inputs` seeds them
        // after the fold.
        let dummy = vec![0u64; program.coord_count()];
        state.seed_inputs(&dummy);
        for name in program.output_names() {
            if let Some(&(node_idx, _)) = program.output_map.get(name)
                && program.wiring[node_idx].is_empty()
            {
                state.pull(&program, name);
            }
        }
        seed_shared_cells(&mut state, &program);
        state.core.seed_output_cells(&program);
        // Auto-seed the kernel's Rule 2 write-through bindings
        // from the program. The program is the single source of
        // truth; any kernel built from it inherits the same
        // bindings.
        let write_throughs = program.write_throughs().to_vec();
        let mut k = Self {
            program,
            state,
            constants_folded: 0, // already folded; see program contents
            scope_coords: Vec::new(),
            write_throughs,
            transit_cells: Vec::new(),
        };
        k.refresh_scope_coordinates();
        k
    }

    /// The shared immutable program.
    pub fn program(&self) -> &Arc<PolydatProgram> {
        &self.program
    }

    /// Attach Rule 2 write-through bindings to this kernel
    /// (subcontext_construction.md §5). Per-cycle eval calls
    /// [`Self::commit_write_throughs`] after the inputs flowing
    /// into the result-binding expressions are written; the
    /// commit walks each binding, pulls its synthetic source
    /// output, and stores the value back through the cell-bound
    /// input slot for `export_name`. Because the slot was
    /// attached to the parent's `SharedCell` at
    /// `materialize_wiring_from_outer` time, the write fans through.
    ///
    /// `SubcontextBuilder::finalize` bakes these onto the program and
    /// `from_program` seeds them on every kernel built from it; per-cycle code never mutates
    /// them.
    // Used only by the subcontext tests: `from_program` auto-seeds
    // write-throughs on every kernel built from the program, so
    // nothing else needs a post-construction setter. Kept for the
    // test surface; dead-code-lint silenced.
    #[allow(dead_code)]
    pub(crate) fn set_write_throughs(&mut self, write_throughs: Vec<KernelWriteThrough>) {
        self.write_throughs = write_throughs;
    }

    /// The Rule 2 write-through bindings carried by this kernel.
    /// Empty for kernels without result-bindings or `shared`
    /// collisions.
    #[allow(dead_code)]
    pub(crate) fn write_throughs(&self) -> &[KernelWriteThrough] {
        &self.write_throughs
    }

    /// Per-cycle commit (subcontext_construction.md §5). Pulls each write-
    /// through's synthetic source output and stores its value
    /// through the corresponding cell-bound input slot for the
    /// declared export name. Reads of that name in the parent or
    /// in sibling kernels share the same cell and observe the
    /// write on the next read.
    ///
    /// TYPE-STABLE (scope_model.md §6.1): a cell keeps
    /// ONE type for life. Each pending value passes a typed
    /// boundary —
    /// matching types pass, a catalog adapter heals (e.g. the lossless
    /// U64→F64 widening), and an UNHEALABLE mismatch (narrowing, kind
    /// change) is an `Err` at THIS write site naming the cell, its
    /// declared type, the incoming type, and the producing binding —
    /// never a silent type flip that a compile-time-typed bridge trips
    /// over tiers later. Explicit narrowing is the author's job via
    /// `trunc_u64(...)` / `round_u64(...)`.
    ///
    /// No-op when the kernel carries no write-throughs.
    pub fn commit_write_throughs(&mut self) -> Result<(), String> {
        let debug = crate::library::debug_nodes_enabled();
        if self.write_throughs.is_empty() {
            if debug {
                crate::library::support::audit::debug(
                    "commit_write_throughs: kernel has zero bindings — no-op",
                );
            }
            return Ok(());
        }
        // Two-pass: pull each value first (each pull mutates the
        // state), collect, then write to the slot. Avoids
        // overlapping borrows on `self.state` / `self.program`.
        // For cell-bound slots `set_input` writes through the
        // cell (single-register: cell IS the slot's register);
        // for non-cell slots it updates the local register.
        let mut pending: Vec<(usize, Value)> = Vec::with_capacity(self.write_throughs.len());
        let bindings = self.write_throughs.clone();
        if debug {
            crate::library::support::audit::debug(&format!(
                "commit_write_throughs: {} binding(s)",
                bindings.len()
            ));
        }
        for wt in &bindings {
            let Some(idx) = self.program.find_input(&wt.export_name) else {
                if debug {
                    crate::library::support::audit::debug(&format!(
                        "commit_write_throughs: skip {} — no input slot",
                        wt.export_name
                    ));
                }
                continue;
            };
            let value = self.state.pull(&self.program, &wt.source_output).clone();
            if debug {
                crate::library::support::audit::debug(&format!(
                    "commit_write_throughs: {} → {}",
                    wt.export_name,
                    value.to_display_string()
                ));
            }
            // Type-stability boundary (doc above): match passes,
            // catalog adapters heal (widening), anything else errors
            // HERE — at the write, with the full story.
            let slot_type = self
                .program
                .input_port_type_by_idx(idx)
                .expect("write-through idx resolved from find_input");
            let value =
                check_write_through_type(&wt.export_name, &wt.source_output, slot_type, value)?;
            pending.push((idx, value));
        }
        for (idx, value) in pending {
            self.state.set_input(idx, value);
        }
        Ok(())
    }

    /// Set source schemas on the program (called by the compiler).
    pub fn set_cursor_schemas(&mut self, schemas: Vec<crate::iteration::source::SourceSchema>) {
        Arc::get_mut(&mut self.program)
            .expect("set_cursor_schemas must be called before program is shared")
            .set_cursor_schemas(schemas);
    }

    /// Record the resource scope of the tree the program belongs to,
    /// before the program is shared.
    pub(crate) fn set_resources(&mut self, resources: crate::resource::ResourceScope) {
        Arc::get_mut(&mut self.program)
            .expect("set_resources must be called before program is shared")
            .set_resources(resources);
    }

    /// Record the digest of the graph the compiler resolved as the
    /// program's graph identity, before the program is shared.
    pub(crate) fn set_graph_identity(&mut self, digest: [u8; 32]) {
        Arc::get_mut(&mut self.program)
            .expect("set_graph_identity must be called before program is shared")
            .set_graph_identity(digest);
    }

    /// Record the const bindings, before the program is shared.
    pub(crate) fn set_const_inits(&mut self, inits: Vec<crate::kernel::ConstInit>) {
        Arc::get_mut(&mut self.program)
            .expect("set_const_inits must be called before program is shared")
            .set_const_inits(inits);
    }

    /// Record how much of the graph the build fused into native cones,
    /// before the program is shared.
    pub(crate) fn set_cone_mode(&mut self, mode: crate::compile::cone::JitMode) {
        Arc::get_mut(&mut self.program)
            .expect("set_cone_mode must be called before program is shared")
            .set_cone_mode(mode);
    }

    /// Attach the parsed AST as live program metadata. Called by
    /// every DSL compile entry point immediately after the
    /// assembler produces the kernel, while the program Arc is
    /// still uniquely owned. The subscope synthesizer queries this
    /// to integrate parent bindings' matter into child scopes.
    pub fn set_ast(&mut self, ast: Arc<crate::dsl::ast::PolydatFile>) {
        Arc::get_mut(&mut self.program)
            .expect("set_ast must be called before program is shared")
            .set_ast(ast);
    }

    /// Attach compiled traversals and producers (for_traversal.md). Called by
    /// the DSL compiler while the program Arc is still uniquely owned.
    pub fn set_traversals(
        &mut self,
        traversals: Vec<crate::dsl::traversal::Traversal>,
        producers: Vec<crate::dsl::traversal::Producer>,
    ) {
        Arc::get_mut(&mut self.program)
            .expect("set_traversals must be called before program is shared")
            .set_traversals(traversals, producers);
    }

    /// The per-fiber mutable evaluation state.
    pub fn state(&mut self) -> &mut PolydatState {
        &mut self.state
    }

    /// Read-only access to the kernel's evaluation state. Used by
    /// callers (e.g. the scope-init pass) that need to inspect
    /// pulled values without consuming the kernel.
    pub fn state_ref(&self) -> &PolydatState {
        &self.state
    }

    /// Convenience: set coordinate inputs on the owned state.
    pub fn set_inputs(&mut self, coords: &[u64]) {
        // Only the coordinates: a value past them would land in an
        // extern's slot, which only a named write sets.
        let n = coords.len().min(self.program.coord_count());
        self.state.set_inputs(&coords[..n]);
    }

    /// Set an extern by name on the owned state. The compiled kernels
    /// offer the same call, so a host drives every engine alike.
    pub fn set_input(&mut self, name: &str, value: Value) -> Result<(), crate::kernel::WriteError> {
        let idx = self.program.find_input(name).ok_or_else(|| {
            crate::kernel::WriteError::UnknownWire {
                key: name.to_string(),
                known: self.program.input_names(),
            }
        })?;
        self.set_input_at(idx, value)
    }

    /// [`Self::set_input`] by input index, as `find_input` numbers them.
    /// The one write rule of every engine: the value satisfies the
    /// declared type or is `None`, and a coordinate is not written here.
    pub fn set_input_at(
        &mut self,
        idx: usize,
        value: Value,
    ) -> Result<(), crate::kernel::WriteError> {
        if self.program.input_kind(idx) == Some(crate::kernel::InputKind::Const) {
            return Err(crate::kernel::WriteError::ConstSlot {
                slot: self
                    .program
                    .input_name_by_idx(idx)
                    .map(|n| n.to_string())
                    .unwrap_or_default(),
            });
        }
        self.write_input_at(idx, value)
    }

    /// [`Self::set_input_at`] as initialization writes it: a const's
    /// slot is accepted (`Kernel::init`).
    pub(crate) fn init_input_at(
        &mut self,
        idx: usize,
        value: Value,
    ) -> Result<(), crate::kernel::WriteError> {
        self.write_input_at(idx, value)
    }

    /// The typed write every input write shares.
    fn write_input_at(
        &mut self,
        idx: usize,
        value: Value,
    ) -> Result<(), crate::kernel::WriteError> {
        use crate::kernel::WriteError;
        let Some(name) = self.program.input_name_by_idx(idx) else {
            return Err(WriteError::UnknownWire {
                key: format!("wire[{idx}]"),
                known: self.program.input_names(),
            });
        };
        if self.program.input_kind(idx) == Some(crate::kernel::InputKind::Coordinate) {
            return Err(WriteError::CoordinateSlot {
                slot: name.to_string(),
            });
        }
        if let Some(declared) = self.program.input_port_type_by_idx(idx)
            && !value.satisfies_slot(declared)
        {
            return Err(WriteError::TypeMismatch {
                slot: name.to_string(),
                expected: declared,
                got: value.port_type(),
            });
        }
        self.state.set_input(idx, value);
        Ok(())
    }

    /// Narrow a cursor to one partition: its `Ext` slot and six scalar
    /// projections are set, as `cursor_partition::narrow_cursor` does.
    /// The compiled kernels offer the same call. The partitions a
    /// cursor's `over` clause denotes are in `program().cursor_schemas()`
    /// when the compiler could resolve them, or from
    /// `cursor_partition::cursor_over_partitions` otherwise.
    pub fn set_cursor(
        &mut self,
        name: &str,
        partition: &crate::iteration::cursor_partition::Partition,
    ) -> Result<(), crate::kernel::WriteError> {
        if self
            .program
            .find_input(&format!("{name}__cursor"))
            .is_none()
        {
            return Err(crate::kernel::WriteError::UnknownWire {
                key: format!("{name}__cursor"),
                known: self
                    .program
                    .cursor_schemas()
                    .iter()
                    .map(|s| s.name.clone())
                    .collect(),
            });
        }
        crate::iteration::cursor_partition::narrow_cursor(
            &self.program,
            &mut self.state,
            name,
            partition,
        );
        Ok(())
    }

    /// Read an input value by name. Cell-aware: cell-bound
    /// slots return the cell's current value.
    pub fn get_input(&self, name: &str) -> Option<Value> {
        self.program
            .find_input(name)
            .map(|idx| self.state.get_input(idx))
    }

    /// Evaluate `output_name`'s cone and borrow the result, which is
    /// the one thing this reader has over
    /// [`Kernel::pull`](crate::Kernel::pull): no clone. The value lives
    /// in the kernel's own buffer, so the borrow ties to `&mut self`
    /// and ends at the next write.
    ///
    /// Named `pull_ref` and not `pull` deliberately. An inherent `pull`
    /// here would shadow the trait's, which returns an owned `Value`,
    /// and the same expression would mean different things depending on
    /// whether the caller held a `PolydatKernel` or a `Box<dyn Kernel>`
    /// — silently, since both sides answer `as_u64` and the rest.
    pub fn pull_ref(&mut self, output_name: &str) -> &Value {
        self.state.pull(&self.program, output_name)
    }

    /// [`Self::pull_ref`] by the output's index rather than its name,
    /// skipping the name resolution. Pair with
    /// [`PolydatProgram::output_index`] resolved once at bind time so a
    /// per-cycle reader pays no name hash on the hot path.
    pub fn pull_ref_at(&mut self, output_idx: usize) -> &Value {
        self.state.pull_by_index(&self.program, output_idx)
    }

    /// Every output, as one read: each volatile step the outputs reach
    /// is evaluated once for all of them, as a compiled kernel's `eval`
    /// runs every step once.
    pub(crate) fn eval_read(&mut self) {
        self.state.rearm_volatile();
        for name in self.program.output_names() {
            let _ = self.state.pull_in_read(&self.program, name);
        }
    }

    /// Copy `self`'s currently-set input-slot values into `child`'s
    /// input slots by name.
    ///
    /// Companion to the internal `materialize_wiring_from_outer`
    /// pass that runs as part of `build_subscope`. That pass
    /// walks the parent's outputs; this method walks the parent's
    /// **inputs** — so cascade-extern'd names that the parent
    /// inherited from *its* parent reach `child` too, rather than
    /// stopping at the parent and silently leaving `child`'s
    /// matching slot at its default.
    ///
    /// `Value::None` inputs are skipped (no point overwriting a
    /// child's possibly-set default with absence). Inputs whose
    /// name has no matching slot on `child` are skipped silently
    /// — they're not the child's concern.
    ///
    /// This is the kernel-chain operation that lets cascade-extern
    /// propagate transitively across multi-level scope chains. Each
    /// scope builder calls it after `build_subscope` finishes.
    pub fn propagate_inputs_into(&self, child: &mut PolydatKernel) {
        let names = self.program.input_names();
        for name in names {
            let Some(outer_value) = self.get_input(&name) else {
                continue;
            };
            if matches!(outer_value, Value::None) {
                continue;
            }
            let cloned = outer_value.clone();
            let Some(inner_idx) = child.program.find_input(&name) else {
                continue;
            };
            child.state.set_input(inner_idx, cloned);
        }
    }

    /// Return the names of the inputs.
    pub fn input_names(&self) -> Vec<String> {
        self.program.input_names()
    }

    /// Return the names of all available output variates.
    pub fn output_names(&self) -> Vec<&str> {
        self.program.output_names()
    }

    /// Read the value of a named output that was folded to a constant.
    ///
    /// Underlying primitive — prefer [`Self::lookup`] for
    /// scope-aware name resolution. This method only succeeds for
    /// constant-folded outputs whose buffer is populated; it
    /// returns `None` for auto-passthrough outputs (where the
    /// value lives in the input slot) and for cycle-dependent
    /// outputs that haven't been pulled.
    ///
    /// A `const` captured at initialization answers from its slot, which
    /// initialization writes, so its value is there before anything
    /// pulls its output.
    pub fn get_constant(&self, name: &str) -> Option<&Value> {
        let val = match self.program.const_inits().iter().find(|c| c.name == name) {
            Some(c) => self.state.core.inputs.get(c.slot_index)?,
            None => {
                let (node_idx, port_idx) = self.program.output_map.get(name)?;
                &self.state.core.buffers[*node_idx][*port_idx]
            }
        };
        if matches!(val, Value::None) {
            None
        } else {
            Some(val)
        }
    }

    /// Find every `const` output whose initialization left the
    /// buffer as `Value::None`. The L2.f sub-axiom in
    /// composition_substrate.md describes this case: an
    /// intermediate-layer `const X := <expr>` whose RHS yields
    /// None falls through silently to the outer scope's X via
    /// the conditional-shadow semantics in none_semantics.md.
    /// This method is the substrate's "did silent fall-through
    /// occur" query — strict-mode callers (per L2.f's
    /// strict-mode hardening note) use it to escalate the
    /// silent fall-through to a hard error.
    ///
    /// Returns the const-output names whose buffers are
    /// `Value::None` after the scope-init pull. Empty `Vec`
    /// means every const materialised to a defined value.
    /// Polydat itself does not implement the strict-mode
    /// policy — it provides this query and the caller decides
    /// whether to surface a diagnostic.
    ///
    /// Call only after `materialize_wiring_from_outer` has run
    /// (i.e., after the kernel is fully constructed and
    /// scope-init pulls have completed). Calling before
    /// scope-init returns a misleading result.
    pub fn find_l2f_violations(&self) -> Vec<String> {
        self.program
            .const_outputs
            .iter()
            .filter(|name| {
                // A const captured at initialization holds its fallback in
                // its own output, so what shows a silent fall-through is
                // its expression's value, `__init_<name>`.
                let own = self
                    .program
                    .const_inits()
                    .iter()
                    .find(|c| &c.name == *name)
                    .map_or(name.as_str(), |c| c.source.as_str());
                self.program
                    .output_map
                    .get(own)
                    .map(|(node_idx, port_idx)| {
                        matches!(&self.state.core.buffers[*node_idx][*port_idx], Value::None)
                    })
                    .unwrap_or(false)
            })
            .cloned()
            .collect()
    }

    /// Look up a name in this kernel's scope.
    ///
    /// The canonical scope-aware read (scope_model.md §5): own-scope folded outputs
    /// shadow inherited extern values, with auto-passthrough
    /// outputs falling through to the input slot transparently.
    ///
    /// Resolution order:
    /// 1. Folded output buffer (compile-time constants).
    /// 2. Cell-aware input read (covers extern values bound via
    ///    `materialize_wiring_from_outer`, auto-passthrough outputs from
    ///    `input ...: u64` / `extern`, and `shared`-cell-backed
    ///    slots — the cell is queried on every read so reads
    ///    pick up writes from sibling kernels intrinsically).
    ///
    /// Returns `None` when the name doesn't resolve in either
    /// tier or when the resolved value is `Value::None` (unset).
    ///
    /// Returns `Value` (owned, not borrowed) because shared-cell
    /// reads acquire a Mutex and clone out — there's no
    /// long-lived borrow into the cell. For non-shared slots
    /// the clone is cheap (Value's Clone is Arc-based for
    /// vectors, primitive copy otherwise).
    ///
    /// This is the single read API for scope-aware name lookup
    /// and is cell-aware by default — callers don't need to
    /// know whether a name is shared or not.
    pub fn lookup(&self, name: &str) -> Option<Value> {
        if let Some(v) = self.get_constant(name)
            && !matches!(v, Value::None)
        {
            return Some(v.clone());
        }
        if let Some(idx) = self.program.find_input(name) {
            let v = self.state.read_input_value(idx);
            return if matches!(v, Value::None) {
                None
            } else {
                Some(v)
            };
        }
        // Dotted names follow the established field-access wire
        // convention (`a.b` lowers to the wire `a__b`), so a
        // text-context reference like `{q.cursor.idx}` resolves
        // through the same flattening the DSL compiler applies.
        if name.contains('.') {
            let flattened = name.replace('.', "__");
            return self.lookup(&flattened);
        }
        None
    }

    /// Materialize a sub-scope kernel under this kernel as
    /// parent. THE single primitive for parent → child kernel
    /// construction with cell propagation.
    ///
    /// The parent supervises sub-context construction
    /// (subcontext_construction.md §8, SC1): only the parent has the
    /// right to materialize a sub-scope
    /// kernel. The parent owns the cell cascade, the value-copy
    /// path for outputs, the scope-coordinate plumbing, and any
    /// pre-bind iter-var injection. Every other code path that
    /// needs a parent-bound child kernel routes through here —
    /// the underlying `materialize_wiring_from_outer` step is private to
    /// this impl and not callable from anywhere else in the
    /// crate.
    ///
    /// `iter_bindings` lets callers inject iter-var values
    /// before binding, matching `for_iteration`'s contract:
    /// values must be installed BEFORE
    /// `refresh_scope_coordinates` runs so the own-coord
    /// snapshot sees them.
    ///
    /// # Side-channel lock
    ///
    /// `materialize_wiring_from_outer` is private to this impl block, so
    /// a caller cannot bypass the typed primitive; the compile-fail
    /// case `crates/polydat/tests/ui/seal/materialize_wiring_is_private.rs` holds
    /// that at the compiler.
    pub(crate) fn materialize_subscope(
        &self,
        program: Arc<PolydatProgram>,
        iter_bindings: &[(String, Value)],
    ) -> PolydatKernel {
        Self::materialize_subscope_under(self, program, iter_bindings)
    }

    /// [`Self::materialize_subscope`] under a parent of any engine.
    ///
    /// The binder reads seven things off a parent — the cells in scope,
    /// its output names, whether a name has an input slot, that name's
    /// binding modifier, its current value, its broadcast cell, and its
    /// scope-coordinate path — and every one of them is on the `Kernel`
    /// trait, so the parent can be a kernel of any engine.
    ///
    /// The child is an interpreter kernel, for the crate's
    /// interpreter-only paths (`for_iteration`, comprehension
    /// evaluation). A host builds a child on its parent's engine with
    /// [`crate::kernel::subcontext::PolydatMatter::build_under`] or
    /// [`crate::kernel::bind_under`].
    pub(crate) fn materialize_subscope_under(
        outer: &dyn crate::kernel::Kernel,
        program: Arc<PolydatProgram>,
        iter_bindings: &[(String, Value)],
    ) -> PolydatKernel {
        let mut child = PolydatKernel::from_program(program);
        child.bind_under(outer, iter_bindings);
        child
    }

    /// Produce a fresh kernel that mirrors this one's program
    /// AND its full shared-cell view (own input-slot cells +
    /// transit cells). The cell handles are Arc-shared; the
    /// returned kernel reads/writes the same cells as `self`.
    ///
    /// Used by [`Self::fork_kernel`] and [`Self::cell_scope_snapshot`].
    /// The snapshot must reflect the LIVE kernel's cell view, not just
    /// its program shape, otherwise Rule 2 in a builder's finalize
    /// over it sees no cells and produces no write-throughs.
    pub(crate) fn snapshot_with_cells(&self) -> PolydatKernel {
        let mut snapshot = PolydatKernel::from_program(self.program.clone());
        snapshot.transit_cells = self.transit_cells.clone();
        // Re-attach every cell from `self`'s input slots onto
        // the matching input slot of `snapshot`. Slot indices
        // and names are isomorphic since the program is the
        // same Arc.
        for name in self.program.input_names() {
            let Some(idx) = self.program.find_input(&name) else {
                continue;
            };
            let Some(cell) = self.state.shared_cell(idx) else {
                continue;
            };
            snapshot.state.attach_shared_cell(idx, cell);
        }
        snapshot
    }

    /// A new kernel over the same program with this one's state:
    /// `snapshot_with_cells`'s shared cells and transit cells, and this
    /// kernel's input values, current outputs, scope path, and write-
    /// throughs, so a scope-init constant materialized here is current
    /// in the fork without running again (`Kernel::fork`).
    pub(crate) fn fork_kernel(&self) -> PolydatKernel {
        let mut fork = self.snapshot_with_cells();
        let inputs = self.state.core.inputs.len();
        for idx in 0..inputs {
            if self.state.shared_cell(idx).is_some() {
                continue;
            }
            fork.state.core.inputs[idx] = self.state.core.inputs[idx].clone();
        }
        fork.state.core.buffers = self.state.core.buffers.clone();
        fork.state.core.node_clean = self.state.core.node_clean.clone();
        fork.scope_coords = self.scope_coords.clone();
        fork.write_throughs = self.write_throughs.clone();
        fork.constants_folded = self.constants_folded;
        fork
    }

    /// Public form of `Self::snapshot_with_cells`: a fresh kernel
    /// mirroring this one's program and full shared-cell view (own
    /// input-slot cells + transit cells, Arc-shared — the snapshot
    /// reads/writes the SAME cells as `self`). For holding a scope's
    /// cell cascade past the point where the kernel itself is consumed
    /// (e.g. an executor keeping a phase-activation scope view alive
    /// for later `build_subscope` binds, after `OpBuilder` has taken
    /// the activation kernel by value). Non-cell state is fresh — this
    /// is a SCOPE view, not a value snapshot.
    pub fn cell_scope_snapshot(&self) -> PolydatKernel {
        self.snapshot_with_cells()
    }

    /// Materialize this kernel's input-slot wiring against `outer`'s
    /// exports, driven by the matter at construction
    /// (wire_materialization.md, "Materialization gradient"). Reads `self.program`'s
    /// matter (its extern / shared / coord declarations) to decide
    /// each slot's materialization gradient — cell-attach for
    /// shared and computed outputs, value-copy for passthrough,
    /// transit-forward for cells with no matching local slot.
    ///
    /// Private; the only sanctioned construction path is
    /// `build_subscope` (which calls `materialize_subscope`
    /// internally). External callers don't see
    /// this operation directly.
    /// Write `iter_bindings` into this kernel's own slots and wire the
    /// rest from `outer`. The order matters: the values must be in
    /// before `refresh_scope_coordinates` runs, so the own-coord
    /// snapshot sees them.
    fn bind_under(&mut self, outer: &dyn crate::kernel::Kernel, iter_bindings: &[(String, Value)]) {
        for (var, value) in iter_bindings {
            if let Some(idx) = self.program.find_input(var) {
                self.state.set_input(idx, value.clone());
            }
        }
        self.materialize_wiring_from_outer(outer);
    }

    /// Wire and initialize. The interpreter's own subscope path cannot
    /// return an error, so a const that fails when the child is
    /// initialized fails the construction here.
    fn materialize_wiring_from_outer(&mut self, outer: &dyn crate::kernel::Kernel) {
        if let Err(e) = Self::wire_child_under(self, outer) {
            panic!("{e}");
        }
    }

    /// Wire `child` from `outer`: the child program's resource scope
    /// joined to the parent's, the cell cascade, the outputs the child
    /// imports, its scope-init consts, and its coordinate path.
    ///
    /// Both sides are `dyn Kernel`, so a child of any engine binds
    /// under a parent of any engine. It stays an associated function
    /// of the interpreter's kernel type because the seal is on this
    /// module — nothing outside the crate reaches the wiring, whichever
    /// kernel it is wiring.
    pub(crate) fn wire_child_under(
        child: &mut dyn crate::kernel::Kernel,
        outer: &dyn crate::kernel::Kernel,
    ) -> Result<(), crate::KernelError> {
        use crate::kernel::interp::Lookup as _;
        // Step 0 — the resource scope. A child compiled on its own
        // resolves lookups through the parent's scope, and the join
        // precedes the scope-init consts, which may read a resource.
        child
            .resources()
            .join(outer.resources())
            .map_err(crate::KernelError::Resources)?;
        // Step 1 — typed shared-cell cascade. Compute every
        // cell visible at the outer scope: cells on outer's
        // own input slots (its `shared X := …` declarations
        // and any cells inherited from its own ancestors that
        // landed on slots) PLUS outer's transit cells (cells
        // outer carried forward as a transit because outer's
        // program had no matching slot). Together these are
        // every cell a descendant could legitimately bind to.
        //
        // Attach each cell to whichever child input slot
        // exists; drop cells whose name the child has already
        // attached itself to (idempotent reattach with the
        // same handle is a no-op, but a name collision with
        // a DIFFERENT cell would be a contract violation).
        // Cells with no matching child slot are stored on the
        // child as transit so a deeper descendant can pick
        // them up (wire_materialization.md, form 1).
        let outer_scope = crate::kernel::interp::KernelLookup::new(outer);
        let outer_cells = outer.cells_in_scope();
        let mut transit_forward: Vec<SharedCellEntry> = Vec::new();
        let mut attached_names: std::collections::HashSet<String> =
            std::collections::HashSet::new();
        // Names this scope declares as a local authoritative
        // output — `const NAME := …`, whether folded at compile
        // time or computed once at initialization after wiring
        // and then fixed for the scope's lifetime. Either way
        // this scope owns the binding for `NAME` over its
        // subtree (wire_materialization.md, "Local-authoritative
        // shadow"), so any transit cell carrying
        // a stale value from a grandparent must be suppressed:
        // without that suppression, step 1's blanket cell-attach
        // would short-circuit step 2's value-copy from
        // `outer.lookup(name)` (already-in-attached_names
        // guard), and descendants would read the transit cell's
        // value instead of the local declaration's.
        //
        // The two forms are uniform from the chain's
        // perspective: both produce a single authoritative
        // value visible to descendants via the standard
        // `extern NAME` lookup. The distinction is internal
        // (when the value is computed) and doesn't affect the
        // shadowing semantics.
        let local_finals: std::collections::HashSet<String> = child
            .output_names()
            .into_iter()
            // `const_outputs()` filters output_modifiers for CONST,
            // so checking the modifier directly is the same query —
            // single source of truth for "this scope authoritatively
            // owns NAME via a const binding."
            .filter(|n| child.output_modifier(n).is_const())
            .collect();
        for entry in outer_cells {
            // A local final on this scope is the canonical writer
            // for the name; the transit cell from above is stale.
            // Drop it on the floor — don't attach to a slot we
            // own, don't transit-forward to descendants. They'll
            // see this scope's final via the standard step-2
            // value-copy or cell-attach path.
            if local_finals.contains(entry.name.as_str()) {
                continue;
            }
            if child.input_index(&entry.name).is_some() {
                child.bind_input_cell(&entry.name, entry.cell.clone());
                attached_names.insert(entry.name);
            } else {
                transit_forward.push(entry);
            }
        }
        child.set_transit_cells(transit_forward);

        // Step 2 — the read invariant (wire_materialization.md,
        // forms 2–5). For each output on
        // outer that matches an input slot on inner:
        //
        // - If the name also exists as an *input slot* on
        //   outer (i.e. it's a passthrough output backed by
        //   an input slot — `extern X: T`, `shared X :=
        //   <lit>`, coord inputs like `cycle`), the canonical
        //   storage is the input slot. Step 1 already
        //   attached the cell for shared / iter-var slots;
        //   for plain passthrough we value-copy the current
        //   slot value. Cycle-derived coord propagation goes
        //   through the explicit set_inputs path on the
        //   inner kernel, not through this bind step.
        //
        // - Otherwise the name is a truly-computed output
        //   (node-backed, no input slot on outer). Attach
        //   outer's output broadcast cell to inner's input
        //   slot. Outer's `pull` writes the freshly computed
        //   value through the cell; inner reads through
        //   `read_input` transparently, so the read invariant
        //   holds (wire_materialization.md, form 3).
        for name in outer.output_names() {
            if attached_names.contains(&name) {
                continue;
            }
            let Some(inner_idx) = child.input_index(&name) else {
                continue;
            };
            let outer_has_slot = outer.input_index(&name).is_some();
            // Conditional-shadow composition (none_semantics.md,
            // "Conditional-shadow semantics for `const`"): when outer's output
            // is a `const` binding, ALWAYS go through outer.lookup
            // (value-copy), never through the broadcast cell. The
            // const's output buffer may be Value::None (Rule 1
            // None-propagation, e.g. set:'s `const X := "{Y}"` when
            // Y is unbound); outer.lookup applies the two-tier read
            // so None falls through to outer's wired-from-grandparent
            // input slot, giving us the canonical chain-walked
            // value. Cell-attaching the None-valued buffer would
            // defeat that fall-through.
            //
            // Const outputs are effectively-const for the scope's
            // lifetime (evaluation_model.md, "Const Binding
            // Contract") — value-copy is semantically
            // equivalent to cell-attach and avoids the dynamic-cell
            // overhead.
            let outer_is_const =
                outer.output_modifier(&name) == crate::dsl::ast::BindingModifier::CONST;
            // Slot's declared port type — needed for
            // boundary-adapter dispatch. `find_input` returned
            // `Some(inner_idx)` above, so `input_port_type` on
            // the same name is a program-shape invariant; a
            // `None` here means the program is malformed.
            let inner_slot_type = child
                .input_port_type(&name)
                .expect("input index resolved but no declared port type");
            // A coordinate is positioned with `set_inputs`, never copied.
            if inner_idx < child.coord_count() {
                continue;
            }
            if outer_has_slot || outer_is_const {
                // Both conditions force the chain-walking value-copy
                // path (see the const rationale above; an outer input
                // slot likewise reads through outer.lookup so the
                // grandparent fall-through applies).
                if let Some(value) = outer_scope.lookup(&name) {
                    copy_from_parent(child, inner_idx, &name, inner_slot_type, value)?;
                }
            } else if let Some(cell) = outer.output_cell(&name) {
                child.bind_input_cell(&name, cell);
                attached_names.insert(name.to_string());
            } else if let Some(value) = outer_scope.lookup(&name) {
                copy_from_parent(child, inner_idx, &name, inner_slot_type, value)?;
            } else if let Some(value) =
                crate::dsl::factories::resolve_extern(&name, inner_slot_type)
            {
                // Registered extern resolver: outer chain has no
                // binding; a host-registered resolver provides one
                // (wire_materialization.md, form 5).
                copy_from_parent(child, inner_idx, &name, inner_slot_type, value)?;
            }
        }

        // Step 3 — initialize the child: now that step 2 has written
        // the enclosing scope's values into its inputs, every const is
        // evaluated once and fixed for the child's life (Kernel::init).
        // Before step 4, whose own-coordinate snapshot reads consts.
        child.init()?;

        // Step 4 — scope-coordinates plumbing. Path is now
        // `[own] ++ outer.scope_coordinates()`. Refresh own
        // (extern values may have just been populated above),
        // then prepend outer's frozen path.
        let outer_path = outer.scope_coordinates().to_vec();
        child.extend_scope_coordinates(&outer_path);
        Ok(())
    }

    /// Advance this kernel's broadcast
    /// state: pull every output that has an attached
    /// broadcast cell, forcing the eval cone to recompute
    /// against current inputs and writing the fresh value
    /// through the cell. Descendant kernels with input slots
    /// cell-attached to these outputs then observe the
    /// current value on their next `read_input` without any
    /// per-fiber-write coordination.
    ///
    /// Intended to run once per cycle on each per-fiber outer
    /// kernel whose outputs are visible to inner scopes. The
    /// alternative — validity-bit + auto-pull-on-stale-read
    /// — would put the trigger fully inside the Polydat engine
    /// (so inner reads transparently fetch fresh values),
    /// but requires the engine to track upstream dependencies
    /// across the cell boundary. This eager-broadcast form
    /// is simpler and lives entirely within the kernel's own
    /// surface: callers ask the kernel to advance its
    /// broadcasts; the kernel does the pulls; cells receive
    /// the values.
    pub fn advance_broadcasts(&mut self) {
        let program = self.program.clone();
        let n_outputs = program.output_names().len();
        for i in 0..n_outputs {
            if self
                .state
                .core
                .output_cells
                .get(i)
                .and_then(|c| c.as_ref())
                .is_some()
            {
                let name = program.output_names()[i].to_string();
                // Some workload-level bindings
                // intentionally panic at specific cycles
                // (`testkit_throw_at(cycle, threshold, ...)` for the
                // resume-test fixture). Those panics belong to
                // the per-op evaluation path — the op's wire
                // resolution pulls the same wire and the
                // cascade catches the panic as a per-op error.
                // Here in the eager-broadcast pre-step we
                // suppress panics so the descendant pull path
                // remains the canonical error-handling site.
                let state = &mut self.state;
                let prog = &program;
                let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                    state.pull(prog, &name);
                }));
            }
        }
    }

    /// Carry `cells` forward for this kernel's descendants, replacing
    /// what it carried. The binder writes what the parent had and this
    /// kernel holds no slot for; the compiled engines keep the same
    /// list in their extern table.
    pub fn replace_transit_cells(&mut self, cells: Vec<SharedCellEntry>) {
        self.transit_cells = cells;
    }

    /// Every shared cell visible at this kernel's scope —
    /// own input slots' attached cells unioned with the
    /// transit cells inherited from ancestors. The typed
    /// `ScopeKernel::shared_cells_in_scope` delegates here.
    ///
    /// Used by `materialize_wiring_from_outer` to compute the parent's
    /// full visible cell set and propagate it to the child.
    /// Public for the typed surface; semantics are the same
    /// as the typed accessor.
    pub fn shared_cells_in_scope(&self) -> Vec<SharedCellEntry> {
        let mut by_name: std::collections::HashMap<String, SharedCellEntry> =
            std::collections::HashMap::new();
        for entry in &self.transit_cells {
            by_name.insert(entry.name.clone(), entry.clone());
        }
        for name in self.program.input_names() {
            let Some(idx) = self.program.find_input(&name) else {
                continue;
            };
            let Some(cell) = self.state.shared_cell(idx) else {
                continue;
            };
            // `find_input` just returned `Some(idx)`; the program
            // shape guarantees a declared port type for that idx.
            let port_type = self
                .program
                .input_port_type(&name)
                .expect("input index resolved but no declared port type");
            by_name.insert(
                name.clone(),
                SharedCellEntry {
                    name,
                    port_type,
                    cell,
                },
            );
        }
        by_name.into_values().collect()
    }

    /// Construct a per-iteration kernel: clone `canonical`'s
    /// program, bind it to `parent`'s scope, and pre-load every
    /// `(var, value)` binding into the corresponding input slot.
    ///
    /// # Cache-and-rehydrate pattern
    ///
    /// `for_iteration` is the public entry point for the
    /// **cache-and-rehydrate pattern** a host builds on:
    /// compile a scope's program **once**, then hydrate many
    /// per-instance kernels from it — one per iteration tuple,
    /// per fiber, per scenario-tree visit. The program is
    /// immutable substance (the `Arc<PolydatProgram>`); each
    /// hydrated kernel carries its own state (the input slot
    /// values for this iteration).
    ///
    /// The pattern's three load-bearing properties:
    ///
    /// 1. **Compile cost amortizes.** Polydat source → typed program
    ///    is paid once per canonical scope, not per iteration
    ///    or per fiber. The compiled `Arc<PolydatProgram>` is shared
    ///    via clone (cheap — refcount bump).
    /// 2. **Each hydrated kernel is independent.** Per-fiber
    ///    state means no synchronization between fibers running
    ///    the same iteration in parallel. Each `for_iteration`
    ///    call produces a fresh kernel with its own input
    ///    slots, output cells, and write-through bindings.
    /// 3. **Parent-chain wiring is uniform.** Every hydrated
    ///    kernel runs through the parent's
    ///    `materialize_subscope` (and downstream
    ///    `materialize_wiring_from_outer`) so cell propagation,
    ///    shared-cell attach, and the read invariant
    ///    (wire_materialization.md) are byte-identical to any
    ///    other parent → child path.
    ///
    /// # When to use this
    ///
    /// - **Per-iteration kernel construction** in scope
    ///   walkers and pre-map walkers. The runtime dispatcher
    ///   uses it before descending into a comprehension
    ///   iteration's children; the pre-map walker uses it so
    ///   nested `for_each` clauses with outer-iter-var
    ///   interpolation (`vec_{profile}`) resolve at pre-map
    ///   time.
    ///
    /// # Why one entry point
    ///
    /// Owning the recipe here ensures both consumers (runtime
    /// dispatcher + pre-map walker) produce identical kernels
    /// for identical inputs, rather than each site composing
    /// `from_program` → `materialize_wiring_from_outer` →
    /// `set_input` on its own and drifting.
    ///
    /// # See also
    ///
    /// - `Self::from_program` (internal) — the
    ///   build-fresh-state primitive `for_iteration` composes
    ///   with parent-chain wiring.
    /// - [`Self::propagate_inputs_into`] — the kernel-chain
    ///   operation that extends cascade-extern values into a
    ///   subkernel (called once after `for_iteration` from each
    ///   scope walker so multi-level cascades reach the
    ///   grandchild).
    pub fn for_iteration(
        canonical: &Arc<PolydatKernel>,
        parent: &Arc<PolydatKernel>,
        bindings: &[(String, Value)],
    ) -> Arc<PolydatKernel> {
        // Routes through the parent's typed materialization
        // primitive so cell propagation is uniform with every
        // other parent → child path.
        Arc::new(parent.materialize_subscope(canonical.program().clone(), bindings))
    }

    /// Recompute this kernel's *own* scope coordinates from
    /// the current state and overwrite [`Self::scope_coords`]
    /// with `[own]`. Used at construction time and at the start
    /// of [`Self::materialize_wiring_from_outer`] before extending with the
    /// outer chain. Internal — callers want
    /// [`Self::scope_coordinates`].
    fn refresh_scope_coordinates(&mut self) {
        let own = self.compute_own_coordinates();
        self.scope_coords.clear();
        if !own.is_empty() {
            self.scope_coords.push(own);
        }
    }

    /// Compute the iteration coordinates this scope owns —
    /// every input slot tagged `IterationExtern` whose name
    /// isn't marked inherited in the program. Values come
    /// from the live state. Empty for non-comprehension
    /// scopes (workload root, scenario lists, individual
    /// phases).
    fn compute_own_coordinates(&self) -> super::ScopeCoord {
        use crate::kernel::InputKind;
        let mut vars = indexmap::IndexMap::new();
        for (idx, name) in self.program.input_names().into_iter().enumerate() {
            let kind = self.program.input_kind(idx);
            if kind != Some(InputKind::IterationExtern) {
                continue;
            }
            if self.program.is_inherited(&name) {
                continue;
            }
            // Use `lookup` (two-tier: const buffer first, input
            // slot second) rather than reading the input slot
            // directly. The conditional-shadow `const NAME :=
            // <expr>` pattern (none_semantics.md) makes NAME both an
            // input slot (wired with the outer scope's binding —
            // typically a workload-param default) AND a const
            // output (the iter-shadow result). The own-coordinate
            // should report the AUTHORITATIVE value the scope
            // publishes, which is the const buffer when present.
            // Reading the input slot directly would report the
            // wired-in default, masking the per-iter shadow value
            // in activity labels / scope-coord display paths.
            let Some(value) = self.lookup(&name) else {
                continue;
            };
            if matches!(value, Value::None) {
                continue;
            }
            vars.insert(name, value);
        }
        super::ScopeCoord { vars }
    }

    /// The leaf-first scope coordinate path — see the
    /// scope model design document (`docs/design/scope_model.md`) for the formal
    /// definition. Always reflects the current binding state:
    /// after `Self::materialize_wiring_from_outer` the path includes the
    /// outer kernel's full chain; for root scopes the path is
    /// just this kernel's own coords (or empty).
    pub fn scope_coordinates(&self) -> &[super::ScopeCoord] {
        &self.scope_coords
    }

    /// Refresh this kernel's own coordinates and append `outer`'s
    /// path, giving `[own] ++ outer`. What the binder does once the
    /// child's inputs are in, so the own-coord snapshot sees them.
    pub fn extend_scope_coordinates(&mut self, outer: &[super::ScopeCoord]) {
        self.refresh_scope_coordinates();
        self.scope_coords.extend_from_slice(outer);
    }

    // There is no scope-exit copy of `shared` values: they live in
    // SharedCell-backed input slots, and writes from inner kernels
    // flow through the cell's Mutex (scope_model.md §6).

    /// Extract the scope values that were set via `materialize_wiring_from_outer`.
    /// Returns `[(name, value)]` for inputs that are not at their
    /// default. Used by `OpBuilder` to inject the same values into
    /// every fiber's state, including per-op-template kernels
    /// whose input layout differs from this kernel's. The name-
    /// keyed shape is the cross-kernel-safe contract: an index
    /// captured against this kernel's layout is meaningless when
    /// applied to a kernel synthesised from a different source
    /// (different extern declaration order, lazy-cascade omissions,
    /// etc.). Naming the binding makes the cross-scope write
    /// unambiguous — a missing name on the target program is a
    /// no-op rather than a silently mis-routed write.
    ///
    /// A const's slot is left out: only initialization writes it, and
    /// each kernel the values are written into initializes its own
    /// consts from them.
    pub fn scope_values(&self) -> Vec<(String, Value)> {
        let mut values = Vec::new();
        for (i, name) in self.program.input_names().into_iter().enumerate() {
            if self.program.input_kind(i) == Some(crate::kernel::InputKind::Const) {
                continue;
            }
            let val = self.state.get_input(i);
            if !matches!(val, Value::None) {
                values.push((name, val.clone()));
            }
        }
        values
    }

    /// Extract the program for concurrent use.
    pub fn into_program(self) -> Arc<PolydatProgram> {
        self.program
    }
}

#[cfg(test)]
mod scope_values_tests {
    /// A scope's values are what a host writes into other kernels, so a
    /// const's slot, which only initialization writes, is not among
    /// them; the extern it reads is.
    #[test]
    fn scope_values_leave_out_const_slots() {
        let k = crate::dsl::compile::compile_polydat_interpreter(
            "extern tag: str = \"t1\"\nconst label := \"x_{tag}\"\n",
        )
        .unwrap();
        let names: Vec<String> = k.scope_values().into_iter().map(|(n, _)| n).collect();
        assert!(names.iter().any(|n| n == "tag"), "{names:?}");
        assert!(
            !names.iter().any(|n| n.starts_with("__const_")),
            "{names:?}"
        );
    }
}

#[cfg(test)]
mod type_stability_tests {
    use super::*;
    use crate::ast::PortType;

    /// scope_model.md §6.1 — the write-through boundary:
    /// matching types pass untouched, the catalog heals lossless
    /// widening (U64 → F64 slot), and an unhealable mismatch (F64
    /// into a U64 cell) errors AT THE WRITE with
    /// the cell name, both types, and the narrowing-cast guidance.
    #[test]
    fn write_through_boundary_matches_widens_and_rejects() {
        // Match: passes through untouched.
        let v = check_write_through_type("m", "__write_m", PortType::U64, Value::U64(7))
            .expect("matching type passes");
        assert_eq!(v.as_u64(), 7);

        // Widening: U64 value into an F64 cell heals via the catalog.
        let v = check_write_through_type("m", "__write_m", PortType::F64, Value::U64(900))
            .expect("u64→f64 widens");
        assert_eq!(v.as_f64(), 900.0);

        // None sentinel passes (none_semantics.md Rule 1 handles it).
        let v = check_write_through_type("m", "__write_m", PortType::U64, Value::None)
            .expect("None passes through");
        assert!(matches!(v, Value::None));

        // Narrowing: F64 into a U64 cell is an error at the write,
        // naming everything the author needs.
        let err = check_write_through_type(
            "measured",
            "__write_measured",
            PortType::U64,
            Value::F64(900.0),
        )
        .expect_err("f64→u64 narrowing must be rejected");
        assert!(err.contains("measured"), "names the cell: {err}");
        assert!(
            err.contains("U64") && err.contains("F64"),
            "names both types: {err}"
        );
        assert!(
            err.contains("trunc_u64"),
            "points at the explicit cast: {err}"
        );
    }
}