refactor(compiler): remove entry point wrappers (#600)

Author: zharinov

crates/plotnik-lib/src/bytecode/dump.rs

@@ -89,10 +89,8 @@ impl DumpContext {
         }
     }
 
-    fn label_for(&self, addr: SuccessorAddr) -> Option<&str> {
-        self.addr_labels
-            .get(&CodeAddr::from(u16::from(addr)))
-            .map(|s| s.as_str())
+    fn label_for(&self, addr: CodeAddr) -> Option<&str> {
+        self.addr_labels.get(&addr).map(|s| s.as_str())
     }
 }
 
@@ -547,7 +545,7 @@ impl DumpFormatter<'_> {
 
     fn format_addr(&self, addr: SuccessorAddr) -> String {
         let c = &self.ctx.colors;
-        if let Some(label) = self.ctx.label_for(addr) {
+        if let Some(label) = self.ctx.label_for(CodeAddr::from(u16::from(addr))) {
             format!("▶({}{}{})", c.blue, label, c.reset)
         } else {
             format!("{:0w$}", u16::from(addr), w = self.addr_width)

crates/plotnik-lib/src/bytecode/entry_point.rs

@@ -3,6 +3,33 @@
 use super::instructions::CodeAddr;
 use super::{StringId, TypeId};
 
+/// Output effects owned by an entry point rather than its shared definition body.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+#[repr(u16)]
+pub(crate) enum EntryBoundary {
+    /// The definition body already produces the complete result.
+    Passthrough = 0,
+    /// Capture the current node after the definition returns successfully.
+    Node = 1,
+    /// Open a root record before execution and close it after a successful return.
+    Record = 2,
+}
+
+impl EntryBoundary {
+    pub(crate) fn from_u16(value: u16) -> Option<Self> {
+        match value {
+            0 => Some(Self::Passthrough),
+            1 => Some(Self::Node),
+            2 => Some(Self::Record),
+            _ => None,
+        }
+    }
+
+    pub(crate) fn to_u16(self) -> u16 {
+        self as u16
+    }
+}
+
 /// Named query definition entry point (8 bytes).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 #[repr(C)]
@@ -13,7 +40,8 @@ pub struct EntryPoint {
     target: CodeAddr,
     /// Result type.
     result_type: TypeId,
-    _pad: u16,
+    /// Entry-owned result boundary effects.
+    boundary: u16,
 }
 
 const _: () = assert!(std::mem::size_of::<EntryPoint>() == EntryPoint::SIZE);
@@ -22,12 +50,17 @@ impl EntryPoint {
     /// Serialized size in bytes.
     pub const SIZE: usize = 8;
 
-    pub fn new(name: StringId, target: CodeAddr, result_type: TypeId) -> Self {
+    pub(crate) fn new(
+        name: StringId,
+        target: CodeAddr,
+        result_type: TypeId,
+        boundary: EntryBoundary,
+    ) -> Self {
         Self {
             name,
             target,
             result_type,
-            _pad: 0,
+            boundary: boundary.to_u16(),
         }
     }
 
@@ -37,7 +70,7 @@ impl EntryPoint {
                 .expect("entry point name id must be non-zero"),
             target: CodeAddr::from(u16::from_le_bytes([bytes[2], bytes[3]])),
             result_type: TypeId::from(u16::from_le_bytes([bytes[4], bytes[5]])),
-            _pad: 0,
+            boundary: u16::from_le_bytes([bytes[6], bytes[7]]),
         }
     }
 
@@ -50,4 +83,13 @@ impl EntryPoint {
     pub fn result_type(&self) -> TypeId {
         self.result_type
     }
+
+    pub(crate) fn try_boundary(&self) -> Option<EntryBoundary> {
+        EntryBoundary::from_u16(self.boundary)
+    }
+
+    pub(crate) fn boundary(&self) -> EntryBoundary {
+        self.try_boundary()
+            .expect("validated entry point has a known boundary mode")
+    }
 }

crates/plotnik-lib/src/bytecode/instructions.rs

@@ -802,7 +802,7 @@ pub struct Call {
     pub ownership: CallOwnership,
     pub nav: Nav,
     pub node_field: Option<NodeFieldId>,
-    pub target: SuccessorAddr,
+    pub target: CodeAddr,
     returns: [Option<SuccessorAddr>; CALL_MAX_RETURNS],
     returns_len: u8,
     consumed_mask: u8,
@@ -815,7 +815,7 @@ impl Call {
         node_field: Option<NodeFieldId>,
         return_addrs: &[SuccessorAddr],
         consumed_mask: u8,
-        target: SuccessorAddr,
+        target: CodeAddr,
     ) -> Self {
         assert!(
             (1..=CALL_MAX_RETURNS).contains(&return_addrs.len()),
@@ -912,7 +912,7 @@ impl Call {
                     node_field,
                     &[successor_addr(4)],
                     consumed_mask,
-                    successor_addr(6),
+                    CodeAddr::from(u16::from_le_bytes([bytes[6], bytes[7]])),
                 )
             }
             Opcode::CallN => {
@@ -927,7 +927,7 @@ impl Call {
                     node_field,
                     &return_addrs,
                     bytes[7],
-                    successor_addr(4),
+                    CodeAddr::from(u16::from_le_bytes([bytes[4], bytes[5]])),
                 )
             }
             _ => unreachable!("Call::from_bytes requires Call1 or CallN"),

crates/plotnik-lib/src/bytecode/mod.rs

@@ -45,6 +45,7 @@ pub(crate) use constants::{
     VERSION,
 };
 pub(crate) use effects::{Effect, EffectKind, EffectSuppression, FrameAction, ValueFrameKind};
+pub(crate) use entry_point::EntryBoundary;
 pub(crate) use format::{
     LineBuilder, Symbol, cols, nav_symbol, trace, truncate_text, width_for_count,
 };

crates/plotnik-lib/src/bytecode/module/decoded.rs

@@ -63,7 +63,7 @@ pub(crate) struct DecodedCall {
     pub(crate) ownership: CallOwnership,
     pub(crate) nav: Nav,
     pub(crate) node_field: Option<NodeFieldId>,
-    pub(crate) target: SuccessorAddr,
+    pub(crate) target: CodeAddr,
     returns_base: u32,
     returns_len: u8,
 }

crates/plotnik-lib/src/bytecode/module/effect_stack.rs

@@ -25,9 +25,9 @@
 //! materializer's pending-value register is full. Tracking span *ids* (not just
 //! a depth) proves every `SpanEnd` closes the span the matching bracket opened,
 //! so inspection extraction can assert pairing instead of re-validating. The
-//! walk starts from each entry point wrapper and follows `Match` successors,
-//! descending through `Call` and resuming at its return address — exactly the
-//! edge set that orders effects at runtime.
+//! walk starts from each entry definition and follows `Match` successors,
+//! descending through `Call` and resuming at its return address. Entry-owned
+//! record/node effects are modeled around the resulting definition summary.
 //!
 //! ## Why state *sets* (collecting semantics)
 //!
@@ -75,8 +75,8 @@
 //! summary instead of inlining, which both terminates and stays sound. The
 //! summaries are computed by a monotone fixpoint (a callee that reads its
 //! caller's top before pushing propagates the constraint up to its own
-//! callers), then a final pass checks every call site and every entry point
-//! wrapper against the stabilized summaries.
+//! callers), then a final pass checks every call site and every entry boundary
+//! against the stabilized summaries.
 //!
 //! `record_sets_caller_top` exists because a below-entry `RecordSet` mutates state the
 //! caller's walk otherwise cannot see: setting a field on the caller's *variant*
@@ -87,11 +87,9 @@
 //! panic past the check.
 //!
 //! A successor-less `Match` accepts the *whole run* from any call depth,
-//! freezing the log with every caller frame still open. Inside an entry point
-//! wrapper the local stack is the global stack, so the existing exit check is
-//! exact; inside a body reachable through `Call` the caller's frames are
-//! invisible here, so such accepts are rejected outright — the compiler ends
-//! every definition body with `Return` and only accepts at wrapper level.
+//! freezing the log with every caller frame still open. Inside a body reachable
+//! through `Call` the caller's frames are invisible here, so such accepts are
+//! rejected outright — the compiler ends every definition body with `Return`.
 //!
 //! Net-neutrality, no popping below entry, and suppression balance are not
 //! assumed — they are verified, so a malformed body is rejected
@@ -113,7 +111,7 @@ use std::collections::{HashMap, HashSet, VecDeque};
 
 use super::{Instruction, Module, ModuleError};
 use crate::bytecode::{
-    CodeAddr, Effect, EffectKind, FrameAction, TypeDefKind, TypeKind, ValueFrameKind,
+    CodeAddr, Effect, EffectKind, EntryBoundary, FrameAction, TypeDefKind, TypeKind, ValueFrameKind,
 };
 
 /// Builder frames the materializer pushes. The root/result frame can be a
@@ -328,19 +326,22 @@ pub(crate) fn validate_effect_stack(module: &Module) -> Result<(), ModuleError>
         )?;
     }
 
-    // ...and every entry point wrapper. A wrapper has no caller, so a residual
-    // caller-top constraint means some effect would read below the frames the
-    // wrapper itself opened and hit the materializer's result root frame.
+    // Entry boundaries supply the root frame/effect that used to be executable
+    // wrapper instructions.
     for entry_point in entry_points.iter() {
         let target = entry_point.target();
-        let wrapper = analyze(
-            module,
-            &summaries,
-            target,
-            BodyRole::from_called(called.contains(&target)),
-            VerifyPhase::Final,
-        )?;
-        if wrapper.entry_tos != KS_ANY {
+        let summary = summaries[&target];
+        let boundary = entry_point.boundary();
+        let accepts_caller_top = match boundary {
+            EntryBoundary::Record => summary.entry_tos & KS_RECORD != 0,
+            EntryBoundary::Passthrough | EntryBoundary::Node => summary.entry_tos == KS_ANY,
+        };
+        if !accepts_caller_top {
+            return Err(ModuleError::EffectStackImbalance(target));
+        }
+        if matches!(boundary, EntryBoundary::Node | EntryBoundary::Record)
+            && summary.returns_pending == Some(true)
+        {
             return Err(ModuleError::EffectStackImbalance(target));
         }
     }
@@ -600,10 +601,9 @@ fn analyze(
                     )?;
                 }
                 if m.succ_count() == 0 {
-                    // A successor-less match accepts the whole run. At wrapper
-                    // level the local stack is the global stack, so balance
-                    // here is exact; under a `Call` the caller's frames are
-                    // still open in the log, so this is never sound.
+                    // A successor-less match accepts the whole run. Under a
+                    // `Call`, caller frames are still open in the log, so this
+                    // is never sound.
                     if role == BodyRole::Called {
                         return Err(ModuleError::EffectStackImbalance(addr));
                     }
@@ -651,7 +651,7 @@ impl CallRoute {
     fn from_instruction(instruction: Instruction<'_>) -> Option<Self> {
         match instruction {
             Instruction::Call(call) => Some(Self {
-                target: CodeAddr::from(u16::from(call.target)),
+                target: call.target,
                 returns: call
                     .returns()
                     .map(|addr| CodeAddr::from(u16::from(addr)))

crates/plotnik-lib/src/bytecode/module/load.rs

@@ -574,8 +574,6 @@ impl Module {
         let entry_points = self.entry_points();
         let word_count = self.header.instruction_word_count;
         let type_defs = self.header.type_defs_count;
-        let storage: &[u8] = &self.storage;
-        let base = self.offsets.entry_points as usize;
         for i in 0..entry_points.len() {
             let invalid = || ModuleError::InvalidEntryPoint(i);
             let ep = entry_points.get(i);
@@ -593,9 +591,7 @@ impl Module {
                 return Err(invalid());
             }
 
-            // Bytes 6-7 are the reserved `_pad`; `EntryPoint::from_bytes` discards
-            // them, so a malformed non-zero pad would otherwise pass unnoticed.
-            if read_u16_le(storage, base + i * 8 + 6) != 0 {
+            if ep.try_boundary().is_none() {
                 return Err(invalid());
             }
         }
@@ -622,7 +618,7 @@ impl Module {
             let words = match self.decode_instruction(addr) {
                 Instruction::Match(m) => m.word_count(),
                 Instruction::Call(c) => {
-                    let target = CodeAddr::from(u16::from(c.target));
+                    let target = c.target;
                     let route = DepthRoute::from_call(c);
                     if let Some(expected) = roots.insert(target, route)
                         && expected != route
@@ -664,7 +660,7 @@ impl Module {
             let words = match self.decode_instruction(addr) {
                 Instruction::Match(matched) => matched.word_count(),
                 Instruction::Call(call) => {
-                    let target = CodeAddr::from(u16::from(call.target));
+                    let target = call.target;
                     if !self
                         .return_contract(target, &mut cache)
                         .is(ReturnPorts::dense(call.arity()), call.callee_contract())
@@ -983,7 +979,7 @@ impl Module {
                     }
                     let next = read_operand_u16(storage, instr_off + 4)?;
                     let target = read_operand_u16(storage, instr_off + 6)?;
-                    if next == 0 || target == 0 {
+                    if next == 0 {
                         return Err(ModuleError::MalformedInstructionStream);
                     }
                     targets.push(CodeAddr::from(next));
@@ -1002,7 +998,7 @@ impl Module {
                     }
                     let target = read_operand_u16(storage, instr_off + 4)?;
                     let arity = usize::from(read_u8(instr_off + 6)?);
-                    if !(2..=usize::from(PortId::COUNT)).contains(&arity) || target == 0 {
+                    if !(2..=usize::from(PortId::COUNT)).contains(&arity) {
                         return Err(ModuleError::MalformedInstructionStream);
                     }
                     let consumed_mask = read_u8(instr_off + 7)?;