deepstrike 0.2.81__tar.gz → 0.2.83__tar.gz

{deepstrike-0.2.81 → deepstrike-0.2.83}/Cargo.lock

@@ -293,7 +293,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-core"
-version = "0.2.81"
+version = "0.2.83"
 dependencies = [
  "compact_str",
  "deepstrike-tokenizer",
@@ -307,7 +307,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-lab"
-version = "0.2.81"
+version = "0.2.83"
 dependencies = [
  "serde",
  "serde_json",
@@ -315,7 +315,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-node"
-version = "0.2.81"
+version = "0.2.83"
 dependencies = [
  "compact_str",
  "deepstrike-core",
@@ -327,7 +327,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-py"
-version = "0.2.81"
+version = "0.2.83"
 dependencies = [
  "compact_str",
  "deepstrike-core",
@@ -338,7 +338,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-sdk"
-version = "0.2.81"
+version = "0.2.83"
 dependencies = [
  "async-stream",
  "async-trait",
@@ -376,7 +376,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-tokenizer"
-version = "0.2.81"
+version = "0.2.83"
 dependencies = [
  "pretty_assertions",
  "tiktoken-rs",
@@ -384,7 +384,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-wasm"
-version = "0.2.81"
+version = "0.2.83"
 dependencies = [
  "compact_str",
  "deepstrike-core",

{deepstrike-0.2.81 → deepstrike-0.2.83}/Cargo.toml

@@ -3,13 +3,13 @@ resolver = "2"
 members = ["crates/deepstrike-core", "crates/deepstrike-tokenizer", "crates/deepstrike-py"]
 
 [workspace.package]
-version = "0.2.81"
+version = "0.2.83"
 edition = "2024"
 repository = "https://github.com/kongusen/deepstrike"
 
 [workspace.dependencies]
-deepstrike-core = { path = "crates/deepstrike-core", version = "0.2.81" }
-deepstrike-tokenizer = { path = "crates/deepstrike-tokenizer", version = "0.2.81" }
+deepstrike-core = { path = "crates/deepstrike-core", version = "0.2.83" }
+deepstrike-tokenizer = { path = "crates/deepstrike-tokenizer", version = "0.2.83" }
 notify = "6"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

{deepstrike-0.2.81 → deepstrike-0.2.83}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepstrike
-Version: 0.2.81
+Version: 0.2.83
 Requires-Dist: httpx>=0.27
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: anyio>=4.0
@@ -250,7 +250,7 @@ The kernel renders context as four LLM API slots — only **history** is compres
 |------|--------|------|
 | `system_stable` | system partition | Identity, rules — never changes within a run |
 | `system_knowledge` | knowledge partition | Preloaded memory, skill defs — low frequency |
-| `turns[0]` | `task_state` + signals | Goal, plan, progress, compression log, runtime signals |
+| `turns[0]` | `task_state` + signals | Goal, plan, progress, the model's notes, compression log, runtime signals |
 | `turns[1..N]` | history | Conversation transcript |
 
 ```python
@@ -268,6 +268,47 @@ Full reference: [docs/concepts/context-slots-compression.md](../docs/concepts/co
 
 ---
 
+## Notes and model-proposed memory (0.2.82)
+
+The model decides what is worth keeping; the kernel keeps it.
+
+- **Notes.** Every request carries a `note` tool. The model writes, rewrites and retires notes — a
+  running count, what is done, a rule it learned. Notes render in the state turn (`notes:`), and no
+  compaction tier or renewal touches them. Over the budget (default 600 tokens) the kernel refuses
+  the write instead of deleting for the model. Each note is a context-graph item with
+  `derived_from` edges to the tool results it came from.
+- **Memory the model proposes.** With a candidate sink, the model calls `propose_memory` for what
+  should outlive the task; the proposal goes through the attested candidate ledger, and later
+  sessions recall it as an index line.
+
+```python
+RuntimeOptions(..., context_policy={"notes_budget_tokens": 600})  # default; 0 turns notes off
+```
+
+```python
+RuntimeOptions(
+    ...,
+    memory_candidate_sink=sink,
+    memory_runtime_policy={"retrieval": "host", "model_writes": "candidate_sink"},
+)
+```
+
+Measured on DeepSeek `deepseek-flash`, paired against the same tasks without the mechanism
+(cost is price-weighted, per correct answer):
+
+| Scenario | Without | With | Cost per correct answer |
+|---|---|---|---|
+| long-horizon (30 pairs) | 15/30 | **20/30** with notes | **−43%** |
+| ledger (30 pairs) | 25/30 | **30/30** with notes | −3% |
+| multi-session (48 pairs) | 9/48, no memory | **33/48** with notes + `propose_memory` | **−68%** |
+
+The kernel never initiates a model call to manage context: kernel-side summaries, cache-account
+compaction, note diagnostics and a post-session consolidation run were measured and deleted. Why,
+and how a mechanism earns its place: [DEC-13: Model-Led Context](https://github.com/kongusen/deepstrike/blob/main/docs/en/decisions/013-model-led-context.md). Details:
+[Context Engineering — notes](https://github.com/kongusen/deepstrike/blob/main/docs/en/guides/context-engineering.md).
+
+---
+
 ## Runtime options
 
 ```python

{deepstrike-0.2.81 → deepstrike-0.2.83}/README.md

@@ -235,7 +235,7 @@ The kernel renders context as four LLM API slots — only **history** is compres
 |------|--------|------|
 | `system_stable` | system partition | Identity, rules — never changes within a run |
 | `system_knowledge` | knowledge partition | Preloaded memory, skill defs — low frequency |
-| `turns[0]` | `task_state` + signals | Goal, plan, progress, compression log, runtime signals |
+| `turns[0]` | `task_state` + signals | Goal, plan, progress, the model's notes, compression log, runtime signals |
 | `turns[1..N]` | history | Conversation transcript |
 
 ```python
@@ -253,6 +253,47 @@ Full reference: [docs/concepts/context-slots-compression.md](../docs/concepts/co
 
 ---
 
+## Notes and model-proposed memory (0.2.82)
+
+The model decides what is worth keeping; the kernel keeps it.
+
+- **Notes.** Every request carries a `note` tool. The model writes, rewrites and retires notes — a
+  running count, what is done, a rule it learned. Notes render in the state turn (`notes:`), and no
+  compaction tier or renewal touches them. Over the budget (default 600 tokens) the kernel refuses
+  the write instead of deleting for the model. Each note is a context-graph item with
+  `derived_from` edges to the tool results it came from.
+- **Memory the model proposes.** With a candidate sink, the model calls `propose_memory` for what
+  should outlive the task; the proposal goes through the attested candidate ledger, and later
+  sessions recall it as an index line.
+
+```python
+RuntimeOptions(..., context_policy={"notes_budget_tokens": 600})  # default; 0 turns notes off
+```
+
+```python
+RuntimeOptions(
+    ...,
+    memory_candidate_sink=sink,
+    memory_runtime_policy={"retrieval": "host", "model_writes": "candidate_sink"},
+)
+```
+
+Measured on DeepSeek `deepseek-flash`, paired against the same tasks without the mechanism
+(cost is price-weighted, per correct answer):
+
+| Scenario | Without | With | Cost per correct answer |
+|---|---|---|---|
+| long-horizon (30 pairs) | 15/30 | **20/30** with notes | **−43%** |
+| ledger (30 pairs) | 25/30 | **30/30** with notes | −3% |
+| multi-session (48 pairs) | 9/48, no memory | **33/48** with notes + `propose_memory` | **−68%** |
+
+The kernel never initiates a model call to manage context: kernel-side summaries, cache-account
+compaction, note diagnostics and a post-session consolidation run were measured and deleted. Why,
+and how a mechanism earns its place: [DEC-13: Model-Led Context](https://github.com/kongusen/deepstrike/blob/main/docs/en/decisions/013-model-led-context.md). Details:
+[Context Engineering — notes](https://github.com/kongusen/deepstrike/blob/main/docs/en/guides/context-engineering.md).
+
+---
+
 ## Runtime options
 
 ```python

deepstrike-0.2.83/crates/deepstrike-core/src/context/cache_ledger.rs

@@ -0,0 +1,383 @@
+//! Plan task 8.0 · the cache ledger: where each provider request broke the previous request's
+//! cacheable prefix, how many tokens that cost, and why.
+//!
+//! A provider caches a request as one prefix: tool schemas, then system[0], system[1], then the
+//! history turns. The volatile state turn is the uncached tail and is left out. Every time a
+//! request goes out the kernel fingerprints that prefix segment by segment and compares it with the
+//! previous request. The first segment that differs is a **prefix break**: every token the previous
+//! request held after it has to be sent uncached again. The ledger records the break (turn, cause,
+//! tokens kept before it, tokens lost after it) and sums the losses into the lifecycle report's
+//! `cache_loss_tokens`.
+//!
+//! The cause comes from the change that made the break. Compaction, renewal, provider rewrites,
+//! tool-result collapse and knowledge promotion announce themselves ([`CacheLedger::note_cause`]);
+//! an unannounced break is classified from the render itself: a dropped item is a budget drop, an
+//! item re-rendered as the narration stub is narration collapse, and a different toolset is a
+//! toolset change.
+//!
+//! The state turn after the history is rebuilt every request, so the previous request's state turn
+//! is never reusable: that is not a break, but a provider's count of uncached input includes it.
+//! The ledger sums it separately as `tail_tokens`, so measured cache loss can be compared with the
+//! kernel's.
+//!
+//! Everything here is derived from the rendered request, so a replay rebuilds the same ledger; it
+//! travels in the checkpoint so a restored run keeps comparing against the request it last sent.
+
+use std::collections::VecDeque;
+
+use serde::{Deserialize, Serialize};
+
+use crate::context::fault::stable_hash;
+use crate::context::item::{HISTORY_ITEM_DETAIL_CAP, ItemId};
+
+/// Prefix breaks the ledger lists one by one; older ones are only counted.
+pub const PREFIX_BREAK_DETAIL_CAP: usize = HISTORY_ITEM_DETAIL_CAP;
+
+/// Why a request's cacheable prefix differs from the previous request's.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum BreakCause {
+    /// The tool schemas changed (a skill narrowed or widened the toolset, a meta tool appeared).
+    Toolset,
+    /// system[0] changed.
+    System,
+    /// system[1] changed outside a compaction: staged knowledge promoted, or a boundary sweep.
+    Promotion,
+    /// Older tool results collapsed to previews under pressure.
+    Collapse,
+    /// An item re-rendered in place without an announced cause (a page-in, a page-out).
+    Reprojection,
+    /// Old assistant narration left the protected window and rendered as the narration stub.
+    Narration,
+    /// The renderer dropped the oldest history over the input budget.
+    BudgetDrop,
+    Snip,
+    Micro,
+    Auto,
+    Renewal,
+    /// The provider compacted or cleared context server-side.
+    Provider,
+    /// History rolled back, or anything else.
+    Other,
+}
+
+impl BreakCause {
+    /// The cause a compaction tier announces.
+    pub fn of_compaction(action: crate::context::pressure::PressureAction) -> Self {
+        use crate::context::pressure::PressureAction;
+        match action {
+            PressureAction::SnipCompact => Self::Snip,
+            PressureAction::MicroCompact => Self::Micro,
+            PressureAction::ContextCollapse => Self::Collapse,
+            PressureAction::AutoCompact => Self::Auto,
+            PressureAction::None => Self::Other,
+        }
+    }
+}
+
+/// One prefix break, attributed.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PrefixBreak {
+    /// The turn of the request that broke the prefix.
+    pub turn: u32,
+    pub cause: BreakCause,
+    /// Tokens of the previous request's prefix still byte-identical (still cacheable).
+    pub kept_tokens: u32,
+    /// Tokens of the previous request's prefix after the break: sent uncached again.
+    pub lost_tokens: u32,
+}
+
+/// The fingerprint and size of one prefix segment.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Segment {
+    /// FNV-1a 64 of the segment's wire material, as 16 hex digits (a string, so a JSON host that
+    /// reads numbers as doubles cannot round it).
+    pub hash: String,
+    pub tokens: u32,
+}
+
+impl Segment {
+    pub fn of(material: &[u8], tokens: u32) -> Self {
+        Self {
+            hash: format!("{:016x}", stable_hash(material)),
+            tokens,
+        }
+    }
+}
+
+/// One history turn of a sent request.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SentTurn {
+    #[serde(flatten)]
+    pub segment: Segment,
+    /// The history item the turn rendered; 0 for a synthetic turn.
+    #[serde(default)]
+    pub item: ItemId,
+    /// The turn rendered as the narration stub.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub stub: bool,
+}
+
+/// The cacheable prefix of one sent request.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SentPrefix {
+    pub tools: Segment,
+    pub system: Segment,
+    pub knowledge: Segment,
+    #[serde(default)]
+    pub turns: Vec<SentTurn>,
+    /// The uncached state turn after the turns.
+    #[serde(default, skip_serializing_if = "crate::context::item::is_zero_u32")]
+    pub tail: u32,
+}
+
+impl SentPrefix {
+    fn header_tokens(&self) -> u32 {
+        self.tools
+            .tokens
+            .saturating_add(self.system.tokens)
+            .saturating_add(self.knowledge.tokens)
+    }
+
+    fn total_tokens(&self) -> u32 {
+        self.turns
+            .iter()
+            .fold(self.header_tokens(), |sum, turn| sum.saturating_add(turn.segment.tokens))
+    }
+
+    /// The tokens a turn with this hash had in this request, to avoid recounting it.
+    pub fn tokens_of(&self, hash: &str) -> Option<u32> {
+        self.turns
+            .iter()
+            .find(|turn| turn.segment.hash == hash)
+            .map(|turn| turn.segment.tokens)
+    }
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CacheLedger {
+    /// The prefix of the last request sent.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sent: Option<SentPrefix>,
+    /// The announced cause of a rewrite since the last request.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub pending: Option<BreakCause>,
+    /// The latest breaks, oldest first.
+    #[serde(default, skip_serializing_if = "VecDeque::is_empty")]
+    pub breaks: VecDeque<PrefixBreak>,
+    #[serde(default, skip_serializing_if = "crate::context::item::is_zero_u32")]
+    pub breaks_omitted: u32,
+    /// Lost tokens summed over every break of the run.
+    #[serde(default, skip_serializing_if = "crate::context::item::is_zero_u64")]
+    pub lost_tokens: u64,
+    /// The state-turn tokens of every request a later request followed: never reusable, so not a
+    /// break, but part of what a provider counts as uncached.
+    #[serde(default, skip_serializing_if = "crate::context::item::is_zero_u64")]
+    pub tail_tokens: u64,
+}
+
+impl CacheLedger {
+    /// A rewrite with `cause` happened; the next request's break, if it has one, is attributed to
+    /// it. The first cause announced since the last request is kept: later rewrites in the same
+    /// interval (a boundary sweep a compaction triggered) follow from it.
+    pub fn note_cause(&mut self, cause: BreakCause) {
+        self.pending.get_or_insert(cause);
+    }
+
+    /// The request with prefix `next` is being sent on `turn`. Compares it with the last request,
+    /// records the break if there is one, and returns it.
+    pub fn observe(&mut self, turn: u32, next: SentPrefix) -> Option<PrefixBreak> {
+        let pending = self.pending.take();
+        self.tail_tokens += self.sent.as_ref().map_or(0, |prev| u64::from(prev.tail));
+        let found = self.sent.as_ref().and_then(|prev| find_break(prev, &next, pending));
+        self.sent = Some(next);
+        let found = found.map(|(cause, kept_tokens, lost_tokens)| PrefixBreak {
+            turn,
+            cause,
+            kept_tokens,
+            lost_tokens,
+        })?;
+        self.lost_tokens += u64::from(found.lost_tokens);
+        self.breaks.push_back(found);
+        if self.breaks.len() > PREFIX_BREAK_DETAIL_CAP {
+            self.breaks.pop_front();
+            self.breaks_omitted += 1;
+        }
+        Some(found)
+    }
+}
+
+/// Where `next` stops reusing `prev`, why, and the (kept, lost) tokens of `prev`'s prefix.
+fn find_break(
+    prev: &SentPrefix,
+    next: &SentPrefix,
+    pending: Option<BreakCause>,
+) -> Option<(BreakCause, u32, u32)> {
+    let total = prev.total_tokens();
+    let lost = |kept: u32| total.saturating_sub(kept);
+    if prev.tools.hash != next.tools.hash {
+        return Some((BreakCause::Toolset, 0, total)).filter(|_| total > 0);
+    }
+    if prev.system.hash != next.system.hash {
+        let kept = prev.tools.tokens;
+        return Some((pending.unwrap_or(BreakCause::System), kept, lost(kept)));
+    }
+    if prev.knowledge.hash != next.knowledge.hash {
+        let kept = prev.tools.tokens.saturating_add(prev.system.tokens);
+        return Some((pending.unwrap_or(BreakCause::Promotion), kept, lost(kept)));
+    }
+    let same = prev
+        .turns
+        .iter()
+        .zip(&next.turns)
+        .take_while(|(a, b)| a.segment.hash == b.segment.hash)
+        .count();
+    if same == prev.turns.len() {
+        return None;
+    }
+    let kept = prev.turns[..same]
+        .iter()
+        .fold(prev.header_tokens(), |sum, turn| sum.saturating_add(turn.segment.tokens));
+    let lost = lost(kept);
+    if lost == 0 {
+        return None;
+    }
+    let cause = pending.unwrap_or_else(|| classify(&prev.turns[same], next, same));
+    Some((cause, kept, lost))
+}
+
+/// An unannounced turn break: what happened to the first turn that no longer matches.
+fn classify(prev: &SentTurn, next: &SentPrefix, at: usize) -> BreakCause {
+    if prev.item != 0 && !next.turns.iter().any(|turn| turn.item == prev.item) {
+        return BreakCause::BudgetDrop;
+    }
+    match next.turns.get(at) {
+        Some(turn) if turn.item == prev.item && turn.stub && !prev.stub => BreakCause::Narration,
+        Some(turn) if turn.item == prev.item && turn.item != 0 => BreakCause::Reprojection,
+        _ => BreakCause::Other,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn seg(name: &str, tokens: u32) -> Segment {
+        Segment::of(name.as_bytes(), tokens)
+    }
+
+    fn turn(name: &str, item: ItemId, tokens: u32) -> SentTurn {
+        SentTurn {
+            segment: seg(name, tokens),
+            item,
+            stub: false,
+        }
+    }
+
+    fn prefix(turns: Vec<SentTurn>) -> SentPrefix {
+        SentPrefix {
+            tools: seg("tools", 100),
+            system: seg("system", 50),
+            knowledge: seg("knowledge", 20),
+            turns,
+            tail: 7,
+        }
+    }
+
+    #[test]
+    fn an_appended_request_breaks_nothing() {
+        let mut ledger = CacheLedger::default();
+        assert_eq!(ledger.observe(1, prefix(vec![turn("a", 1, 10)])), None);
+        let next = prefix(vec![turn("a", 1, 10), turn("b", 2, 30)]);
+        assert_eq!(ledger.observe(2, next), None);
+        assert_eq!(ledger.lost_tokens, 0);
+        assert_eq!(ledger.tail_tokens, 7, "the first request's state turn was not reusable");
+    }
+
+    #[test]
+    fn a_dropped_oldest_turn_is_a_budget_drop() {
+        let mut ledger = CacheLedger::default();
+        ledger.observe(1, prefix(vec![turn("a", 1, 10), turn("b", 2, 30)]));
+        let found = ledger.observe(2, prefix(vec![turn("b", 2, 30), turn("c", 3, 5)]));
+        assert_eq!(
+            found,
+            Some(PrefixBreak {
+                turn: 2,
+                cause: BreakCause::BudgetDrop,
+                kept_tokens: 170,
+                lost_tokens: 40,
+            })
+        );
+        assert_eq!(ledger.lost_tokens, 40);
+    }
+
+    #[test]
+    fn a_turn_rendered_as_the_stub_is_narration() {
+        let mut ledger = CacheLedger::default();
+        ledger.observe(1, prefix(vec![turn("a", 1, 10), turn("b", 2, 30)]));
+        let mut stub = turn("stub", 1, 4);
+        stub.stub = true;
+        let found = ledger.observe(2, prefix(vec![stub, turn("b", 2, 30)])).unwrap();
+        assert_eq!(found.cause, BreakCause::Narration);
+        assert_eq!((found.kept_tokens, found.lost_tokens), (170, 40));
+    }
+
+    #[test]
+    fn an_announced_cause_wins_and_is_spent_by_one_request() {
+        let mut ledger = CacheLedger::default();
+        ledger.observe(1, prefix(vec![turn("a", 1, 10)]));
+        ledger.note_cause(BreakCause::Auto);
+        ledger.note_cause(BreakCause::Promotion);
+        let found = ledger.observe(2, prefix(vec![turn("summary", 5, 3)])).unwrap();
+        assert_eq!(found.cause, BreakCause::Auto);
+        // A compaction that broke nothing leaves no cause behind for a later break.
+        ledger.note_cause(BreakCause::Snip);
+        assert_eq!(ledger.observe(3, prefix(vec![turn("summary", 5, 3)])), None);
+        assert_eq!(ledger.pending, None);
+    }
+
+    #[test]
+    fn a_new_toolset_loses_the_whole_prefix() {
+        let mut ledger = CacheLedger::default();
+        ledger.observe(1, prefix(vec![turn("a", 1, 10)]));
+        let mut next = prefix(vec![turn("a", 1, 10)]);
+        next.tools = seg("narrowed", 60);
+        let found = ledger.observe(2, next).unwrap();
+        assert_eq!(found.cause, BreakCause::Toolset);
+        assert_eq!((found.kept_tokens, found.lost_tokens), (0, 180));
+    }
+
+    #[test]
+    fn changed_knowledge_is_a_promotion_unless_announced() {
+        let mut ledger = CacheLedger::default();
+        ledger.observe(1, prefix(vec![turn("a", 1, 10)]));
+        let mut next = prefix(vec![turn("a", 1, 10)]);
+        next.knowledge = seg("promoted", 40);
+        let found = ledger.observe(2, next).unwrap();
+        assert_eq!(found.cause, BreakCause::Promotion);
+        assert_eq!((found.kept_tokens, found.lost_tokens), (150, 30));
+    }
+
+    #[test]
+    fn the_detail_is_capped_but_the_total_is_not() {
+        let mut ledger = CacheLedger::default();
+        for round in 0..(PREFIX_BREAK_DETAIL_CAP as u32 + 3) {
+            let name = format!("t{round}");
+            ledger.observe(round, prefix(vec![turn(&name, u64::from(round) + 1, 10)]));
+        }
+        assert_eq!(ledger.breaks.len(), PREFIX_BREAK_DETAIL_CAP);
+        assert_eq!(ledger.breaks_omitted, 2);
+        assert_eq!(ledger.lost_tokens, 10 * (PREFIX_BREAK_DETAIL_CAP as u64 + 2));
+    }
+
+    #[test]
+    fn the_ledger_round_trips_through_json() {
+        let mut ledger = CacheLedger::default();
+        ledger.observe(1, prefix(vec![turn("a", 1, 10)]));
+        ledger.observe(2, prefix(vec![turn("b", 2, 10)]));
+        ledger.note_cause(BreakCause::Renewal);
+        let json = serde_json::to_string(&ledger).unwrap();
+        assert_eq!(serde_json::from_str::<CacheLedger>(&json).unwrap(), ledger);
+    }
+}

{deepstrike-0.2.81 → deepstrike-0.2.83}/crates/deepstrike-core/src/context/config.rs

@@ -103,6 +103,10 @@ pub struct ContextConfig {
     /// The provider compacts natively, so the kernel runs neither context collapse nor auto-compact.
     /// Renewal is never delegated: it is decided on the full local history and stays the safety net.
     pub delegate_compaction: bool,
+
+    // ── Notes (plan task 9.1) ───────────────────────────────────────────────
+    /// Tokens the model's notes may hold in the state turn. `0` turns the `note` tool off.
+    pub notes_budget_tokens: u32,
 }
 
 impl Default for ContextConfig {
@@ -127,6 +131,7 @@ impl Default for ContextConfig {
             knowledge_budget_ratio: 0.25,
             delegate_tool_result_clearing: false,
             delegate_compaction: false,
+            notes_budget_tokens: 0,
         }
     }
 }

{deepstrike-0.2.81 → deepstrike-0.2.83}/crates/deepstrike-core/src/context/fault.rs

@@ -11,8 +11,8 @@ pub enum ContextFault {
     InvalidReplay { turn: u32, reason: String },
 }
 
-/// FNV-1a 64-bit — the render layer's cache-stability test fingerprint dialect.
-#[cfg(test)]
+/// FNV-1a 64-bit — the render layer's cache-stability fingerprint dialect (the render tests and
+/// the plan task 8.0 cache ledger).
 pub(crate) fn stable_hash(bytes: &[u8]) -> u64 {
     let mut hash = 0xcbf29ce484222325u64;
     for byte in bytes {

{deepstrike-0.2.81 → deepstrike-0.2.83}/crates/deepstrike-core/src/context/item.rs

@@ -40,6 +40,12 @@ pub enum Relation {
     InheritedFrom,
     /// Plan task 7.4 · the item that read a dependency output back → the run that produced it.
     DependsOn,
+    /// Plan task 9.1 · a note the model wrote → the evidence it came from.
+    DerivedFrom,
+    /// Plan task 9.1 · a note → another note it names.
+    LinksTo,
+    /// Plan task 9.1 · a note → the note it replaced.
+    Supersedes,
 }
 
 impl Relation {
@@ -53,6 +59,9 @@ impl Relation {
             Self::Expands => "expands",
             Self::InheritedFrom => "inherited_from",
             Self::DependsOn => "depends_on",
+            Self::DerivedFrom => "derived_from",
+            Self::LinksTo => "links_to",
+            Self::Supersedes => "supersedes",
         }
     }
 }
@@ -138,7 +147,7 @@ pub(crate) fn is_zero_u32(value: &u32) -> bool {
     *value == 0
 }
 
-fn is_zero_u64(value: &u64) -> bool {
+pub fn is_zero_u64(value: &u64) -> bool {
     *value == 0
 }
 
@@ -163,6 +172,8 @@ pub enum ItemOrigin {
     TaskState,
     Signal,
     ProviderSummary,
+    /// Plan task 9.1 · a note the model wrote with the `note` tool.
+    Note,
 }
 
 impl ItemOrigin {
@@ -200,6 +211,7 @@ impl ItemOrigin {
             Self::TaskState => "task_state",
             Self::Signal => "signal",
             Self::ProviderSummary => "provider_summary",
+            Self::Note => "note",
         }
     }
 
@@ -224,6 +236,7 @@ impl ItemOrigin {
             Self::TaskState => (S::Task, F::Structured, L::Permanent, A::Kernel),
             Self::Signal => (S::Operation, F::Full, L::SingleUse, A::Host),
             Self::ProviderSummary => (S::Operation, F::Full, L::Permanent, A::Provider),
+            Self::Note => (S::Task, F::Full, L::Permanent, A::Model),
         };
         ItemDefaults { scope, fidelity, lease, authority }
     }