feat: add previous() to access a tracked function's prior memoized value

components/salsa-macro-rules/src/setup_tracked_fn.rs

@@ -469,6 +469,40 @@ macro_rules! setup_tracked_fn {
                     }
                 }
 
+                /// Returns a reference to this function's memoized value from the previous
+                /// revision, or `None` if there is no usable previous value.
+                ///
+                /// This is only meaningful while the function is re-executing for the current
+                /// key: it lets the new computation build on its own prior result. Reading the
+                /// previous value replays that result's dependencies into the current execution,
+                /// so incremental validation stays correct.
+                ///
+                /// Returns `None` when the function has never completed for this key, when the
+                /// previous result is provisional (for example, mid-cycle), or when the memoized
+                /// value has been evicted (for example, due to an LRU capacity limit).
+                ///
+                /// Values accumulated by the previous execution itself are not replayed; a
+                /// function that accumulates must push its values again even when it returns
+                /// its previous result.
+                ///
+                /// For a specifiable function, the previous value may have been assigned via
+                /// `specify` rather than computed by this function; the two cases are
+                /// indistinguishable here.
+                ///
+                /// # Panics
+                ///
+                /// Panics if called outside of this tracked function's own execution.
+                pub fn previous<$db_lt>(
+                    $db: &$db_lt dyn $Db,
+                ) -> Option<&$db_lt $output_ty> {
+                    use ::salsa::plumbing as $zalsa;
+
+                    $zalsa::attach($db, || {
+                        let (zalsa, zalsa_local) = $db.zalsas();
+                        $Configuration::fn_ingredient_($db, zalsa).previous(zalsa, zalsa_local)
+                    })
+                }
+
                 $zalsa::macro_if! { $is_specifiable =>
                     pub fn specify<$db_lt>(
                         $db: &$db_lt dyn $Db,

src/active_query.rs

@@ -11,7 +11,9 @@ use crate::key::DatabaseKeyIndex;
 use crate::runtime::Stamp;
 use crate::sync::atomic::AtomicBool;
 use crate::tracked_struct::{Disambiguator, DisambiguatorMap, IdentityHash, IdentityMap};
-use crate::zalsa_local::{OriginAndExtra, QueryEdge, QueryRevisions, QueryRevisionsExtra};
+use crate::zalsa_local::{
+    OriginAndExtra, QueryEdge, QueryEdges, QueryRevisions, QueryRevisionsExtra,
+};
 use crate::{
     Id,
     cycle::{CycleHeads, IterationStamp},
@@ -72,7 +74,7 @@ impl ActiveQuery {
         &mut self,
         durability: Durability,
         changed_at: Revision,
-        edges: crate::zalsa_local::QueryEdges<'_>,
+        edges: QueryEdges<'_>,
         untracked_read: bool,
         active_tracked_ids: &[(Identity, Id)],
     ) {
@@ -93,6 +95,32 @@ impl ActiveQuery {
             .seed(active_tracked_ids.iter().map(|(id, _)| id));
     }
 
+    pub(super) fn add_previous_memo_read(
+        &mut self,
+        durability: Durability,
+        current_revision: Revision,
+        edges: QueryEdges<'_>,
+        untracked_read: bool,
+        tracked_struct_ids: &[(Identity, Id)],
+        #[cfg(feature = "accumulator")] accumulated_inputs: InputAccumulatedValues,
+    ) {
+        self.input_outputs.extend(edges);
+        self.durability = self.durability.min(durability);
+        self.changed_at = self.changed_at.max(current_revision);
+        self.untracked_read |= untracked_read;
+        #[cfg(feature = "accumulator")]
+        {
+            self.accumulated_inputs |= accumulated_inputs;
+        }
+
+        // Mark all tracked structs from the previous revision as active and reserve
+        // their identities so that newly created structs receive later disambiguators.
+        self.tracked_struct_ids
+            .mark_all_active(tracked_struct_ids.iter().copied());
+        self.disambiguator_map
+            .seed(tracked_struct_ids.iter().map(|(id, _)| id));
+    }
+
     pub(super) fn take_cycle_heads(&mut self) -> CycleHeads {
         std::mem::take(&mut self.cycle_heads)
     }

src/function.rs

@@ -34,6 +34,7 @@ mod fetch;
 mod inputs;
 mod maybe_changed_after;
 mod memo;
+mod previous;
 mod specify;
 mod sync;
 

src/function/previous.rs

@@ -0,0 +1,55 @@
+use crate::function::{Configuration, IngredientImpl};
+use crate::zalsa::Zalsa;
+use crate::zalsa_local::ZalsaLocal;
+
+impl<C> IngredientImpl<C>
+where
+    C: Configuration,
+{
+    /// Returns the value memoized for the active key in the previous revision,
+    /// replaying that result's dependencies into the active query.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the active query is not an execution of this tracked function.
+    pub fn previous<'db>(
+        &'db self,
+        zalsa: &'db Zalsa,
+        zalsa_local: &'db ZalsaLocal,
+    ) -> Option<&'db C::Output<'db>> {
+        let Some((database_key_index, _)) = zalsa_local.active_query() else {
+            panic!(
+                "cannot access previous memoized value for {} outside of its tracked function",
+                C::DEBUG_NAME,
+            );
+        };
+
+        if database_key_index.ingredient_index() != self.index {
+            panic!(
+                "cannot access previous memoized value for {} while executing {database_key_index:?}",
+                C::DEBUG_NAME,
+            );
+        }
+
+        let id = database_key_index.key_index();
+        let memo_ingredient_index = self.memo_ingredient_index(zalsa, id);
+        let memo = self.get_memo_from_table_for(zalsa, id, memo_ingredient_index)?;
+
+        if memo.header.may_be_provisional() {
+            return None;
+        }
+
+        let value = memo.value.as_ref()?;
+        let revisions = &memo.header.revisions;
+        zalsa_local.report_previous_memo_read(
+            revisions.durability,
+            revisions.origin().edges(),
+            revisions.is_derived_untracked(),
+            revisions.tracked_struct_ids(),
+            #[cfg(feature = "accumulator")]
+            revisions.accumulated_inputs.load(),
+            zalsa.current_revision(),
+        );
+        Some(value)
+    }
+}

src/input.rs

@@ -272,6 +272,7 @@ pub struct StructEntry<'db, C>
 where
     C: Configuration,
 {
+    #[cfg_attr(not(feature = "salsa_unstable"), expect(dead_code))]
     value: &'db Value<C>,
     key: DatabaseKeyIndex,
 }

src/table/memo.rs

@@ -111,6 +111,7 @@ impl LazyMemoEntries {
         self.as_mut_slice()?.get_mut(index)
     }
 
+    #[cfg(feature = "salsa_unstable")]
     fn iter(&self) -> std::slice::Iter<'_, MemoEntry> {
         self.as_slice().unwrap_or_default().iter()
     }

src/tracked_struct.rs

@@ -942,6 +942,7 @@ pub struct StructEntry<'db, C>
 where
     C: Configuration,
 {
+    #[cfg_attr(not(feature = "salsa_unstable"), expect(dead_code))]
     value: &'db Value<C>,
     key: DatabaseKeyIndex,
 }

src/zalsa_local.rs

@@ -15,7 +15,7 @@ use thin_vec::ThinVec;
 #[cfg(feature = "accumulator")]
 use crate::accumulator::{
     Accumulator,
-    accumulated_map::{AccumulatedMap, AtomicInputAccumulatedValues},
+    accumulated_map::{AccumulatedMap, AtomicInputAccumulatedValues, InputAccumulatedValues},
 };
 use crate::active_query::{CompletedQuery, DetachedInputOutputs, QueryCompletion, QueryStack};
 use crate::cycle::{AtomicIterationStamp, CycleHeads, IterationStamp, empty_cycle_heads};
@@ -392,6 +392,33 @@ impl ZalsaLocal {
         }
     }
 
+    pub(crate) fn report_previous_memo_read(
+        &self,
+        durability: Durability,
+        edges: QueryEdges<'_>,
+        untracked_read: bool,
+        tracked_struct_ids: &[(Identity, Id)],
+        #[cfg(feature = "accumulator")] accumulated_inputs: InputAccumulatedValues,
+        current_revision: Revision,
+    ) {
+        // SAFETY: We do not access the query stack reentrantly.
+        unsafe {
+            self.with_query_stack_unchecked_mut(|stack| {
+                if let Some(top_query) = stack.last_mut() {
+                    top_query.add_previous_memo_read(
+                        durability,
+                        current_revision,
+                        edges,
+                        untracked_read,
+                        tracked_struct_ids,
+                        #[cfg(feature = "accumulator")]
+                        accumulated_inputs,
+                    );
+                }
+            })
+        }
+    }
+
     /// Register that the current query read an untracked value
     ///
     /// # Parameters