Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(sweep): delete old rotated hook ledgers on an opt-in age
Djalma Júnior67f8b959ad0f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4a936f50..4eff58c2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -129,6 +129,25 @@ version in [`docs/changelog/`](docs/changelog/):apply), keeping the checkpoint's frontmatter. Restoring can bring back texta root deleted or purged, so both listing and restoring need the same adminauthority as `/admin/restore-page`. The MCP surface is now 24 tools. (#1307)+- Added an opt-in sweep of old hook event ledgers by age. With `[decay]+ ledger_retention_months = N` (env `AI_MEMORY_DECAY__LEDGER_RETENTION_MONTHS`;+ `0`, the default, disables it; a negative value is rejected at startup), the+ forget sweep deletes a project's `log-YYYY-MM.md` once `N` whole UTC calendar+ months have passed after its month ended. A file qualifies only when its name+ is a rotated ledger **and** its content opens like a ledger, so a page that+ merely shares the name is never deleted; `log.md`, the current month and the+ previous month are never deleted whatever `N` is. The deletion goes through+ the wiki (`Wiki::delete_event_ledger`, under the mutation guard) and never+ writes the database; a dry run reports `ledgers_prunable` and+ `ledger_bytes_prunable` and deletes nothing, and a real run reports+ `ledgers_pruned`, `ledger_bytes_pruned` and `ledger_page_rows_left` (legacy+ page rows it left alone) in the `forget-sweep` / `memory_forget_sweep`+ report. Each removal consults the blocking admission chain on the new+ `delete_event_ledger` op, the same check a page delete runs: a `reject`-policy+ webhook keeps the file, which the sweep counts in `ledgers_undeleted`, keeps+ going and retries on the next run, and non-blocking observers are told only+ after the unlink. The deletion is permanent on disk; the wiki's git history+ keeps the blobs a checkpoint already captured. (#PRNUM)### Changed- `ai-memory setup` now ends by naming the agents to restart and the questiondiff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex 662c703a..0d50b7d0 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -1366,6 +1366,7 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {.with_decay_params(decay_params).with_decay_breadth_weight(config.decay.breadth_weight).with_observation_retention(config.decay.observation_retention())+ .with_ledger_retention(config.decay.ledger_retention()).with_compact_cold_episodic(config.decay.compact_cold_episodic).with_contradiction_band(config.contradiction_band_min, config.contradiction_band_max).with_auto_improve_require_approval(config.auto_improve.require_approval)@@ -1642,6 +1643,7 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {},config.decay.breadth_weight,config.decay.observation_retention(),+ config.decay.ledger_retention(),config.decay.compact_cold_episodic,);// Multi-rung auth assembly:@@ -2122,6 +2124,7 @@ async fn start_maintenance_scheduler(&decay.decay_params(),decay.breadth_weight,decay.observation_retention(),+ decay.ledger_retention(),decay.compact_cold_episodic,decay.cold_cluster_dedup(dedup_embedding),)@@ -2140,6 +2143,9 @@ async fn start_maintenance_scheduler(expired = outcome.expired,hard_deleted = outcome.hard_deleted,observations_pruned = outcome.observations_pruned,+ ledgers_pruned = outcome.ledgers_pruned,+ ledger_bytes_pruned = outcome.ledger_bytes_pruned,+ ledgers_undeleted = outcome.ledgers_undeleted,errors = outcome.errors,elapsed_ms = started.elapsed().as_millis(),"scheduled forget sweep completed"@@ -2539,6 +2545,9 @@ struct ScheduledSweepTickOutcome {expired: usize,hard_deleted: usize,observations_pruned: usize,+ ledgers_pruned: usize,+ ledger_bytes_pruned: u64,+ ledgers_undeleted: usize,errors: usize,}@@ -2550,6 +2559,7 @@ async fn run_scheduled_sweep_tick(decay: &ai_memory_store::DecayParams,breadth_weight: f64,retention: ObservationRetention,+ ledgers: ai_memory_consolidate::LedgerRetention,compact_cold_episodic: bool,dedup: ai_memory_consolidate::ColdClusterDedup,) -> Result<ScheduledSweepTickOutcome> {@@ -2560,7 +2570,7 @@ async fn run_scheduled_sweep_tick(};for scope in scopes {- match ai_memory_consolidate::run_sweep_with_hygiene(+ match ai_memory_consolidate::run_sweep_with_ledgers(reader,writer,Some(wiki),@@ -2571,6 +2581,7 @@ async fn run_scheduled_sweep_tick(retention,compact_cold_episodic,dedup.clone(),+ ledgers,false,).await@@ -2586,6 +2597,9 @@ async fn run_scheduled_sweep_tick(outcome.expired += report.expired.len();outcome.hard_deleted += report.hard_deleted;outcome.observations_pruned += report.observations_pruned;+ outcome.ledgers_pruned += report.ledgers_pruned;+ outcome.ledger_bytes_pruned += report.ledger_bytes_pruned;+ outcome.ledgers_undeleted += report.ledgers_undeleted;}Err(e) => {outcome.errors += 1;@@ -5570,6 +5584,7 @@ mod tests {&decay,0.0,ObservationRetention::default(),+ ai_memory_consolidate::LedgerRetention::default(),false,ai_memory_consolidate::ColdClusterDedup::default(),)diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex 957fb6f5..c9ea0d92 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -106,6 +106,11 @@ pub struct DecaySettings {pub observation_retention_days: i64,/// Observation rows deleted per prune transaction.pub observation_prune_batch: usize,+ /// Age, in whole UTC calendar months after a month ends, past which the+ /// forget sweep deletes that month's hook event ledger+ /// (`log-YYYY-MM.md`). `0` disables the pass; nothing is deleted until an+ /// operator opts in. The current and the previous month are never deleted.+ pub ledger_retention_months: i64,/// A2 extractive tier-down (`[decay] compact_cold_episodic`). When `true`,/// the forget sweep COMPACTS a cold episodic page — keeping its L0 abstract,/// an L1 summary and the L2 keep-token set, dropping the prose — instead of@@ -145,6 +150,7 @@ impl Default for DecaySettings {breadth_weight: 0.0,observation_retention_days: 0,observation_prune_batch: ai_memory_consolidate::DEFAULT_OBSERVATION_PRUNE_BATCH,+ ledger_retention_months: 0,compact_cold_episodic: false,dedup_cold_clusters: false,dedup_min_pts: 0,@@ -203,6 +209,15 @@ impl DecaySettings {}}+ /// Opt-in event ledger age bound consumed by the forget sweep. Disabled+ /// (`months == 0`) unless `[decay] ledger_retention_months` is positive.+ #[must_use]+ pub fn ledger_retention(self) -> ai_memory_consolidate::LedgerRetention {+ ai_memory_consolidate::LedgerRetention {+ months: self.ledger_retention_months,+ }+ }+/// A3 cold-cluster dedup options for the M8 sweep.////// `embedding` is the running server's configured embedder coordinate, or@@ -2384,6 +2399,14 @@ impl Config {if config.decay.observation_prune_batch == 0 {anyhow::bail!("decay.observation_prune_batch must be greater than zero");}+ // The same fail-closed rule for the opt-in ledger sweep: a negative+ // age is not a cutoff, and this pass deletes files.+ if config.decay.ledger_retention_months < 0 {+ anyhow::bail!(+ "decay.ledger_retention_months must be greater than or equal to zero \+ (0 disables ledger deletion)"+ );+ }// A5 zero-LLM contradiction band (`memory_lint`): both edges must be// finite and inside cosine similarity's own range, and the band must// be non-empty. An inverted or out-of-range band would either@@ -3868,6 +3891,9 @@ mod tests {assert_eq!(cfg.decay.observation_retention_days, 0);assert_eq!(cfg.decay.observation_prune_batch, 5_000);assert!(!cfg.decay.observation_retention().is_enabled());+ // Same contract for the hook event ledgers: kept unless opted in.+ assert_eq!(cfg.decay.ledger_retention_months, 0);+ assert!(!cfg.decay.ledger_retention().is_enabled());assert!(!cfg.slots.per_user);assert!(cfg.auto_improve.scheduler.enabled);assert_eq!(cfg.auto_improve.scheduler.interval_secs, 3_600);@@ -4721,6 +4747,32 @@ mod tests {}}+ /// A negative ledger age is rejected at load, like the observation age: a+ /// destructive pass is never configured into a nonsensical shape. `0` is+ /// the valid "disabled" value and loads.+ #[test]+ fn load_rejects_a_negative_ledger_retention() {+ let tmp = TempDir::new().unwrap();+ let config_path = tmp.path().join("config.toml");+ std::fs::write(&config_path, "[decay]\nledger_retention_months = -1\n").unwrap();+ let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))+ .expect_err("a negative ledger retention must fail closed");+ assert!(+ error.to_string().contains("ledger_retention_months"),+ "unexpected error: {error:#}"+ );++ std::fs::write(&config_path, "[decay]\nledger_retention_months = 0\n").unwrap();+ let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))+ .expect("zero disables the pass and must load");+ assert!(!cfg.decay.ledger_retention().is_enabled());++ std::fs::write(&config_path, "[decay]\nledger_retention_months = 12\n").unwrap();+ let cfg = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))+ .expect("a positive age must load");+ assert_eq!(cfg.decay.ledger_retention().months, 12);+ }+/// The consolidation budget must be big enough to leave room for/// observations after the fixed system prompt and page conventions./// Below the floor every consolidation would be evidence-free, so itdiff --git a/crates/ai-memory-cli/templates/config.default.toml b/crates/ai-memory-cli/templates/config.default.tomlindex 091695dd..de2cef58 100644--- a/crates/ai-memory-cli/templates/config.default.toml+++ b/crates/ai-memory-cli/templates/config.default.toml@@ -126,6 +126,17 @@ log_level = "info"# will not shrink after the first prune; the `ai-memory backup` tarball will.# - A quarter of raw capture: observation_retention_days = 90# - Smaller transactions on a slow disk: observation_prune_batch = 2000+#+# The hook event ledgers (log-YYYY-MM.md, one per project per month) are an+# append-only grep trail nothing reads back, and a busy project's month can+# take hundreds of megabytes. Set ledger_retention_months to a positive number+# to let the forget sweep DELETE a ledger once that many whole calendar months+# (UTC) have passed after its month ended. The current and the previous month+# are never deleted, whatever the value, and only files whose content opens+# like a ledger qualify (a page that merely shares the name is untouched).+# Deletion is permanent on disk; git history keeps the old blobs until the+# repository is compacted. 0 (the default) keeps every ledger.+# - Keep a year of ledgers: ledger_retention_months = 12# --- Embeddings (hybrid retrieval) ---------------------------------------# Unset = the 2.0 default: in-process local embeddings (all-MiniLM-L6-v2,# 384-dim), no API key, no data egress. The ~87 MB model is fetched once@@ -147,6 +158,7 @@ hard_delete_after_days = 180breadth_weight = 0.0observation_retention_days = 0 # 0 = never prune raw observationsobservation_prune_batch = 5000 # rows per prune transaction+ledger_retention_months = 0 # 0 = never delete hook event ledgers# Privacy strip.#diff --git a/crates/ai-memory-consolidate/src/lib.rs b/crates/ai-memory-consolidate/src/lib.rsindex 5332df02..d022d57c 100644--- a/crates/ai-memory-consolidate/src/lib.rs+++ b/crates/ai-memory-consolidate/src/lib.rs@@ -92,9 +92,9 @@ pub use lint::{};pub use sweep::{ColdClusterDedup, CompactedPage, DEFAULT_OBSERVATION_PRUNE_BATCH, EmbeddingCoord, EvictedPage,- MergedCluster, ObservationRetention, SweepError, SweepReport, run_sweep,+ LedgerRetention, MergedCluster, ObservationRetention, SweepError, SweepReport, run_sweep,run_sweep_with_breadth, run_sweep_with_compaction, run_sweep_with_hygiene,- run_sweep_with_options,+ run_sweep_with_ledgers, run_sweep_with_options,};pub use types::{ConsolidatedBatch, ConsolidatedPage, ConsolidatedPageUpdate, ConsolidationOutcome, PageKind,diff --git a/crates/ai-memory-consolidate/src/sweep.rs b/crates/ai-memory-consolidate/src/sweep.rsindex 67e56b43..622332ba 100644--- a/crates/ai-memory-consolidate/src/sweep.rs+++ b/crates/ai-memory-consolidate/src/sweep.rs@@ -33,6 +33,14 @@//! visible to its predicate: a session whose summary page was evicted or//! hard-deleted by the passes above keeps its raw capture, because that capture//! is now the only surviving copy.+//!+//! Event ledger pass (opt-in, disabled unless `LedgerRetention::months > 0`)+//! deletes old hook event ledgers (`log-YYYY-MM.md`, one per project per+//! month) once their month ended at least that many whole calendar months ago.+//! Ledgers are files, not pages: the pass runs through the wiki's dedicated+//! ledger delete (confined, under the mutation guard, re-checking the+//! content gate) and never touches the store. The current and the previous+//! month are never deleted whatever the setting.use std::collections::{HashMap, HashSet};@@ -231,6 +239,26 @@ pub struct SweepReport {pub observation_prune_sessions: usize,/// Transactions the prune spent. Makes the batching bound observable.pub observation_prune_batches: usize,+ /// Old hook event ledgers (`log-YYYY-MM.md`) the ledger pass matched.+ /// Reported in both modes; `0` when ledger retention is disabled (the+ /// default) or the caller has no wiki handle.+ pub ledgers_prunable: usize,+ /// Bytes on disk of the ledgers counted in [`Self::ledgers_prunable`].+ pub ledger_bytes_prunable: u64,+ /// Ledger files actually deleted. Always `0` on `dry_run`.+ pub ledgers_pruned: usize,+ /// Bytes freed by the deleted ledgers. Always `0` on `dry_run`.+ pub ledger_bytes_pruned: u64,+ /// Matched ledgers the pass could not delete: an admission webhook with a+ /// `reject` policy refused the removal, or the delete itself failed. The+ /// file is preserved and retried on the next sweep — the ledger answer+ /// to a page delete that a webhook refused (kept, `deleted: false`,+ /// retried). Always `0` on `dry_run`.+ pub ledgers_undeleted: usize,+ /// Matched ledgers that still have a legacy `pages` row (indexed before+ /// #660). The pass deletes the file only and leaves the row alone;+ /// `reclaim-ledger-versions` is the tool that cleans those rows.+ pub ledger_page_rows_left: usize,}/// Opt-in bound on how long raw observations outlive their consolidation.@@ -270,6 +298,27 @@ impl ObservationRetention {/// Default rows per prune transaction.pub const DEFAULT_OBSERVATION_PRUNE_BATCH: usize = 5_000;+/// Opt-in age bound for the hook event ledgers (`log-YYYY-MM.md`).+///+/// A type of its own for the same reason as [`ObservationRetention`]: the+/// sweep entry points are public and widening an existing struct would break+/// downstream callers that build it directly.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]+pub struct LedgerRetention {+ /// A ledger is deletable once this many whole calendar months (UTC) have+ /// passed after its own month ended. `0` disables the pass entirely — the+ /// default, so an existing install keeps every ledger.+ pub months: i64,+}++impl LedgerRetention {+ /// `true` when the pass is enabled and can delete something.+ #[must_use]+ pub const fn is_enabled(self) -> bool {+ self.months > 0+ }+}+/// Errors raised by the sweep.#[derive(Debug, Error)]#[non_exhaustive]@@ -283,6 +332,9 @@ pub enum SweepError {/// The opt-in observation retention age was negative.#[error("decay observation_retention_days must be greater than or equal to zero")]InvalidObservationRetention,+ /// The opt-in ledger retention age was negative.+ #[error("decay ledger_retention_months must be greater than or equal to zero")]+ InvalidLedgerRetention,}const US_PER_DAY: f64 = 86_400_000_000.0;@@ -467,6 +519,98 @@ pub async fn run_sweep_with_hygiene(compact_cold_episodic: bool,dedup: ColdClusterDedup,dry_run: bool,+) -> Result<SweepReport, SweepError> {+ run_sweep_with_ledgers(+ reader,+ writer,+ wiki,+ workspace_id,+ project_id,+ params,+ breadth_weight,+ retention,+ compact_cold_episodic,+ dedup,+ LedgerRetention::default(),+ dry_run,+ )+ .await+}++/// Run a sweep with everything [`run_sweep_with_hygiene`] does plus the opt-in+/// event ledger pass, at `Timestamp::now()`.+///+/// The ledger pass runs after the observation prune and, like the other+/// wiki-routed passes, needs a `wiki` handle (without one it is skipped). With+/// `ledgers.months == 0` (the default everywhere) it does nothing and this is+/// byte-identical to [`run_sweep_with_hygiene`]. A dry run lists the files and+/// bytes it would delete and deletes nothing.+///+/// # Errors+/// Returns [`SweepError::InvalidLedgerRetention`] for a negative age, in+/// addition to the errors documented by [`run_sweep_with_hygiene`].+#[allow(clippy::too_many_arguments)]+pub async fn run_sweep_with_ledgers(+ reader: &ReaderPool,+ writer: &WriterHandle,+ wiki: Option<&Wiki>,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ params: &DecayParams,+ breadth_weight: f64,+ retention: ObservationRetention,+ compact_cold_episodic: bool,+ dedup: ColdClusterDedup,+ ledgers: LedgerRetention,+ dry_run: bool,+) -> Result<SweepReport, SweepError> {+ run_sweep_at(+ reader,+ writer,+ wiki,+ workspace_id,+ project_id,+ params,+ breadth_weight,+ retention,+ compact_cold_episodic,+ dedup,+ ledgers,+ Timestamp::now(),+ dry_run,+ )+ .await+}++/// The full-knob sweep run with its caller-supplied instant: the scoring,+/// TTL and observation cutoffs and the ledger pass's month arithmetic all+/// read `now`, so the passes that were already evaluated at sweep start keep+/// one consistent instant. (The aged-tombstone cutoff stays a fresh+/// `Timestamp::now()`, because it has to sit after this run's own eviction+/// stamps — see the inline note.)+///+/// Production callers go through [`run_sweep_with_ledgers`] (which passes+/// `Timestamp::now()`), so this changes no production behaviour. The seam+/// exists so the integration tests can hold the pass at a fixed UTC instant,+/// away from the real month boundary a wall-clock run could cross mid-test.+///+/// # Errors+/// Same as [`run_sweep_with_ledgers`].+#[allow(clippy::too_many_arguments)]+pub(crate) async fn run_sweep_at(+ reader: &ReaderPool,+ writer: &WriterHandle,+ wiki: Option<&Wiki>,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ params: &DecayParams,+ breadth_weight: f64,+ retention: ObservationRetention,+ compact_cold_episodic: bool,+ dedup: ColdClusterDedup,+ ledgers: LedgerRetention,+ now: Timestamp,+ dry_run: bool,) -> Result<SweepReport, SweepError> {if !breadth_weight.is_finite() || breadth_weight < 0.0 {return Err(SweepError::InvalidBreadthWeight);@@ -474,10 +618,13 @@ pub async fn run_sweep_with_hygiene(if retention.days < 0 {return Err(SweepError::InvalidObservationRetention);}+ if ledgers.months < 0 {+ return Err(SweepError::InvalidLedgerRetention);+ }let candidates = reader.decay_candidates(workspace_id, project_id).await?;let breadth =access_breadth_for_scoring(reader, workspace_id, project_id, breadth_weight).await?;- let now_us = Timestamp::now().as_microsecond();+ let now_us = now.as_microsecond();let mut evicted = Vec::new();let mut compacted: Vec<CompactedPage> = Vec::new();@@ -557,7 +704,7 @@ pub async fn run_sweep_with_hygiene(let mut observations_pruned = 0usize;let mut observation_prune_sessions = 0usize;let mut observation_prune_batches = 0usize;- let observation_cutoff_us = Timestamp::now()+ let observation_cutoff_us = now.as_microsecond().saturating_sub(retention.days.saturating_mul(US_PER_DAY_I64));if retention.is_enabled() {@@ -722,6 +869,12 @@ pub async fn run_sweep_with_hygiene(if let Some(wiki) = wiki {let grace_days = params.hard_delete_after_days.max(0);+ // A FRESH clock read, deliberately not the caller's `now`: the+ // evictions above stamp their tombstones' `superseded_at` as they+ // go, and the grace-0 case hard-deletes exactly those. The cutoff+ // has to sit after this run's own stamps, or a tombstone the run+ // just wrote is not "older than itself" and the grace-0 purge+ // silently skips it.let cutoff_us = Timestamp::now().as_microsecond().saturating_sub(grace_days.saturating_mul(US_PER_DAY_I64));@@ -781,6 +934,24 @@ pub async fn run_sweep_with_hygiene(}}+ // Event ledger pass, last: files, not pages, so nothing above depends on it+ // and it depends on nothing above. Both modes list; only a real run deletes.+ let ledger_outcome = match wiki {+ Some(wiki) if ledgers.is_enabled() => {+ sweep_event_ledgers(+ reader,+ wiki,+ workspace_id,+ project_id,+ ledgers,+ now,+ dry_run,+ )+ .await+ }+ _ => LedgerSweepOutcome::default(),+ };+Ok(SweepReport {dry_run,candidates_evaluated: candidates.len(),@@ -793,9 +964,150 @@ pub async fn run_sweep_with_hygiene(observations_pruned,observation_prune_sessions,observation_prune_batches,+ ledgers_prunable: ledger_outcome.matched,+ ledger_bytes_prunable: ledger_outcome.matched_bytes,+ ledgers_pruned: ledger_outcome.deleted,+ ledger_bytes_pruned: ledger_outcome.deleted_bytes,+ ledgers_undeleted: ledger_outcome.undeleted,+ ledger_page_rows_left: ledger_outcome.page_rows_left,})}+/// What the ledger pass found and did, folded into the [`SweepReport`].+#[derive(Debug, Default, PartialEq, Eq)]+pub(crate) struct LedgerSweepOutcome {+ pub(crate) matched: usize,+ pub(crate) matched_bytes: u64,+ pub(crate) deleted: usize,+ pub(crate) deleted_bytes: u64,+ /// Matched ledgers whose removal failed (a refusing admission webhook or+ /// an IO error). Kept and retried by the next sweep.+ pub(crate) undeleted: usize,+ pub(crate) page_rows_left: usize,+}++/// Position of a calendar month on one line: `year * 12 + (month - 1)`.+fn month_index(year: i64, month: i64) -> i64 {+ year.saturating_mul(12).saturating_add(month - 1)+}++/// Month index of a `log-YYYY-MM.md` file name, or `None` when the name is not+/// that shape or the month is not 1..=12 (a shape the content gate cannot+/// vouch for is never an age decision).+fn ledger_month_index(file_name: &str) -> Option<i64> {+ if !ai_memory_core::log_ledger::is_rotated_log_ledger_path(file_name) {+ return None;+ }+ let stem = file_name.strip_prefix("log-")?.strip_suffix(".md")?;+ let year: i64 = stem.get(..4)?.parse().ok()?;+ let month: i64 = stem.get(5..)?.parse().ok()?;+ (1..=12).contains(&month).then(|| month_index(year, month))+}++/// Whether a ledger whose month sits at `ledger_idx` may be deleted when the+/// current month sits at `now_idx`, with `months` as the retention age.+///+/// Two independent rules, both required:+///+/// - the writer guard: the current and the previous month are never+/// deletable. The hook appender may still write to them (the previous month+/// takes late-delivered events), so no setting can make them eligible;+/// - the age rule: at least `months` whole calendar months have passed since+/// the ledger's month ended (`ledger_idx + 1 + months <= now_idx`).+///+/// For a positive `months` the age rule already implies the guard; the guard+/// stays a separate line so the protection does not depend on that arithmetic+/// or on the caller's gate (it is exercised directly with `months == 0`).+fn ledger_is_expired(ledger_idx: i64, now_idx: i64, months: i64) -> bool {+ if ledger_idx >= now_idx.saturating_sub(1) {+ return false;+ }+ ledger_idx.saturating_add(months).saturating_add(1) <= now_idx+}++/// The ledger pass: list the project's event ledgers, pick the expired ones+/// and, unless `dry_run`, delete them through [`Wiki::delete_event_ledger`],+/// which consults the blocking admission chain (a `reject`-policy webhook+/// keeps the file).+///+/// Best-effort like the other wiki-routed passes: a listing or per-file+/// failure (an admission refusal, an IO error) is logged and counted in+/// [`LedgerSweepOutcome::undeleted`], the file is kept, and the pass keeps+/// going — the same answer a refused page delete gets, which the sweep+/// retries on the next run. The store is only read (to say how many matched+/// ledgers still have a legacy page row); those rows are left alone.+async fn sweep_event_ledgers(+ reader: &ReaderPool,+ wiki: &Wiki,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ ledgers: LedgerRetention,+ now: Timestamp,+ dry_run: bool,+) -> LedgerSweepOutcome {+ let mut outcome = LedgerSweepOutcome::default();+ let found = match wiki.list_event_ledgers(workspace_id, project_id) {+ Ok(found) => found,+ Err(error) => {+ tracing::warn!(+ %error,+ "forget sweep: listing event ledgers failed; retrying on next sweep"+ );+ return outcome;+ }+ };+ let now_utc = now.to_zoned(jiff::tz::TimeZone::UTC);+ let now_idx = month_index(i64::from(now_utc.year()), i64::from(now_utc.month()));+ for ledger in found {+ let Some(idx) = ledger_month_index(&ledger.file_name) else {+ continue;+ };+ if !ledger_is_expired(idx, now_idx, ledgers.months) {+ continue;+ }+ outcome.matched += 1;+ outcome.matched_bytes = outcome.matched_bytes.saturating_add(ledger.bytes);+ match reader+ .latest_page_id_by_ids(workspace_id, project_id, ledger.file_name.clone())+ .await+ {+ Ok(Some(_)) => outcome.page_rows_left += 1,+ Ok(None) => {}+ Err(error) => tracing::warn!(+ file = %ledger.file_name,+ %error,+ "forget sweep: could not check a ledger for a legacy page row"+ ),+ }+ if dry_run {+ continue;+ }+ match wiki+ .delete_event_ledger(workspace_id, project_id, &ledger.file_name)+ .await+ {+ Ok(Some(bytes)) => {+ outcome.deleted += 1;+ outcome.deleted_bytes = outcome.deleted_bytes.saturating_add(bytes);+ }+ // Gone or no longer a ledger since the listing: nothing to delete.+ Ok(None) => {}+ Err(error) => {+ // A refusing webhook (or a failed delete): the file stays,+ // the pass keeps going, the next sweep retries it — the same+ // shape as a refused page delete above.+ outcome.undeleted += 1;+ tracing::warn!(+ file = %ledger.file_name,+ %error,+ "forget sweep: event ledger delete refused or failed; retrying on next sweep"+ );+ }+ }+ }+ outcome+}+/// A cold page (scored below `cold_threshold`) captured once so the A3 dedup/// pass and the evict/compact remainder read the same materialised set.///@@ -1282,4 +1594,82 @@ mod tests {assert_eq!(elapsed_days(1_000, 2_000), 0.0);assert!(elapsed_days(US_PER_DAY as i64, 0) >= 1.0);}++ #[test]+ fn ledger_month_index_reads_only_real_months() {+ assert_eq!(+ ledger_month_index("log-2026-07.md"),+ Some(month_index(2026, 7))+ );+ assert_eq!(+ ledger_month_index("log-2026-12.md"),+ Some(month_index(2026, 12))+ );+ for name in [+ "log.md",+ "log-2026-13.md",+ "log-2026-00.md",+ "log-2026-7.md",+ "log-2026-07-15.md",+ "notes/log-2026-07.md",+ "LOG-2026-07.md",+ ] {+ assert_eq!(+ ledger_month_index(name),+ None,+ "{name} must not date a ledger"+ );+ }+ // Consecutive months, across a year boundary, are consecutive indices.+ assert_eq!(+ month_index(2027, 1) - month_index(2026, 12),+ 1,+ "december to january is one month"+ );+ }++ /// The age rule: a ledger is deletable once `months` whole calendar months+ /// passed after its own month ended, and not a month earlier.+ #[test]+ fn ledger_age_rule_counts_whole_months_after_the_month_ended() {+ let now = month_index(2026, 10);+ // N = 3: June ended Jul 1; Jul, Aug and Sep are the three whole months+ // after it, so June is deletable in October. July has only Aug and Sep+ // behind it (October is not over), so it is one month short.+ assert!(ledger_is_expired(month_index(2026, 5), now, 3));+ assert!(ledger_is_expired(month_index(2026, 6), now, 3));+ assert!(!ledger_is_expired(month_index(2026, 7), now, 3));+ assert!(!ledger_is_expired(month_index(2026, 8), now, 3));+ assert!(!ledger_is_expired(month_index(2026, 9), now, 3));+ assert!(!ledger_is_expired(month_index(2026, 10), now, 3));+ // N = 1 across a year boundary.+ let jan = month_index(2027, 1);+ assert!(ledger_is_expired(month_index(2026, 11), jan, 1));+ assert!(!ledger_is_expired(month_index(2026, 12), jan, 1));+ }++ /// The writer guard holds whatever the age: the current and the previous+ /// month are never deletable, even with `months == 0` (which the sweep never+ /// passes, but which makes the age rule alone delete last month) or a+ /// retention so large the arithmetic saturates. Mutation captured: dropping+ /// the guard line makes the `months == 0` case delete the previous month.+ #[test]+ fn ledger_guard_protects_the_current_and_previous_month_regardless_of_age() {+ let now = month_index(2026, 10);+ for months in [0, 1, 2, 12, i64::MAX] {+ assert!(+ !ledger_is_expired(now, now, months),+ "the current month must be kept at months={months}"+ );+ assert!(+ !ledger_is_expired(now - 1, now, months),+ "the previous month must be kept at months={months}"+ );+ }+ // Control: with no retention the age rule alone reaches two months back,+ // so the cases above are the guard's doing.+ assert!(ledger_is_expired(now - 2, now, 0));+ // A retention too large to ever elapse deletes nothing, without panic.+ assert!(!ledger_is_expired(now - 2, now, i64::MAX));+ }}diff --git a/crates/ai-memory-consolidate/tests/suite/ledger_sweep.rs b/crates/ai-memory-consolidate/tests/suite/ledger_sweep.rsnew file mode 100644index 00000000..22a71a79--- /dev/null+++ b/crates/ai-memory-consolidate/tests/suite/ledger_sweep.rs@@ -0,0 +1,542 @@+//! The opt-in event ledger sweep, end to end through a real Store + Wiki.+//!+//! Hook event ledgers (`log-YYYY-MM.md`) are files nothing reads back, and a+//! busy project's month can hold hundreds of megabytes. The sweep deletes the+//! old ones when `[decay] ledger_retention_months` is positive. These tests+//! hold the pass to what makes that safe:+//!+//! 1. **Off by default.** Nothing is deleted at `LedgerRetention::default()`.+//! 2. **A dry run lists and keeps.** Files and bytes are reported, nothing goes.+//! 3. **Age, not name alone.** An old ledger goes; a recent one stays; the+//! current and the previous month stay even with a one-month retention.+//! 4. **Content, not name alone.** An ordinary page named `log-YYYY-MM.md` is+//! never deleted, and neither is the unrotated `log.md`.+//! 5. **Scope.** Another project's ledgers are untouched.+//! 6. **Files, not pages.** A legacy `pages` row for a deleted ledger is left+//! alone and counted in the report.+//! 7. **Admission.** The delete consults the blocking admission chain the way+//! a page delete does: a `reject`-policy webhook keeps the file and the+//! report counts it; an accepting chain removes the file and tells the+//! non-blocking observers afterwards.+//!+//! Fixture names and the pass age against one fixed UTC instant (mid-month,+//! away from a boundary), so a run can never cross the real month boundary+//! between the fixture and the sweep.++use std::io::{Read, Write};+use std::sync::{Arc, Mutex};++use ai_memory_consolidate::sweep::run_sweep_at;+use ai_memory_consolidate::{+ ColdClusterDedup, LedgerRetention, ObservationRetention, SweepError, SweepReport,+ run_sweep_with_ledgers,+};+use ai_memory_core::{NewPage, PagePath, ProjectId, Tier, WorkspaceId};+use ai_memory_store::{DecayParams, Store};+use ai_memory_wiki::{AdmissionChain, AdmissionOp, FailurePolicy, WebhookConfig, Wiki};+use jiff::Timestamp;+use tempfile::TempDir;++/// What a hook ledger opens with: `## [ts] <event> | <title>`.+const LEDGER_BODY: &str = "## [2025-01-03T10:00:00Z] user-prompt | hello\n\+ ## [2025-01-03T10:00:05Z] stop | done\n";+/// An ordinary page that merely shares the ledger's file name.+const PAGE_BODY: &str =+ "# Meeting notes\n\nNot a hook ledger, just a page someone named log-*.md.\n";++/// One fixed instant, mid-UTC-month: the fixture names and the pass age+/// against this same clock, so no run can straddle the real month boundary.+/// The epoch seconds are 2026-07-15T12:00:00Z.+fn now() -> Timestamp {+ Timestamp::new(1_784_116_800, 0).unwrap()+}++struct Fixture {+ _tmp: TempDir,+ store: Store,+ wiki: Wiki,+ ws: WorkspaceId,+ proj: ProjectId,+ other: ProjectId,+}++async fn fixture_with_chain(chain: Option<AdmissionChain>) -> Fixture {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "ledgers", None)+ .await+ .unwrap();+ let other = store+ .writer+ .get_or_create_project(ws, "neighbour", None)+ .await+ .unwrap();+ let mut wiki = Wiki::new(tmp.path(), store.writer.clone())+ .unwrap()+ .with_store_reader(store.reader.clone());+ if let Some(chain) = chain {+ wiki = wiki.with_admission_chain(chain);+ }+ for project in [proj, other] {+ std::fs::create_dir_all(wiki.project_root(ws, project)).unwrap();+ }+ Fixture {+ _tmp: tmp,+ store,+ wiki,+ ws,+ proj,+ other,+ }+}++async fn fixture() -> Fixture {+ fixture_with_chain(None).await+}++/// `log-YYYY-MM.md` for the month `back` months before the fixture's month.+fn month_file(back: i64) -> String {+ let now_utc = now().to_zoned(jiff::tz::TimeZone::UTC);+ let index = i64::from(now_utc.year()) * 12 + i64::from(now_utc.month()) - 1 - back;+ format!(+ "log-{:04}-{:02}.md",+ index.div_euclid(12),+ index.rem_euclid(12) + 1+ )+}++fn put(fx: &Fixture, project: ProjectId, name: &str, body: &str) -> std::path::PathBuf {+ let path = fx.wiki.project_root(fx.ws, project).join(name);+ std::fs::write(&path, body).unwrap();+ path+}++async fn sweep(fx: &Fixture, project: ProjectId, months: i64, dry_run: bool) -> SweepReport {+ run_sweep_at(+ &fx.store.reader,+ &fx.store.writer,+ Some(&fx.wiki),+ fx.ws,+ project,+ &DecayParams::default(),+ 0.0,+ ObservationRetention::default(),+ false,+ ColdClusterDedup::default(),+ LedgerRetention { months },+ now(),+ dry_run,+ )+ .await+ .unwrap()+}++/// Minimal loopback webhook server for the admission tests: answers every+/// POST with one fixed status and records the `X-Memory-Op` header of each+/// request. Built on `std::net` — this harness has no HTTP server crate as a+/// dev-dependency — and it speaks just enough HTTP/1.1 for the engine's+/// `reqwest` client: one `Content-Length`-framed body per call, answered with+/// `Connection: close` so the client opens a fresh connection per call. The+/// listener thread lives for the rest of the process, as the test-only+/// `dead_http_endpoint` helper does.+fn webhook(status: u16, ops: &Arc<Mutex<Vec<String>>>) -> String {+ let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();+ let port = listener.local_addr().unwrap().port();+ let ops = Arc::clone(ops);+ std::thread::spawn(move || {+ for stream in listener.incoming() {+ let Ok(mut stream) = stream else { continue };+ let _ = stream.set_read_timeout(Some(std::time::Duration::from_secs(5)));+ let mut buf = Vec::new();+ let mut chunk = [0u8; 4096];+ // Read the head until the blank line that ends the headers.+ let head_end = loop {+ if let Some(pos) = buf.windows(4).position(|w| w == b"\r\n\r\n") {+ break Some(pos + 4);+ }+ match stream.read(&mut chunk) {+ Ok(0) | Err(_) => break None,+ Ok(n) => buf.extend_from_slice(&chunk[..n]),+ }+ };+ let Some(end) = head_end else { continue };+ let head = String::from_utf8_lossy(&buf[..end]).to_lowercase();+ let op = head+ .lines()+ .find_map(|l| l.strip_prefix("x-memory-op:").map(str::to_owned))+ .map(|v| v.trim().to_string());+ let body_len = head+ .lines()+ .find_map(|l| l.strip_prefix("content-length:"))+ .and_then(|v| v.trim().parse::<usize>().ok())+ .unwrap_or(0);+ // Drain the body before answering: the client may still be+ // writing it, and a premature close surfaces as a spurious+ // connection error.+ while buf.len() < end + body_len {+ match stream.read(&mut chunk) {+ Ok(0) | Err(_) => break,+ Ok(n) => buf.extend_from_slice(&chunk[..n]),+ }+ }+ if let Some(op) = op {+ ops.lock().unwrap().push(op);+ }+ let resp =+ format!("HTTP/1.1 {status}\r\ncontent-length: 0\r\nconnection: close\r\n\r\n");+ let _ = stream.write_all(resp.as_bytes());+ let _ = stream.flush();+ }+ });+ format!("http://127.0.0.1:{port}")+}++#[tokio::test]+async fn the_default_configuration_deletes_no_ledger() {+ let fx = fixture().await;+ let old = put(&fx, fx.proj, &month_file(36), LEDGER_BODY);++ let report = sweep(&fx, fx.proj, 0, false).await;++ assert!(old.exists(), "retention 0 must keep every ledger");+ assert_eq!(report.ledgers_prunable, 0);+ assert_eq!(report.ledgers_pruned, 0);+ assert_eq!(report.ledger_bytes_prunable, 0);+ assert_eq!(report.ledger_bytes_pruned, 0);+}++#[tokio::test]+async fn a_dry_run_reports_files_and_bytes_and_deletes_nothing() {+ let fx = fixture().await;+ let old_a = put(&fx, fx.proj, &month_file(24), LEDGER_BODY);+ let old_b = put(&fx, fx.proj, &month_file(10), LEDGER_BODY);+ let recent = put(&fx, fx.proj, &month_file(1), LEDGER_BODY);++ let report = sweep(&fx, fx.proj, 3, true).await;++ assert!(report.dry_run);+ assert_eq!(report.ledgers_prunable, 2);+ assert_eq!(report.ledger_bytes_prunable, 2 * LEDGER_BODY.len() as u64);+ assert_eq!(report.ledgers_pruned, 0, "a dry run deletes nothing");+ assert_eq!(report.ledger_bytes_pruned, 0);+ assert!(old_a.exists() && old_b.exists() && recent.exists());+}++#[tokio::test]+async fn an_old_ledger_is_deleted_and_a_recent_one_is_kept() {+ let fx = fixture().await;+ let old = put(&fx, fx.proj, &month_file(24), LEDGER_BODY);+ let four_back = put(&fx, fx.proj, &month_file(4), LEDGER_BODY);+ // Three whole months have not yet passed after this month ended.+ let three_back = put(&fx, fx.proj, &month_file(3), LEDGER_BODY);+ let recent = put(&fx, fx.proj, &month_file(0), LEDGER_BODY);++ let report = sweep(&fx, fx.proj, 3, false).await;++ assert!(!old.exists(), "a two-year-old ledger goes");+ assert!(+ !four_back.exists(),+ "the first month past the threshold goes"+ );+ assert!(+ three_back.exists(),+ "one month short of the threshold stays"+ );+ assert!(recent.exists(), "the current month stays");+ assert_eq!(report.ledgers_prunable, 2);+ assert_eq!(report.ledgers_pruned, 2);+ assert_eq!(report.ledger_bytes_pruned, 2 * LEDGER_BODY.len() as u64);+ assert!(!report.dry_run);+}++#[tokio::test]+async fn the_current_and_previous_month_survive_even_a_one_month_retention() {+ let fx = fixture().await;+ let current = put(&fx, fx.proj, &month_file(0), LEDGER_BODY);+ let previous = put(&fx, fx.proj, &month_file(1), LEDGER_BODY);+ // Control: the month before that is old enough at N = 1 and must go, so the+ // two survivors above are protected by the guard and not by an empty pass.+ let two_back = put(&fx, fx.proj, &month_file(2), LEDGER_BODY);++ let report = sweep(&fx, fx.proj, 1, false).await;++ assert!(+ current.exists(),+ "the writer may still append to this month"+ );+ assert!(previous.exists(), "late events still land in last month");+ assert!(!two_back.exists(), "control: a closed month is deletable");+ assert_eq!(report.ledgers_pruned, 1);+}++#[tokio::test]+async fn an_ordinary_page_named_like_a_ledger_is_never_deleted() {+ let fx = fixture().await;+ let page = put(&fx, fx.proj, &month_file(36), PAGE_BODY);+ // Frontmatter does not make a page a ledger either (a migrated store stamps+ // frontmatter on real ledgers, so the gate looks past it to the body).+ let framed = put(+ &fx,+ fx.proj,+ &month_file(35),+ "---\ntitle: Quarterly log\n---\n\n# Quarterly log\n\nplain text\n",+ );+ // The unrotated ledger is never swept, whatever its content.+ let unrotated = put(&fx, fx.proj, "log.md", LEDGER_BODY);+ // Control: a real old ledger in the same project is deleted by the same run.+ let ledger = put(&fx, fx.proj, &month_file(34), LEDGER_BODY);++ let report = sweep(&fx, fx.proj, 3, false).await;++ assert!(page.exists(), "a page that only shares the name must stay");+ assert_eq!(std::fs::read_to_string(&page).unwrap(), PAGE_BODY);+ assert!(+ framed.exists(),+ "frontmatter without a ledger entry must stay"+ );+ assert!(unrotated.exists(), "log.md is never swept");+ assert!(!ledger.exists(), "control: the real ledger goes");+ assert_eq!(report.ledgers_pruned, 1);+ // The report must not claim files it will not delete: the pages are not+ // even matched.+ assert_eq!(report.ledgers_prunable, 1);+ assert_eq!(report.ledger_bytes_prunable, LEDGER_BODY.len() as u64);+}++#[tokio::test]+async fn another_projects_ledgers_are_untouched() {+ let fx = fixture().await;+ let mine = put(&fx, fx.proj, &month_file(24), LEDGER_BODY);+ let theirs = put(&fx, fx.other, &month_file(24), LEDGER_BODY);++ let report = sweep(&fx, fx.proj, 3, false).await;++ assert!(!mine.exists(), "the swept project's ledger goes");+ assert!(theirs.exists(), "a neighbouring project's ledger stays");+ assert_eq!(report.ledgers_pruned, 1);++ // And the neighbour's own sweep is what reaches its file.+ let report = sweep(&fx, fx.other, 3, false).await;+ assert!(!theirs.exists());+ assert_eq!(report.ledgers_pruned, 1);+}++#[tokio::test]+async fn a_legacy_page_row_is_left_alone_and_reported() {+ let fx = fixture().await;+ let name = month_file(24);+ put(&fx, fx.proj, &name, LEDGER_BODY);+ fx.store+ .writer+ .upsert_page(NewPage {+ workspace_id: fx.ws,+ project_id: fx.proj,+ path: PagePath::new(name.clone()).unwrap(),+ title: name.clone(),+ body: LEDGER_BODY.into(),+ tier: Tier::Episodic,+ frontmatter_json: serde_json::json!({}),+ pinned: false,+ links: Vec::new(),+ author_id: None,+ expires_at: None,+ entities: Vec::new(),+ evidence: Vec::new(),+ })+ .await+ .unwrap();++ let report = sweep(&fx, fx.proj, 3, false).await;++ assert_eq!(report.ledgers_pruned, 1, "the file goes");+ assert_eq!(+ report.ledger_page_rows_left, 1,+ "the legacy row is reported"+ );+ assert!(+ fx.store+ .reader+ .latest_page_id_by_ids(fx.ws, fx.proj, name)+ .await+ .unwrap()+ .is_some(),+ "the sweep never touches the store for a ledger"+ );+}++#[tokio::test]+async fn a_negative_ledger_retention_stops_the_sweep() {+ let fx = fixture().await;+ let old = put(&fx, fx.proj, &month_file(24), LEDGER_BODY);++ let error = run_sweep_with_ledgers(+ &fx.store.reader,+ &fx.store.writer,+ Some(&fx.wiki),+ fx.ws,+ fx.proj,+ &DecayParams::default(),+ 0.0,+ ObservationRetention::default(),+ false,+ ColdClusterDedup::default(),+ LedgerRetention { months: -1 },+ false,+ )+ .await+ .expect_err("a negative age is not a cutoff");++ assert!(matches!(error, SweepError::InvalidLedgerRetention));+ assert!(old.exists());+}++#[tokio::test]+async fn without_a_wiki_handle_the_pass_is_skipped() {+ let fx = fixture().await;+ let old = put(&fx, fx.proj, &month_file(24), LEDGER_BODY);++ let report = run_sweep_with_ledgers(+ &fx.store.reader,+ &fx.store.writer,+ None,+ fx.ws,+ fx.proj,+ &DecayParams::default(),+ 0.0,+ ObservationRetention::default(),+ false,+ ColdClusterDedup::default(),+ LedgerRetention { months: 3 },+ false,+ )+ .await+ .unwrap();++ assert!(+ old.exists(),+ "a bare-store caller has no wiki to delete through"+ );+ assert_eq!(report.ledgers_pruned, 0);+}++#[tokio::test]+async fn a_rejecting_admission_webhook_keeps_the_ledger_and_the_report_says_so() {+ let ops = Arc::new(Mutex::new(Vec::new()));+ let base = webhook(403, &ops);+ let chain = AdmissionChain::new(vec![WebhookConfig {+ name: "refuse-ledger-deletes".into(),+ url: format!("{base}/hook"),+ timeout_ms: 2_000,+ failure_policy: FailurePolicy::Reject,+ events: vec![AdmissionOp::DeleteEventLedger],+ blocking: true,+ }])+ .unwrap();+ let fx = fixture_with_chain(Some(chain)).await;+ let old = put(&fx, fx.proj, &month_file(24), LEDGER_BODY);+ let recent = put(&fx, fx.proj, &month_file(0), LEDGER_BODY);++ let report = run_sweep_at(+ &fx.store.reader,+ &fx.store.writer,+ Some(&fx.wiki),+ fx.ws,+ fx.proj,+ &DecayParams::default(),+ 0.0,+ ObservationRetention::default(),+ false,+ ColdClusterDedup::default(),+ LedgerRetention { months: 3 },+ now(),+ false,+ )+ .await+ .unwrap();++ assert!(+ old.exists(),+ "a refusing webhook keeps the file, like a refused page delete"+ );+ assert_eq!(+ std::fs::read_to_string(&old).unwrap(),+ LEDGER_BODY,+ "the file is not just present, it is intact"+ );+ assert!(recent.exists());+ assert_eq!(report.ledgers_prunable, 1);+ assert_eq!(report.ledgers_pruned, 0, "nothing went");+ assert_eq!(+ report.ledgers_undeleted, 1,+ "the report counts the refusal, so it is visible without reading logs"+ );+ assert_eq!(+ *ops.lock().unwrap(),+ vec!["delete_event_ledger".to_string()],+ "the sweep asked the ledger op, not a page delete"+ );+}++#[tokio::test]+async fn an_accepting_admission_webhook_is_told_after_the_file_is_gone() {+ let decider_ops = Arc::new(Mutex::new(Vec::new()));+ let observer_ops = Arc::new(Mutex::new(Vec::new()));+ let decider = webhook(204, &decider_ops);+ let observer = webhook(204, &observer_ops);+ let chain = AdmissionChain::new(vec![+ WebhookConfig {+ name: "ledger-gate".into(),+ url: format!("{decider}/gate"),+ timeout_ms: 2_000,+ failure_policy: FailurePolicy::Reject,+ events: vec![AdmissionOp::DeleteEventLedger],+ blocking: true,+ },+ WebhookConfig {+ name: "ledger-mirror".into(),+ url: format!("{observer}/mirror"),+ timeout_ms: 2_000,+ failure_policy: FailurePolicy::Ignore,+ events: vec![AdmissionOp::DeleteEventLedger],+ blocking: false,+ },+ ])+ .unwrap();+ let fx = fixture_with_chain(Some(chain)).await;+ let old = put(&fx, fx.proj, &month_file(24), LEDGER_BODY);++ let report = sweep(&fx, fx.proj, 3, false).await;++ assert!(!old.exists(), "the accepting chain lets the delete through");+ assert_eq!(report.ledgers_pruned, 1);+ assert_eq!(report.ledgers_undeleted, 0);+ assert_eq!(+ *decider_ops.lock().unwrap(),+ vec!["delete_event_ledger".to_string()],+ "the blocking gate was consulted before the removal"+ );+ // The observer is dispatched fire-and-forget after the removal, like a+ // page delete tells its mirrors; poll for it instead of racing it.+ tokio::time::timeout(std::time::Duration::from_secs(5), async {+ loop {+ if observer_ops+ .lock()+ .unwrap()+ .iter()+ .any(|op| op == "delete_event_ledger")+ {+ break;+ }+ tokio::time::sleep(std::time::Duration::from_millis(10)).await;+ }+ })+ .await+ .expect("the observer was told after the file was gone");+}diff --git a/crates/ai-memory-consolidate/tests/suite/mod.rs b/crates/ai-memory-consolidate/tests/suite/mod.rsindex de5b6717..8ccde9c2 100644--- a/crates/ai-memory-consolidate/tests/suite/mod.rs+++ b/crates/ai-memory-consolidate/tests/suite/mod.rs@@ -14,6 +14,7 @@ mod embeddings;mod entropy_experience;#[cfg(unix)]mod eval_results;+mod ledger_sweep;mod lifecycle;mod local_embeddings;mod multi_machine;diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex ca1e8dbc..89436b27 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -59,11 +59,12 @@ use std::pin::Pin;use ai_memory_consolidate::{AutoImproveReviewConfig, AutoImproveTelemetryParams, AutoImproveTelemetryReport, Bootstrap,- BootstrapConfig, BootstrapOutcome, BootstrapSource, CuratorParams, CuratorReport,- EmbedBackfillCounts, EmbedBackfillOptions, ObservationRetention, SourceCounts,- prune_sources_to_budget, render_auto_improve_telemetry_report_markdown,- render_curator_report_markdown, run_auto_improve_review, run_auto_improve_telemetry_report,- run_curator_report_with_breadth, run_embedding_backfill, run_lint, run_sweep_with_compaction,+ BootstrapConfig, BootstrapOutcome, BootstrapSource, ColdClusterDedup, CuratorParams,+ CuratorReport, EmbedBackfillCounts, EmbedBackfillOptions, LedgerRetention,+ ObservationRetention, SourceCounts, prune_sources_to_budget,+ render_auto_improve_telemetry_report_markdown, render_curator_report_markdown,+ run_auto_improve_review, run_auto_improve_telemetry_report, run_curator_report_with_breadth,+ run_embedding_backfill, run_lint, run_sweep_with_ledgers,};use ai_memory_core::{ActiveProject, AgentKind, AutoImproveProposalId, Capability, DEFAULT_PROJECT_NAME,@@ -101,6 +102,8 @@ const CONTRIBUTORS_WEBHOOK_NAME: &str = "contributors";struct SweepTuning {breadth_weight: f64,retention: ObservationRetention,+ /// Opt-in age bound for the hook event ledgers (disabled by default).+ ledger_retention: LedgerRetention,/// A2 opt-in: compact cold episodic pages instead of evicting them.compact_cold_episodic: bool,}@@ -623,17 +626,20 @@ pub fn admin_router_with_decay_breadth(state: AdminState, breadth_weight: f64) -state,breadth_weight,ObservationRetention::default(),+ LedgerRetention::default(),false,)}/// Build the admin router with every sweep knob that lives outside-/// `DecayParams`, including the opt-in observation prune (disabled by default)-/// and A2 extractive tier-down (`compact_cold_episodic`, off by default).+/// `DecayParams`, including the opt-in observation prune (disabled by default),+/// the opt-in event ledger age sweep (disabled by default) and A2 extractive+/// tier-down (`compact_cold_episodic`, off by default).pub fn admin_router_with_sweep_tuning(state: AdminState,breadth_weight: f64,retention: ObservationRetention,+ ledger_retention: LedgerRetention,compact_cold_episodic: bool,) -> Router {let state = Arc::new(state);@@ -750,6 +756,7 @@ pub fn admin_router_with_sweep_tuning(.layer(axum::Extension(SweepTuning {breadth_weight,retention,+ ledger_retention,compact_cold_episodic,}))}@@ -3971,7 +3978,7 @@ async fn handle_forget_sweep() -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {let (ws, proj) = lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await?;- run_sweep_with_compaction(+ run_sweep_with_ledgers(&state.reader,&state.writer,Some(&state.wiki),@@ -3981,6 +3988,8 @@ async fn handle_forget_sweep(tuning.breadth_weight,tuning.retention,tuning.compact_cold_episodic,+ ColdClusterDedup::default(),+ tuning.ledger_retention,req.dry_run,).awaitdiff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex d60db446..41809494 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -6,8 +6,8 @@ use std::sync::{Arc, Mutex};use std::time::{Duration, Instant};use ai_memory_consolidate::{- AutoImproveReviewConfig, Consolidator, ObservationRetention, projection::cap_text_with_marker,- run_auto_improve_review, run_lint, run_sweep_with_compaction,+ AutoImproveReviewConfig, ColdClusterDedup, Consolidator, LedgerRetention, ObservationRetention,+ projection::cap_text_with_marker, run_auto_improve_review, run_lint, run_sweep_with_ledgers,};use ai_memory_core::{ActiveProject, AgentKind, FeedbackKind, HandoffId, HandoffState, NewHandoff, PageId, PagePath,@@ -409,9 +409,15 @@ should be proposed from a completed session, or at explicit wrap-up \- `memory_lint` — when the user asks to audit the wiki for stale \pages, contradictions, or rule suggestions.\n\- `memory_forget_sweep` — when the user wants to prune old / cold \- pages. Three passes: expired pages are hard-deleted even when \+ pages. Five passes: expired pages are hard-deleted even when \pinned, cold episodic pages decay to tombstones (pinned exempt), \- old tombstones are purged (idempotent, supports dry-run).\n\+ old tombstones are purged, old raw observations are pruned, and \+ old hook event ledgers (log-YYYY-MM.md) are deleted — the last two \+ only when their opt-in retention is configured (decay \+ `observation_retention_days` / `ledger_retention_months`), and the \+ ledger pass never touches the current or previous month. \+ Idempotent; `dry_run=true` reports what every pass would delete \+ without deleting anything.\n\- `memory_install_self_routing` — when the user asks to 'install \ai-memory routing into this project' or 'add ai-memory to \CLAUDE.md / AGENTS.md'. Returns the managed routing package: the \@@ -503,6 +509,9 @@ pub struct AiMemoryServer {/// Opt-in bound on how long raw observations outlive their consolidation./// Default is disabled, so `memory_forget_sweep` deletes no raw capture.observation_retention: ObservationRetention,+ /// Opt-in age bound for the hook event ledgers. Default is disabled, so+ /// `memory_forget_sweep` deletes no ledger file.+ ledger_retention: LedgerRetention,/// A2 opt-in: compact cold episodic pages (tier-down) instead of evicting/// them. Default `false`, so the sweep evicts exactly as before.compact_cold_episodic: bool,@@ -1889,6 +1898,7 @@ impl AiMemoryServer {decay_params: DecayParams::default(),decay_breadth_weight: 0.0,observation_retention: ObservationRetention::default(),+ ledger_retention: LedgerRetention::default(),compact_cold_episodic: false,contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,@@ -2623,6 +2633,14 @@ impl AiMemoryServer {self}+ /// Set the opt-in event ledger age bound used by `memory_forget_sweep`.+ /// Unset, the sweep never deletes a ledger file.+ #[must_use]+ pub fn with_ledger_retention(mut self, retention: LedgerRetention) -> Self {+ self.ledger_retention = retention;+ self+ }+/// Attach the wiki handle. Without this, `memory_forget_sweep`/// and `memory_lint` cannot write their report pages.#[must_use]@@ -3601,7 +3619,7 @@ impl AiMemoryServer {idempotent_hint = true,open_world_hint = false),- description = "Run the retention sweep. FOUR passes, and they \+ description = "Run the retention sweep. FIVE passes, and they \differ on what they will delete. (1) TTL: pages whose frontmatter \expires_at is in the past are hard-deleted (file + rows) REGARDLESS \OF TIER OR PIN — an explicit expiry overrides a pin, so a pinned \@@ -3618,9 +3636,15 @@ impl AiMemoryServer {page that is still live — an unconsolidated session, or one whose \page pass 2 or 3 just removed, keeps every row. This pass is DISABLED \by default (observation_retention_days = 0) and deletes nothing until \- an operator opts in; when off, observations_pruned is 0. The report's \- expired / hard_deleted / observations_pruned counts come from passes \- 1, 3 and 4. Pass dry_run=true to preview."+ an operator opts in; when off, observations_pruned is 0. (5) Event \+ ledgers: hook event ledger files (log-YYYY-MM.md) whose month ended \+ at least decay.ledger_retention_months whole months ago are deleted \+ from disk permanently (never the current or previous month, never a \+ file that does not open like a ledger). DISABLED by default \+ (ledger_retention_months = 0); when off, ledgers_pruned is 0. The \+ report's expired / hard_deleted / observations_pruned counts come \+ from passes 1, 3 and 4; ledgers_prunable / ledgers_pruned and their \+ byte counts from pass 5. Pass dry_run=true to preview.")]async fn memory_forget_sweep(&self,@@ -3640,7 +3664,7 @@ impl AiMemoryServer {Self::viewer_from_parts(Some(&parts)),).await?;- let report = run_sweep_with_compaction(+ let report = run_sweep_with_ledgers(&self.reader,&self.writer,self.wiki.as_ref(),@@ -3650,6 +3674,8 @@ impl AiMemoryServer {self.decay_breadth_weight,self.observation_retention,self.compact_cold_episodic,+ ColdClusterDedup::default(),+ self.ledger_retention,args.dry_run.unwrap_or(false),).await@@ -10045,11 +10071,26 @@ mod tests {);// MEMORY_INSTRUCTIONS is read before an agent ever inspects- // `tools/list`, so it carries the same obligation.+ // `tools/list`, so it carries the same obligation. The ledger pass+ // removes a new class of file (monthly hook event ledgers), so the+ // item must name it and its opt-in gate; the stale three-pass count+ // must not come back either.assert!(MEMORY_INSTRUCTIONS.contains("hard-deleted even when"),"MEMORY_INSTRUCTIONS must warn that expired pages delete despite a pin");+ assert!(+ MEMORY_INSTRUCTIONS.contains("ledger_retention_months"),+ "MEMORY_INSTRUCTIONS must name the opt-in event-ledger retention pass"+ );+ assert!(+ MEMORY_INSTRUCTIONS.contains("dry_run=true"),+ "MEMORY_INSTRUCTIONS must say a dry run reports without deleting"+ );+ assert!(+ !MEMORY_INSTRUCTIONS.contains("Three passes"),+ "the stale three-pass count must not come back in MEMORY_INSTRUCTIONS"+ );}/// All three prompt surfaces must steer agents toward the H1-in-bodydiff --git a/crates/ai-memory-wiki/src/admission.rs b/crates/ai-memory-wiki/src/admission.rsindex a1075081..693d9613 100644--- a/crates/ai-memory-wiki/src/admission.rs+++ b/crates/ai-memory-wiki/src/admission.rs@@ -52,6 +52,13 @@ pub enum AdmissionOp {/// A single page is being deleted (`Wiki::delete_page`). Carries the/// page path; no body. Lets a mirror `git rm` the file.Delete,+ /// A hook event ledger file (`log-YYYY-MM.md`) is being deleted by the+ /// opt-in ledger retention pass of the forget sweep+ /// (`Wiki::delete_event_ledger`). Carries the ledger file name in the+ /// page path; no body, and no `pages` row to touch (ledgers are files,+ /// not pages). Fired **before** the file is removed, so a `reject`-policy+ /// webhook keeps it; a mirror subscribed to it can `git rm` the file.+ DeleteEventLedger,/// A whole project is being purged (`Wiki::purge_project` →/// `remove_dir_all`). Carries the project (ctx), no page path. Lets a/// mirror remove the project's directory.@@ -107,6 +114,7 @@ impl AdmissionOp {AdmissionOp::WritePage => "write_page",AdmissionOp::Consolidate => "consolidate",AdmissionOp::Delete => "delete",+ AdmissionOp::DeleteEventLedger => "delete_event_ledger",AdmissionOp::PurgeProject => "purge_project",AdmissionOp::PurgeSession => "purge_session",AdmissionOp::PurgeWorkspace => "purge_workspace",diff --git a/crates/ai-memory-wiki/src/lib.rs b/crates/ai-memory-wiki/src/lib.rsindex ea535bc3..453d7fa8 100644--- a/crates/ai-memory-wiki/src/lib.rs+++ b/crates/ai-memory-wiki/src/lib.rs@@ -34,8 +34,8 @@ pub use markdown::{pub use migrations::run_pending as run_wiki_migrations;pub use watcher::{DEBOUNCE_WINDOW, RECONCILE_INTERVAL, WatcherHandle};pub use wiki::{- ConditionalWrite, MoveSessionOutcome, PAGE_CHECKPOINT_WALK_LIMIT, PurgeSessionOutcome,- SessionPageFile, Wiki, WritePageRequest,+ ConditionalWrite, EventLedgerFile, MoveSessionOutcome, PAGE_CHECKPOINT_WALK_LIMIT,+ PurgeSessionOutcome, SessionPageFile, Wiki, WritePageRequest,};// Integration tests compile into this crate's test harness instead of adiff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex 48b2eed8..7bab8889 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -37,6 +37,16 @@ pub struct PurgeSessionOutcome {pub files_failed: Vec<PagePath>,}+/// One hook event ledger (`log-YYYY-MM.md`) found in a project's wiki+/// directory by [`Wiki::list_event_ledgers`].+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct EventLedgerFile {+ /// File name inside the project directory, e.g. `log-2026-07.md`.+ pub file_name: String,+ /// Size on disk, in bytes.+ pub bytes: u64,+}+/// Summary of a [`Wiki::reindex_all`] run.#[derive(Debug, Default, Clone)]pub struct ReindexSummary {@@ -1641,6 +1651,154 @@ impl Wiki {}}+ /// List the rotated hook event ledgers (`log-YYYY-MM.md`) directly under a+ /// project's wiki directory, in file-name order.+ ///+ /// A file qualifies only when its name has the rotated-ledger shape AND its+ /// content opens like a ledger (the [`ai_memory_core::log_ledger`]+ /// predicates, the same gate the indexer, the OKF migration and the OKF+ /// export apply): an ordinary page named `log-2025-01.md` is not listed.+ /// The unrotated `log.md` is never listed. Symbolic links and anything+ /// that is not a regular file are skipped. A project with no directory yet+ /// lists nothing.+ ///+ /// # Errors+ /// Returns [`WikiError::Confinement`] when the project tree crosses a+ /// symbolic link, or [`WikiError::Io`] when the directory cannot be read.+ pub fn list_event_ledgers(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ ) -> WikiResult<Vec<EventLedgerFile>> {+ self.inspect_project_tree(workspace_id, project_id)?;+ let root = self.confined_project_root(workspace_id, project_id, Prepare::Inspect)?;+ let entries = match std::fs::read_dir(&root) {+ Ok(entries) => entries,+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),+ Err(e) => return Err(e.into()),+ };+ let mut ledgers = Vec::new();+ for entry in entries {+ let entry = entry?;+ let Some(file_name) = entry.file_name().to_str().map(str::to_owned) else {+ continue;+ };+ if !crate::ledger::is_rotated_log_filename(&file_name) {+ continue;+ }+ let metadata = match std::fs::symlink_metadata(entry.path()) {+ Ok(metadata) => metadata,+ // Removed between the listing and the stat: not a ledger now.+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,+ Err(e) => return Err(e.into()),+ };+ if !metadata.is_file()+ || crate::confinement::is_link_like(&metadata)+ || !crate::ledger::opens_with_log_ledger(&entry.path())+ {+ continue;+ }+ ledgers.push(EventLedgerFile {+ file_name,+ bytes: metadata.len(),+ });+ }+ ledgers.sort_by(|a, b| a.file_name.cmp(&b.file_name));+ Ok(ledgers)+ }++ /// Delete one rotated hook event ledger (`log-YYYY-MM.md`) from a+ /// project's wiki directory and report the file's size.+ ///+ /// The only wiki path that removes a ledger: a ledger is not a page, so+ /// none of the page-delete helpers (which address `pages` rows) fit. It+ /// takes the exclusive mutation guard, then re-checks under it what the+ /// caller may have decided from a stale listing: the name must have the+ /// rotated-ledger shape (never `log.md`, never a path) and the file must be+ /// a regular, non-linked file whose content still opens like a ledger, so+ /// an ordinary page that carries the name is never deleted.+ ///+ /// Then it runs the same blocking admission check a page delete gets+ /// (`remove_page_locked`): webhooks subscribed to `delete_event_ledger`+ /// are notified with the ledger's file name BEFORE the removal, and a+ /// `Reject`-policy webhook refuses the delete — the file is left in place+ /// and the error propagates. Only after the file is gone are the chain's+ /// non-blocking observers dispatched, the way page deletes tell them.+ ///+ /// The window it leaves: the hook ledger appender does not take the+ /// mutation guard, so an append that lands between the content check and+ /// the removal (the admission round-trip included in that interval) is+ /// deleted with the file. Callers are expected to pass only+ /// closed months, which nothing appends to except a late-delivered event+ /// (which recreates a small file). Never touches the store: a legacy+ /// `pages` row for the ledger is left alone.+ ///+ /// Returns `Ok(Some(bytes))` when the file was deleted and `Ok(None)` when+ /// there was nothing deletable: no such file, or one that is not a ledger.+ ///+ /// # Errors+ /// Returns [`WikiError::Confinement`] when the project tree crosses a+ /// symbolic link, [`WikiError::Io`] when `file_name` is not a rotated+ /// ledger name, when a `reject`-policy webhook refuses the removal, or+ /// when the filesystem fails.+ pub async fn delete_event_ledger(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ file_name: &str,+ ) -> WikiResult<Option<u64>> {+ if !crate::ledger::is_rotated_log_filename(file_name) {+ return Err(ai_memory_wiki_error(+ "only a rotated event ledger (log-YYYY-MM.md) can be deleted",+ ));+ }+ let _guard = self.mutation_lock.write().await;+ self.inspect_project_tree(workspace_id, project_id)?;+ let abs = project_path(+ &self.root,+ workspace_id,+ project_id,+ Path::new(file_name),+ Prepare::Inspect,+ )?;+ let metadata = match std::fs::symlink_metadata(&abs) {+ Ok(metadata) => metadata,+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),+ Err(e) => return Err(e.into()),+ };+ if !metadata.is_file()+ || crate::confinement::is_link_like(&metadata)+ || !crate::ledger::opens_with_log_ledger(&abs)+ {+ return Ok(None);+ }+ // The blocking half, exactly as `remove_page_locked` runs it for a+ // page delete: a `reject`-policy webhook refuses before anything is+ // removed, and the refusal propagates with the file left in place.+ let resolved_ctx = if let Some(chain) = &self.admission_chain {+ let mut ctx = AdmissionContext {+ op: AdmissionOp::DeleteEventLedger,+ ..Default::default()+ };+ self.resolve_admission_names(workspace_id, project_id, &mut ctx)+ .await;+ chain.notify(Some(file_name), &ctx).await?;+ Some(ctx)+ } else {+ None+ };+ match self.git.remove_file_checked(&abs) {+ Ok(()) => {+ if let (Some(chain), Some(ctx)) = (&self.admission_chain, &resolved_ctx) {+ chain.dispatch_async(Some(file_name), &serde_json::Value::Null, "", ctx);+ }+ Ok(Some(metadata.len()))+ }+ Err(WikiError::Io(e)) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),+ Err(e) => Err(e),+ }+ }+/// Session ids this scope has tombstoned, as a set for the reindex gate.////// The session-level twin of [`WriterHandle::scope_is_purged`], and readdiff --git a/crates/ai-memory-wiki/tests/suite/ledger_files.rs b/crates/ai-memory-wiki/tests/suite/ledger_files.rsnew file mode 100644index 00000000..6272d2eb--- /dev/null+++ b/crates/ai-memory-wiki/tests/suite/ledger_files.rs@@ -0,0 +1,174 @@+//! `Wiki::list_event_ledgers` and `Wiki::delete_event_ledger`: the only wiki+//! path that removes a hook event ledger.+//!+//! A ledger is a file, not a page, so the page-delete helpers do not fit. What+//! these tests pin is the gate that makes a file delete safe: a rotated name+//! AND ledger content, re-checked at delete time, inside one project's tree.++use ai_memory_core::{ProjectId, WorkspaceId};+use ai_memory_store::Store;+use ai_memory_wiki::{EventLedgerFile, Wiki};+use tempfile::TempDir;++const LEDGER: &str = "## [2025-01-03T10:00:00Z] user-prompt | hello\n";+const PAGE: &str = "# Notes\n\nA page that happens to be called log-2025-01.md.\n";++struct Fixture {+ _tmp: TempDir,+ wiki: Wiki,+ ws: WorkspaceId,+ proj: ProjectId,+ other: ProjectId,+}++async fn fixture() -> Fixture {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "a", None)+ .await+ .unwrap();+ let other = store+ .writer+ .get_or_create_project(ws, "b", None)+ .await+ .unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();+ for project in [proj, other] {+ std::fs::create_dir_all(wiki.project_root(ws, project)).unwrap();+ }+ Fixture {+ _tmp: tmp,+ wiki,+ ws,+ proj,+ other,+ }+}++fn put(fx: &Fixture, project: ProjectId, name: &str, body: &str) -> std::path::PathBuf {+ let path = fx.wiki.project_root(fx.ws, project).join(name);+ std::fs::write(&path, body).unwrap();+ path+}++#[tokio::test]+async fn listing_returns_only_rotated_files_that_open_like_a_ledger() {+ let fx = fixture().await;+ put(&fx, fx.proj, "log-2025-01.md", LEDGER);+ put(&fx, fx.proj, "log-2025-02.md", PAGE);+ put(&fx, fx.proj, "log.md", LEDGER);+ put(&fx, fx.proj, "log-2025-1.md", LEDGER);+ put(&fx, fx.proj, "notes.md", LEDGER);+ put(&fx, fx.other, "log-2025-03.md", LEDGER);++ let listed = fx.wiki.list_event_ledgers(fx.ws, fx.proj).unwrap();++ assert_eq!(+ listed,+ vec![EventLedgerFile {+ file_name: "log-2025-01.md".into(),+ bytes: LEDGER.len() as u64,+ }],+ "one project's listing is only its own ledger files"+ );+}++#[tokio::test]+async fn a_project_without_a_directory_lists_nothing() {+ let fx = fixture().await;+ std::fs::remove_dir_all(fx.wiki.project_root(fx.ws, fx.proj)).unwrap();+ assert!(+ fx.wiki+ .list_event_ledgers(fx.ws, fx.proj)+ .unwrap()+ .is_empty()+ );+}++#[tokio::test]+async fn deleting_a_ledger_removes_the_file_and_reports_its_size() {+ let fx = fixture().await;+ let path = put(&fx, fx.proj, "log-2025-01.md", LEDGER);++ let deleted = fx+ .wiki+ .delete_event_ledger(fx.ws, fx.proj, "log-2025-01.md")+ .await+ .unwrap();++ assert_eq!(deleted, Some(LEDGER.len() as u64));+ assert!(!path.exists());+ // Gone is not an error: a second call has nothing to delete.+ assert_eq!(+ fx.wiki+ .delete_event_ledger(fx.ws, fx.proj, "log-2025-01.md")+ .await+ .unwrap(),+ None+ );+}++#[tokio::test]+async fn a_page_wearing_a_ledger_name_is_not_deleted_even_when_asked_by_name() {+ let fx = fixture().await;+ let path = put(&fx, fx.proj, "log-2025-01.md", PAGE);++ let deleted = fx+ .wiki+ .delete_event_ledger(fx.ws, fx.proj, "log-2025-01.md")+ .await+ .unwrap();++ assert_eq!(+ deleted, None,+ "the content gate is re-checked at delete time"+ );+ assert_eq!(std::fs::read_to_string(path).unwrap(), PAGE);+}++#[tokio::test]+async fn only_a_rotated_ledger_name_is_accepted() {+ let fx = fixture().await;+ let unrotated = put(&fx, fx.proj, "log.md", LEDGER);+ let page = put(&fx, fx.proj, "notes.md", LEDGER);+ let neighbour = put(&fx, fx.other, "log-2025-01.md", LEDGER);++ for name in [+ "log.md",+ "notes.md",+ "log-2025-01.md.bak",+ "../log-2025-01.md",+ "sub/log-2025-01.md",+ "..\\log-2025-01.md",+ ] {+ fx.wiki+ .delete_event_ledger(fx.ws, fx.proj, name)+ .await+ .expect_err(name);+ }++ assert!(unrotated.exists() && page.exists());+ assert!(neighbour.exists(), "no name reaches another project's file");+}++#[tokio::test]+async fn deleting_in_one_project_leaves_the_neighbours_ledger() {+ let fx = fixture().await;+ let mine = put(&fx, fx.proj, "log-2025-01.md", LEDGER);+ let theirs = put(&fx, fx.other, "log-2025-01.md", LEDGER);++ fx.wiki+ .delete_event_ledger(fx.ws, fx.proj, "log-2025-01.md")+ .await+ .unwrap();++ assert!(!mine.exists());+ assert!(theirs.exists());+}diff --git a/crates/ai-memory-wiki/tests/suite/mod.rs b/crates/ai-memory-wiki/tests/suite/mod.rsindex 2edf7da4..04ac344d 100644--- a/crates/ai-memory-wiki/tests/suite/mod.rs+++ b/crates/ai-memory-wiki/tests/suite/mod.rs@@ -3,4 +3,5 @@//! no extra binary; a new file must be declared below.mod admission;+mod ledger_files;mod wiki_git_ledgers;diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 52fe2062..19c8eb29 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -207,7 +207,23 @@ from hook paths.a better model, a better prompt, or a fixed consolidator bug), and itssummary page becomes the only surviving account of that session. FreedSQLite pages are reused rather than returned to the OS: the `.db` file does- not shrink, but the backup tarball does.+ not shrink, but the backup tarball does. A fifth pass, disabled unless+ `[decay] ledger_retention_months` is positive (env+ `AI_MEMORY_DECAY__LEDGER_RETENTION_MONTHS`), deletes old hook event ledgers+ (`log-YYYY-MM.md`) once that many whole UTC calendar months have passed+ after their month ended. It qualifies a file by name AND content (the+ `log_ledger` predicates), never touches `log.md`, never touches the current+ or the previous month whatever the setting, and removes files through+ `Wiki::delete_event_ledger` (confined, under the wiki mutation guard,+ content gate re-checked) rather than from the sweep. Each removal consults+ the blocking admission chain on the `delete_event_ledger` op, the same+ check a page delete runs: a `reject`-policy webhook keeps the file, which+ the sweep counts in `ledgers_undeleted`, keeps going and retries next run —+ and non-blocking observers are dispatched only after the unlink. Ledgers are+ not pages:+ the store is only read, and a legacy `pages` row for a deleted ledger is left+ for `reclaim-ledger-versions`. A dry run reports the files and bytes it would+ delete (`ledgers_prunable`, `ledger_bytes_prunable`) and deletes nothing.Scheduled sweep, rule-based lint, and opt-in embedding backfill ticksenumerate every existing workspace/project scope before doing per-projectwork, matching the auto-improvement scheduler's store-wide scope model. A@@ -1036,6 +1052,10 @@ hard_delete_after_days = 180breadth_weight = 0.0 # opt-in reward for distinct operatorsobservation_retention_days = 0 # 0 = never prune raw observationsobservation_prune_batch = 5000 # rows per prune transaction+ledger_retention_months = 0 # 0 = never delete hook event ledgers; N > 0 =+ # delete a log-YYYY-MM.md N whole months after+ # its month ended (current + previous month+ # are never deleted)compact_cold_episodic = false # A2 opt-in: tier-down (compact) a cold# episodic page instead of evicting it —# keep abstract+summary+keep-tokens, dropdiff --git a/docs/admission-webhooks.md b/docs/admission-webhooks.mdindex 9940ee44..90958fc3 100644--- a/docs/admission-webhooks.md+++ b/docs/admission-webhooks.md@@ -57,6 +57,16 @@ Webhooks fire on these `op` values today (extensible enum):**before** the file is removed so a mirror can `git rm` the same path. TheSQLite index is deleted directly by the writer actor; the watcher does notreconcile delete events.+- `delete_event_ledger`: a hook event ledger file (`log-YYYY-MM.md`) is+ removed by the forget sweep's opt-in ledger retention pass+ (`Wiki::delete_event_ledger`, enabled by `[decay] ledger_retention_months`).+ Carries the ledger file name in `page.path`, no body, and no `pages` row to+ touch (ledgers are files, not pages). Fired **before** the file is removed,+ so a `reject`-policy webhook keeps it: the sweep then counts the file in the+ report's `ledgers_undeleted` and retries it on the next run, and keeps the+ rest of the sweep going. Non-blocking observers are dispatched again after+ the removal is durable. (Per-event *appends* to ledgers still never fire+ the chain — see below — this is the one ledger path that does.)- `purge_project`: a whole project is purged (`Wiki::purge_project` →`remove_dir_all`, routed from `/admin/purge-project`). Carries theproject in `ctx`, **no** page path; fired before the directory is@@ -175,7 +185,11 @@ terminal `purge_project` notification is unchanged.(per prompt/tool-call). Routing each through the chain would mean anHTTP POST per observation, violating the fire-and-forget hook budget. Theper-event log is a local audit artifact; back it up out-of-band (batched- rsync), not per-line.+ rsync), not per-line. The one ledger path that DOES fire the chain is the+ forget sweep's opt-in aged removal (`[decay] ledger_retention_months`):+ each ledger file it deletes emits a blocking `delete_event_ledger`+ notification before the unlink, so a `reject`-policy webhook can keep an+ audit file the sweep would otherwise remove.- **The page bodies behind a handoff**: the `handoff_*` ops above carry onlythe scope and the acting operator. A handoff is SQLite rows, so a file mirrorhas no file change to reconcile from one; what it gets is the lifecycle@@ -202,12 +216,13 @@ terminal `purge_project` notification is unchanged.```httpPOST <webhook.url>Content-Type: application/json-X-Memory-Op: write_page | consolidate | delete | purge_project | purge_workspace | move_project+X-Memory-Op: write_page | consolidate | delete | delete_event_ledger | purge_project | purge_workspace | move_project| move_session | handoff_begin | handoff_accept | handoff_cancel```-(The header is one of those ten values; the second line is a continuation of-the list, not a second header.)+(The header carries one of the `AdmissionOp` values shown above — the source+enum is the full catalog; the second line is a continuation of the list, not+a second header.)```jsonc{diff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.mdindex 5ba34347..d926fea8 100644--- a/docs/lifecycle-ops.md+++ b/docs/lifecycle-ops.md@@ -18,6 +18,7 @@ on a homelab box where mistakes are harder to undo.| `move-session <id> --to --confirm` | ✅ yes | no | yes (move it back) | Re-stamps one session (or every session touching `--from-project`) into another project: `sessions`, `observations`, its `handoffs`, consolidation jobs, auto-improve runs/claims, profile prompt candidates, ingest keys and its `sessions/<id>.md` page, one transaction per session; the page file moves with it (`--pages move`, default) or is retired for regeneration. Without `--confirm` it is a real dry run (rolled back). Refuses with `409` an open session or a pending consolidation job unless `--force`. || `repair-backfill-timestamps --project --confirm` | ✅ yes | no | yes, if the operator kept the audit row or the CLI's before/after report (nothing else) | Corrects `sessions.started_at`/`ended_at` for sessions an older `backfill` imported before it carried the transcript's own event time. The CLI reads the operator's local transcripts read-only and posts candidate `(session_id, started_at, ended_at)` tuples to `POST /admin/repair-session-times`, which validates each one against `(workspace, project)` (a candidate outside that scope is `not_found` and untouched), only rewrites a row whose `started_at` postdates the candidate's own end (`not_flattened` otherwise, so a correctly hook-captured session or a re-run is a no-op), refuses negative/inverted/future-dated times, and never assigns an end time to a session still open. Without `--confirm` the server validates and reports inside a rolled-back transaction, so it is a real dry run; a confirmed run writes one `audit_log` row per request with the before/after times. Touches only the two timestamp columns of rows already in scope; `observations` and pages (including the session's own page frontmatter) are untouched. || `backup --to` | ✅ yes | no | n/a | Streams a gzipped tarball from the server's online `sqlite3 .backup` plus the wiki tree. Safe alongside the live writer. |+| `forget-sweep` event-ledger pass (`[decay] ledger_retention_months`) | ✅ yes | old hook event ledger *files* (`log-YYYY-MM.md`) from disk, nothing in the database | no ai-memory command restores a ledger (`restore-page` restores pages only); the content stays in the wiki's git history when a checkpoint captured it, recoverable with plain git until the repository is compacted | **Off by default** (`0`). Runs inside the forget sweep, so `--dry-run` previews it: the report lists `ledgers_prunable` and `ledger_bytes_prunable`. Online through the admin API. Only a file whose name is `log-YYYY-MM.md` **and** whose content opens with a ledger hook entry qualifies; `log.md`, the current month and the previous month are never deleted, whatever the setting. Each removal consults the blocking admission chain (`delete_event_ledger` op); a `reject`-policy webhook keeps the file and the report counts it in `ledgers_undeleted`. || `reclaim-ledger-versions` | ✅ yes | superseded pre-#660 ledger page *versions* only | no (the latest page version stays) | Dry-run by default; needs `--confirm` to delete. Online through the writer actor, safe alongside the live writer. Content-gated: only non-latest, non-decay `log.md`/`log-YYYY-MM.md` versions whose body opens with a ledger hook entry are removed; a real page that merely shares the name is untouched. `--compact` additionally rebuilds FTS and `VACUUM`s to reclaim the freed bytes. || `checkpoints` | ✅ yes | no | n/a | Lists recent wiki git checkpoints. Read-only. || `restore-page --path --from` | ✅ yes | overwrites one markdown page version | yes (restore another checkpoint) | Restores one page from wiki git history, reindexes it into SQLite, and writes a post-restore checkpoint. Does not restore DB-only state. |@@ -820,6 +821,59 @@ FTS index and `VACUUM`. `--drop-latest` (also content-gated) additionallyreclaims the latest ledger version when you no longer need the in-wiki ledger atall.+### Event-ledger sweep (`forget-sweep`, opt-in)++```bash+# Preview: which ledgers and how many bytes the sweep would delete.+ai-memory forget-sweep --dry-run+# Enable it (config.toml) — the sweep then deletes them on its schedule too:+# [decay]+# ledger_retention_months = 12+```++The hook event ledgers (`log-YYYY-MM.md`, one per project per month) are an+append-only audit trail that no ai-memory surface reads back: the indexer,+consolidation, the OKF migration and export skip them. On a busy project a+single month can hold hundreds of megabytes. With `[decay]+ledger_retention_months = N` (env `AI_MEMORY_DECAY__LEDGER_RETENTION_MONTHS`)+the forget sweep deletes a project's ledger once `N` whole UTC calendar months+have passed after its month ended. `0` (the default) keeps every ledger; a+negative value is rejected at startup.++What it will and will not delete:++- A file qualifies only when its name is `log-YYYY-MM.md` **and** its content+ opens like a ledger (the same content gate `reclaim-ledger-versions` and the+ indexer use). A page a person named `log-2025-01.md` is never deleted.+- The current month and the previous month are never deleted, whatever `N` is:+ the hook appender may still write to them.+- `log.md` (the unrotated ledger) is never deleted.+- Only the swept project's directory is looked at. The sweep that runs for one+ project never touches another project's ledgers.+- A deletion is the same blocking admission check a page delete is: webhooks+ subscribed to the `delete_event_ledger` op are consulted before the unlink,+ and a `reject`-policy webhook keeps the file. The sweep then counts it in+ the report's `ledgers_undeleted` and moves on (retried by the next sweep),+ exactly as a refused page delete is kept and retried. (Per-event *appends*+ to ledgers still bypass the chain, as before.)++How it deletes: through `Wiki::delete_event_ledger`, which takes the wiki+mutation guard, re-checks the name and the content gate, runs the blocking+admission check described above, and only then removes the file; the sweep+never calls `std::fs` itself. The hook appender does not take+that guard, so an append landing in the instant between the check and the+removal would be deleted with the file; that can only affect a month closed for+at least `N` months, which receives nothing except a very late event (and that+event recreates a small file). The database is never written: ledgers have no+`pages` rows since #660, and when a legacy row exists for a deleted ledger the+report counts it in `ledger_page_rows_left` and leaves it alone — run+`reclaim-ledger-versions` for those.++The sweep deletes the file from disk. The wiki's git repository keeps the+blobs a checkpoint already captured; deleting a ledger does not shrink+`wiki/.git` (that needs the repository to be compacted, which ai-memory does not+do).+### `repair-backfill-timestamps````bashdiff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex 44e418d6..fdeb1b77 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -77,6 +77,7 @@ means the boundary is not built yet.| 10d | Workspace delete's own row counts are scope-bound to `workspace_id` (a workspace's *own* rows are never over- or under-counted by a sibling workspace's), its cross-workspace observation/handoff cascade is reported by both preview and confirm rather than prevented (same as `purge-project` one level down), the non-empty guard fails closed without `force`, and `delete-workspace`'s `dry_run` always wins | `ai-memory-store/src/ops.rs` `delete_workspace` — every direct count and the `DELETE FROM workspaces` itself are scoped by `workspace_id = ?1`; the two `collateral_*` counts are scoped by `workspace_id != ?1` so a row is counted as one or the other but never both; `projects_deleted > 0 && !force → WorkspaceNotEmpty` fail-closed, and a missing workspace is `NotFound`, both checked identically under `PurgeMode::Preview` and `PurgeMode::Commit`; whole op in one transaction; `admin.rs` `handle_delete_workspace` checks `req.dry_run` unconditionally, before building the confirmed path, mirroring `reclaim-ledger-versions`/`purge-project`; root-only gate is the shared `/admin/*` multi-user auth ladder, not a separate check | `admin_move.rs` `delete_workspace_dry_run_never_counts_a_different_workspaces_rows` — previewing workspace A counts only its own project/page/session/observation/handoff rows, not workspace B's (which holds two like-named projects and its own full row set), and a session living in B that stamps an observation directly into A is counted in A's own `observations_deleted`, never in `collateral_observations_deleted` (the two counts are mutually exclusive by construction); `admin_move.rs` `delete_workspace_force_true_and_dry_run_true_still_only_previews` — `{"force": true, "dry_run": true}` deletes nothing; `ops.rs` `delete_workspace_dry_run_changes_nothing` — every table's row count, including `workspaces` itself and the `purged_scopes` tombstone (the two tables a confirmed delete's own transaction writes to), is identical before/after a `PurgeMode::Preview` run; `ops.rs` `delete_workspace_dry_run_and_confirmed_delete_both_report_collateral_damage_in_another_workspace` and `admin_move.rs` of the same name — deleting workspace W collaterally deletes an observation, and orphans a handoff's session reference, in a *different* workspace (via `sessions` cascading out of W), and both the preview and the confirmed response count it identically — the cascade itself is reported, not blocked, by either; `admin_move.rs` `delete_workspace_dry_run_refuses_non_empty_without_force` / `delete_workspace_dry_run_nonexistent_workspace_returns_404` — same `409`/`404` a confirmed delete would give; `admin.rs` `multiuser_delete_workspace_dry_run_rejects_db_user_and_anonymous` — root reaches the preview handler (404 control), DB user gets 403, anonymous gets 401 | STRONG || 10e | Reconcile-tombstone of a disk-deleted page is opt-in, soft, scope-bound, and false-positive-guarded (invariant #16, #929 delete-half) | `ai-memory-wiki/src/watcher.rs` — off by default (`[maintenance] reconcile_tombstones_deleted_pages`); a page is tombstoned only after its file is observed missing on two consecutive passes (streak resets if the path's `PageId` changed), re-verified against the live filesystem immediately before acting, with reserved/indexed-but-unwalked paths (`bootstrap.md`, `_meta.md`, `_pending/`, `sessions/*.md`) excluded and a circuit breaker that skips a whole scope when `> max(3, 50%)` of its pages look missing or a non-partial walk finds nothing; `ai-memory-store/src/ops.rs` `soft_delete_for_reconcile_if_latest` is a soft tombstone (`is_latest=0` + `superseded_at`, decay's shape) through the single writer actor in one transaction — never a filesystem write — scoped to the page's own `(workspace_id, project_id)` | `watcher.rs` `reconcile_delete_disabled_by_default_never_tombstones_a_missing_page`, `reconcile_delete_cross_project_isolation` (project A's deletion never tombstones project B's same-path page), `reconcile_tombstone_refuses_a_stale_latest_id`, `reconcile_tombstone_refuses_when_the_file_still_exists`, `reconcile_tombstone_never_touches_the_filesystem`; `ops.rs` `reconcile_tombstone_resurrects_instead_of_orphaning_on_recreate` | STRONG || 10f | Session-time repair is scope-bound (no cross-project timestamp rewrite) | `ai-memory-store/src/ops.rs` `repair_session_times` — every candidate is read back and updated with `WHERE id=? AND workspace_id=? AND project_id=?`; a row outside that 3-tuple is reported `NotFound` and untouched, same code path as an id that does not exist at all; `ai-memory-mcp/src/admin.rs` `handle_repair_session_times` passes the caller's `(workspace, project)` straight through, never the candidate's own | `ops.rs` `repair_session_times_does_not_touch_a_session_of_another_project` (control: sibling session in-scope repaired in the same batch); `admin_repair_session_times.rs` `cross_project_session_is_not_found_and_untouched`; both bite-checked by dropping the `project_id` filter | STRONG |+| 10g | The event-ledger age sweep deletes only closed ledger files of the swept project: opt-in, content-gated, admission-gated, never the writer's months (invariant #16) | `ai-memory-consolidate/src/sweep.rs` `sweep_event_ledgers` + `ledger_is_expired` (off at `[decay] ledger_retention_months = 0`; never the current or previous UTC month, whatever the age; a dry run only lists; a per-file delete failure is counted in `ledgers_undeleted`, kept and retried — the sweep does not abort, exactly as a refused page delete is kept and retried); `ai-memory-wiki/src/wiki.rs` `list_event_ledgers` / `delete_event_ledger` — rotated `log-YYYY-MM.md` name AND `log_ledger` content gate (re-checked at delete time, under the mutation guard), a project-confined path, no symlink, never `log.md`, no store write; then the same blocking admission check a page delete runs (`remove_page_locked`): webhooks subscribed to `delete_event_ledger` are notified BEFORE the unlink, a `reject`-policy webhook refuses and the file stays, and the non-blocking observers are told only after the removal is durable | `consolidate` `tests/suite/ledger_sweep.rs` `an_ordinary_page_named_like_a_ledger_is_never_deleted` (a page, a frontmatter page and `log.md` are kept; the real ledger is the control), `another_projects_ledgers_are_untouched`, `the_current_and_previous_month_survive_even_a_one_month_retention`, `the_default_configuration_deletes_no_ledger`, `a_dry_run_reports_files_and_bytes_and_deletes_nothing`, `a_rejecting_admission_webhook_keeps_the_ledger_and_the_report_says_so` (adversarial: a `reject`-policy webhook on `delete_event_ledger` — the file stays intact, the report counts it in `ledgers_undeleted`, the sweep keeps the rest going), `an_accepting_admission_webhook_is_told_after_the_file_is_gone` (legitimate control: an accepting gate lets the delete through and the non-blocking observer receives the op only after removal); `sweep.rs` `ledger_guard_protects_the_current_and_previous_month_regardless_of_age`; `wiki` `tests/suite/ledger_files.rs` `a_page_wearing_a_ledger_name_is_not_deleted_even_when_asked_by_name`, `only_a_rotated_ledger_name_is_accepted` (traversal and `log.md` refused), `deleting_in_one_project_leaves_the_neighbours_ledger` | STRONG || 11a | Hook backpressure (202/429) + bounded fan-out (invariant #5) | `ai-memory-hooks/src/router.rs` semaphore→429, 202 immediately, `MAX_HOOK_BATCH_ITEMS`, bounded LRU limiter; batch acknowledgements retain only processed indices and classify terminal drops without consuming capacity | `router.rs` `handle_hook_returns_429_when_ingest_saturated`, `ingest_rate_limiter_is_bounded`; `router.rs` `handle_hook_batch_skips_rate_limited_first_item_and_accepts_later_source`, `handle_hook_batch_reports_failed_index_after_rate_limited_skip`, `handle_hook_batch_drops_subagent_events_before_capacity_check` (each asserts result indices and includes an accepted control) | STRONG || 11b | Capture exclusions drop before storage | `ai-memory-hooks` `capture_policy.rs` `inspect`→`Drop` (before semaphore/spawn), including shell commands whose arguments name an ignored path (`match_command`; argv elements matched whole and tokenized, and every word that holds several words, such as a quoted `sh -c` script or a `"$(…)"` substitution, re-split to four levels by `ShellCommand::split`/`push_nested_words`, a deeper script metadata-only; ANSI-C strings decoded and a backslash before an ordinary letter dropped (`shell_words`, `push_word`); backslash-newline continuations joined (`shell_words`); a parameter default's operand, a value glued to a short flag and a `file:` URL's path read as candidates (`parameter_operands`, `shell_arguments`, `file_url_path`); PowerShell and cmd escape characters read out under the `PowerShell` tool or on a Windows host (`without_windows_escapes`); `~+` resolved to the cwd and a `~-`/`~N`/`~name` prefix metadata-only (`names_unknown_directory`); shell and interpreter options that take a value skipped while looking for a `-c` script or inline code (`takes_shell_value`, `runs_inline_code`, which also lists `lua`/`Rscript`/`osascript -e`, and `su -c`/`script -c` as script runners); paths compared without regard to case on a macOS host (`fold_case`, set by `resolve`; patterns and candidates composed to NFC and lowercased in full by `fold_path`, TS `captureFold`; client-only, the server's sentinel re-inspection never depends on it); a `file:` URL cut at its query or fragment before decoding (`file_url_path`); a parameter default nested past four levels metadata-only and a default read again after backslash removal (`parameter_operands`, `push_word_reading`); a tilde expanded or treated as an unknown directory only when the shell expands it, unquoted and in a script rather than a quoted message or argv element, every tilde under PowerShell (`marked_shell_words`, `literal_tildes`, `expand_tilde`); a file or shell read of a harness's saved tool output, or a glob that could match one, metadata-only under an active policy (`output_spool`: Claude Code `tool-results/` and `tasks/*.output`, OpenCode `tool-output/`, Pi `pi-bash-*.log`; glob segments fit a name they share a match with, `globs_intersect`, TS `captureGlobsIntersect`, and one fitting segment must spell three characters in a row of that name's distinctive text literally, `spells`, TS `captureSpells`, so `*.log` is not read as `pi-bash-*.log`, a trade-off that leaves a glob with no such literal run, `/tmp/p?-b*`, outside the rule; the TS matcher applies it to `read_many_files` entries too); every other marker governing a file-tool target (an `apply_patch`'s header paths, read after leading whitespace, `patch_paths`), a search/list tool's directory, file or path-like glob argument (`search_scope`, Hermes `file_glob` included; a grep `pattern` is not read) or a separator-bearing shell argument also inspects the call, found by the lexical marker walk from each location's nearest existing directory, each directory's answer remembered for every lookup that passes it (`marker.rs` `MarkerMemo`, TS `captureMemoMarker`, seeded with the event's own walk, `remember`, TS `captureMemoRemember`), bounded (4,096 locations, 16 markers, and 16,384 probes sharing the glob walk's 50 ms, `MAX_LOOKUP_PROBES`, TS `CAPTURE_MAX_LOOKUP_PROBES`; locations outside the own checkout are looked up first, a glob's literal root before the walk below it (whose single listing can spend the time budget on a large directory), and past a bound fail closed as under an invalid policy, while running out inside the own checkout, whose locations are looked up shallowest first, ends the lookup, its own policy governing there) and combined strictest-first (`capture_lookup_locations`, `CaptureDecision::stricter`, `hook.rs` `foreign_capture_decision`, also applied by `transcript_capture.rs` `decide_call`; TS `captureForeignConfigs`, `captureDecide`, `captureSearchScope`, `capturePatchPaths`); a location with glob syntax is looked up from its literal root and, when that root lies outside the event's `.git` checkout, every directory the glob could pass through is checked for a marker (`glob_walk`, `hook.rs` `GlobBudget::markers_below`; TS `captureGlobWalk`, `captureMarkersBelow`, `captureOwnCheckout`: a `*`/`?` segment lists the child directories it matches, a class/brace/group every child, a `**` the subtree except the event's checkout's; a glob rooted inside the event's checkout is not walked; a checkout root at or above the home directory, or the filesystem root, is never the own checkout for these rules (`own_checkout`), so a dotfiles `~/.git` does not stop the walk from `~/Projects`; symlinks never followed; 256 directories, counted as a `**` lists, 32,768 entries and 50 ms, `MAX_GLOB_TIME`, TS `CAPTURE_MAX_GLOB_MS`, injectable clock, past which, or for a brace/group spanning a separator, a `..`/`~` alternative or one a bounded brace expansion builds, `brace_alternatives`, TS `captureBraceAlternatives`, a directory alternative bash before 5.2 expands to `..` (`.{*,x}/`), or an expansion too large to list whose pieces could build one of these (`brace_overflow_could_leave`, TS `captureBraceOverflowLeaves`: integer and letter sequences cannot, so `file{1..200}.txt` is walked like any glob), the call fails closed); a `..` after a `**` is read both as the `**` matching no directory and as matching some, by the event's own matcher and the lookup (`normalize_readings`, TS `captureReadings`, at most 16 readings, past which the call fails closed), and so is a directory segment that bash before 5.2 can expand to `..` (`could_name_parent`, `class_glob_matches` with POSIX classes such as `[[:punct:]]` and extglob groups such as `@(.)`, `?(.)`, `*(.)`, `+(.)`, `!(x)`; TS `captureCouldNameParent`, `captureClassGlob`, `captureNamedClass`), read as `..` too; inside double quotes a backslash before `$` or a backquote is dropped, so a quoted script (`bash -c "…"`, `eval "…"`) re-split for its words reads an ANSI-C string as the shell it runs does (`shell_tokens`, TS `captureMarkedWords`); a zsh glob group kept in its word and ANSI-C numeric escapes decoded are fed to the lookup (`shell_tokens` with `expand`, `ShellWords::expanded`, `glob_group`, `ansi_c_numeric_escape`; TS `captureMarkedWords(…, true)`, `captureGlobGroup`, `captureAnsiNumeric`); a file tool whose targets cannot be read or resolved, and a search/list argument that is not a string, fail closed; the path of a git `REV:path` object name tried from the cwd and the marker directory (`git_object_path`); Antigravity `run_command` resolved from its `Cwd`); an invalid marker makes file, search/list and shell calls metadata-only; an active one makes a shell call metadata-only when a word uses unquoted brace expansion, a bracket class (a leading `]` included), a zsh glob group or extglob, or a numeric/control ANSI-C escape (`has_unevaluated_expansion`, also run on scripts given to `sh -c`, `eval` or a substitution), or when it runs inline interpreter code (`runs_inline_code`: `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `deno eval`), and either makes tools that read back an earlier command's output metadata-only (`reads_earlier_output`: `BashOutput`, `TaskOutput`, `write_stdin`, `process`, `read_bash`/`write_bash` and PowerShell twins); the server admits a metadata-only shell or unknown-family body only under an active or invalid marker, with no paths and an `extracted` state (`router.rs` `metadata_protocol_is_legal`), and its own re-inspection strips an older client's keep for either; a Gemini `read_many_files` literal entry is also read as `entry/**` (`glob_matches_below`), and Copilot CLI's runtime `view`/`create`/`str_replace_editor` are file tools for that agent only (`agent_family`); Factory Droid's Claude-shaped payload is read by `extract`, its `Create` and `ApplyPatch` are file tools for that agent only (`agent_family`), `ApplyPatch` reads its `input` envelope like Codex `apply_patch`, and its `LS` `directory_path`, `Glob` `folder`/`patterns` and `Grep` `glob_pattern` locate the call for the cross-checkout lookup (`search_direct_paths`, `search_scope`) (#1240); Meta Muse Code's Claude-shaped payload is read by `extract` with its `tool_use_id`, its `read_file`/`write_file`/`edit_file` `path` resolves lexically against `cwd`, its `read_memory`/`add_memory`/`edit_memory` are file tools for that agent only whose `project`-scope `path` is placed under `.agents/memory/` and whose personal scopes fail closed to metadata-only (`muse_memory_paths`), `monitor` is a shell for that agent only, and `bash_input` is an output reader for that agent only; CodeBuddy Code's payload carries Claude Code's tool names and fields and is read by the same `extract` arm (#1299); generated OpenCode/OMP/Pi/OpenClaw integrations mirror it in `render_shared.rs` `ts_capture_policy_v1` (`captureMatchCommand`, `captureShellSplit`, `captureUnevaluatedExpansion`, `captureInlineCode`, `captureGitObjectPath`, `captureGlobBelow`, the `reader` flag). Candidate/argument flavor (`Flavor::Posix` vs `Flavor::Windows`, used to pick which `ignore_paths` patterns even apply) is derived from the **host** (the cwd), never from the candidate string alone — a POSIX-host candidate spelled with a leading `//` is collapsed to a single `/` before flavor detection (`normalize_candidate`; TS `captureNormalize`'s `windowsHost` parameter, sourced from `captureHostWindows(cwd)`), fixing GHSA-vh98 (a `//`-prefixed candidate used to self-classify as `Flavor::Windows` regardless of host, matching zero POSIX patterns and being captured instead of dropped); a genuine Windows/UNC host (cwd itself windows-flavored) is unaffected; `hook.rs` `--check-capture` preflight uses the same capture policy before any spool or spawn; transcript imports (`ai-memory backfill`, including the automatic first-boot run, the `ai-memory run` ledger upload, and `ai-memory recover`'s finish-failed re-import and degraded-run replay in `recovery.rs` `recover_finish_failed`/`recover_degraded_run`, each built for the journaled checkout's `cwd`) apply the same decision table through `commands/transcript_capture.rs`: each recorded tool call is rebuilt in its agent's hook shape (`capture_policy.rs` `tool_call_payload`) and inspected by the checkout's policy, and by a reroute destination's policy too; a Drop removes the call and its result (paired by native id, else the strictest call of the turn when the result has no id; a result whose id matches no call, or with no call, follows the orphan rule: dropped under a policy, content-free without one), metadata-only posts the hook's metadata-only body with its protocol (backfill) or a withheld placeholder keeping only the family and a call id that passes the server's `valid_call_id` (ledger), and a shell call whose recorded arguments cannot be parsed drops; both imports also apply the hook's repository admission gate (`hook.rs` `checkout_admits_capture`: persisted capture mode, marker opt-in, readable routing marker — the same helpers the hook's own gate uses), so under allowlist mode an unmarked checkout imports nothing, prompts included: `backfill` stops before contacting the server and the run ledger finishes with no events; a tool the transcript names differently from the hook is rebuilt under the hook's name and fields (`capture_policy.rs` `hook_tool_call`: Codex `exec_command` `{cmd, workdir}` → `Bash` `{command, workdir}`); the Claude Code and Codex JSONL adapters label each event with its record's cwd (`transcript.rs` `stamp_record_cwd`, `RECORD_CWD_KEY`), from which the import resolves arguments, policy and reroutes, falling back to the session cwd, and which is removed before a ledger upload; a rerouted call, and an event whose record cwd lies outside the checkout, must pass that directory's admission gate, resolve to the same server-profile route as the checkout and to the same project scope (`transcript_capture.rs` `admits_elsewhere` → `hook.rs` `checkout_admits_capture` + `delivers_to_same_server`, which compares two `resolve_hook_route` results and never matches a refused selection, + `routes_to_same_project`, which compares the two `hook_scope` hint sets and, when they leave the project to the server, under `repo-root` the repository/marker anchor or the directory itself, under the default `basename` the directory itself or a destination inside the repository whose root is the source), else it drops with its result, since the import files every event under the importing project; compaction, checkpoint and annotation events answer to the same record-cwd checks; Claude Code `!` shell-mode output (a user message opening with a `<bash-stdout>`/`<bash-stderr>`/`<local-command-stdout>` block, whatever it holds) is dropped (`shell_mode_output`); the Claude Code adapter excludes harness-written background-task turns (`transcript.rs` `claude_task_notification`: `origin.kind` `task-notification` in any case, or a first text block opening with a `<task-notification` tag in any case, attributes allowed, after a byte-order mark, zero-width characters or whitespace) and records a compaction summary (`isCompactSummary` true, `"true"` or `1`, `truthy`) as a compaction event, which backfill does not post; a tool the matcher does not recognize (unknown family: MCP tools, Codex `view_image`, …) keeps only its family whatever the policy, as the live server stores for it (`EventCapture::Unrecognized`: backfill posts title `tool unknown` and body `tool_family: unknown`, the ledger a withheld placeholder), and so does a result with no call to inherit from ; in a Windows session every candidate, shell argument and `workdir` is read as the file Windows opens before matching (`windows_spelling`, `windows_segment`, `command_base`; TS `captureWindowsSpelling`/`captureResolve`/`captureBase`): Git Bash/MSYS2/Cygwin `/c/…` and `/cygdrive/c/…`, a drive-less rooted path on the cwd's drive, the `\\?\`/`\\.\`/`\??\` and `UNC` prefixes, the local administrative share (`\\localhost\C$`), and per-segment alternate-data-stream suffixes and trailing dots/spaces, any other device path unusable (metadata-only for a file tool); `/c/…` and `/cygdrive/c/…` are also read from the root of the cwd's drive, as a native tool reads them, and either reading matching drops (`windows_spellings`, `normalize_candidates`, `normalize_readings`; TS `captureWindowsSpellings`/`captureAllReadings`); the cwd, the marker directory, home and an absolute pattern get the same reading so every side shares one spelling (`normalize_root`, `compile`; TS `captureRoot`, the marker directory cut lexically); a Windows session also reads each shell command and argv element with every backslash literal, as PowerShell and cmd do, so a bare or double-quoted `\\server\share\…` or `\\?\C:\…` argument keeps its prefix (`literal_shell_words`, threaded through `push_nested_words`/`push_argv_item`; TS `captureMarkedWords(…, literal)`); the harness-spool check is linear in the path and charged to the match budget, past it fail-closed (`output_spool`, TS `captureOutputSpool`); a shell command over `MAX_SHELL_COMMAND_CHARS` (1 MiB) is metadata-only and its marker lookup unprovable (`ShellCommand::oversized`, TS `captureCommandOversized`); Hermes `execute_code` is metadata-only under an active policy (`INLINE_CODE_TOOL_NAMES`); the TS file/search/non-file/inline-code/output-reader tool lists and the command limit are generated from the native constants (`FILE_TOOL_NAMES` and siblings, spliced by `ts_capture_policy_v1`), and the TS marker reader honours every TOML spelling of the capture table toml_edit does (dotted `capture.ignore_paths`, quoted or spaced `[capture]` headers) and fails closed on the shapes it rejects (inline table, `[[capture]]`, `[capture.x]`, a second definition) (`captureTomlKey` and the `captureConfigAt` section loop), tracks every multi-line array so a line inside one (`["docs"]`) is never a header, and fails closed on a line that is neither header nor key/value, a key line swallowed by an open array, text after a continued array closes, or an inline table left open at a line end (`captureValueScan`); the TS glob walk reads a directory one entry at a time with `opendirSync`, stopping at the entry bound; in a Windows session a shell argument or `workdir` that is drive-relative (`C:docs\x`, a bare `C:`) or a device path naming no drive or share (`\\?\GLOBALROOT\…`, `\\.\HarddiskVolume3\…`) makes the command metadata-only, a POSIX shell's reading of a placeable native path (`C:\repo\x` read as `C:repox`) excused and a device reading never (`windows_unplaceable`, `match_command`, the `workdir` check in `inspect`; TS `captureWindowsUnplaceable`, `captureMatchCommand`, `captureDecide`); a PowerShell `FileSystem::`/`Microsoft.PowerShell.Core\FileSystem::` provider prefix is dropped before a Windows path is read (`strip_powershell_provider` in `candidate_raw`/`command_base`; TS `captureStripProvider` in `captureResolve`/`captureBase`); a POSIX absolute pattern in a Windows marker makes the marker invalid (`compile`; TS `captureConfigAt`) (GHSA-gcpc-88hm-3xqr); server re-inspection compiles an Active never-match sentinel in the cwd's path flavor (`inspection_sentinel`, `capture_inspector`) (#1250) | `capture_policy.rs` per-agent `…honors_exclusions` tests, `shell_fixture_vectors` (shared `capture-policy.json` `shell` drop/keep vectors: tool aliases incl. OpenClaw/Devin `exec` and `PowerShell`, `workdir`, glob directories, Windows paths, and a POSIX-host leading-`//` command via `/{root}/docs/adr/x.md`), `shell_tool_shapes_of_every_adapter_honor_exclusions`, `claude_code_powershell_honors_ignored_paths_on_a_windows_host` (#1186: Windows-spelled and `-Param:value` paths drop, public-path and `git status` controls kept, invalid marker metadata-only), `gemini_cli_shell_and_read_many_files_honor_ignored_paths` (Gemini `run_shell_command` incl. `dir_path`/`directory`, and `read_many_files` globs via `match_globs`: excluded literal, mixed public+excluded, `docs/*`, recursive `**` and case-variant entries drop, an `exclude` list cannot rescue them, unsupported glob syntax and malformed lists are metadata-only, public entries kept, POSIX and Windows hosts) and `globstar_reaches_lets_double_star_span_any_depth`, `fixture_vectors` (incl. TS-adapter `bash`/`exec` vectors, and `normalization`'s leading-`//` POSIX vectors alongside the kept Windows-cwd UNC vectors as the no-regression control); `shell_matching_is_off_when_inactive_and_fails_closed_when_invalid_or_over_budget`; `router.rs` `capture_protocol_shell_decisions_survive_server_reinspection`, `capture_protocol_invalid_marker_shell_is_metadata_only` (active metadata-only shell admitted for an unevaluated expansion, inactive refused, older client's invalid-marker keep stripped, commandless control kept), `capture_protocol_unparseable_marker_strips_shell_events` (server fallback for an unparseable marker), `capture_protocol_invalid_shell_metadata_claim_must_be_canonical` (a stripped shell claim with a path count or non-`extracted` state is refused), `capture_protocol_active_keep_on_a_windows_cwd_keeps_provable_bodies` (#1250: a kept Read and Bash on `C:\repo` and a UNC cwd stay Keep; brace-expansion still metadata-only); `capture_policy.rs` `invalid_marker_strips_shell_calls_with_unparseable_commands`, `long_bash_lc_script_in_argv_is_not_dropped_by_the_match_budget`, **`a_leading_double_slash_candidate_does_not_escape_posix_ignore_paths_via_flavor_mismatch`** (GHSA-vh98 adversarial: attempts the `//repo/secret/...` violation on a POSIX host, proves it now drops, with a plain-single-slash control and a Windows-hosted genuine-UNC control both still correct — fails on the pre-fix code); `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool`, `gemini_cli_shell_and_read_many_files_exclusions_drop_before_spool` (pre- and post-tool events with an excluded path are never spooled; public controls spool with their family); `capture_policy.rs` `read_many_files_directory_entries_cannot_reach_ignored_paths` (shared `read_many_files_directories` vectors: `docs`, `.`, `./`, `docs/`, case and `..` variants drop; `src`, `README.md`, `docs/adrx` kept), `output_reader_tools_are_metadata_only_only_under_a_policy` (active and invalid strip, inactive and an unrelated unknown tool keep), `copilot_cli_runtime_file_tools_are_scoped_to_copilot`, `unevaluated_shell_expansions_respect_quoting` (also leading-`]` classes, zsh groups and extglobs, ANSI-C numeric escapes; subshells, `$((…))`, `<(…)`, array assignments kept), the shell fixture's brace/class vectors (quoted, escaped, `${…}`, `{}`, `[ … ]`, `HEAD@{1}` controls kept); `quoted_scripts_in_string_commands_are_read_like_command_lines` (`sh -c`, `timeout … bash -c`, `"$(…)"`, `NAME="$(…)"`, backquotes, two nested shells and an inline-interpreter literal drop; `bash -c 'cargo test'` and `"$(git rev-parse HEAD)"` kept; four levels read, a fifth metadata-only), `inline_interpreter_code_is_metadata_only_under_an_active_policy` (inline code metadata-only, kept with no policy; modules, script files and `grep -e` unaffected), `git_object_names_are_path_candidates` (`HEAD:`, `:`, `:N:` and `@{n}` names drop, also from a subdirectory; drive letters, URLs, `NAME=a:b` and flags are not object names; a public object name kept), `ansi_c_strings_and_escaped_letters_are_read_like_the_shell`, `antigravity_run_command_resolves_arguments_from_its_cwd` (absolute and relative `Cwd` drop, a public `Cwd` kept, another agent's `Cwd` key ignored), `windows_escape_characters_are_read_on_a_windows_host` (caret and backquote spellings drop on a Windows host, public controls kept, a POSIX host reads both literally), `a_case_folding_host_matches_paths_without_regard_to_case` (file tool and shell drop with folding, keep without, public control kept; folding injected through `resolve_for_host` so it runs on every CI OS), the shell fixture's continuation, PowerShell/cmd escape, option-value, runner, interpreter, glued-flag, `file:` URL, tilde, parameter-default and `fold_case` vectors with their controls, the near-miss controls added to `common_commands_stay_kept_under_an_active_policy` (also quoted tildes, a `file:` URL with a query, a shallow nested default and a scratchpad log), the shell fixture's `file:` query/fragment, deep-default, escaped-default, quoted/argv/script tilde, PowerShell tilde, harness-output and Unicode `fold_case` vectors and the `decisions` harness-output vectors with their controls, `reading_a_harness_output_spool_is_metadata_only_under_a_policy` (active and invalid strip, inactive keeps, same-named files elsewhere kept, an ignored path still drops), `capture_lookup_locations_name_every_path_a_call_spells`, the Unicode rows of `a_case_folding_host_matches_paths_without_regard_to_case`, **`hook.rs` `another_checkouts_exclusions_hold_for_a_call_made_elsewhere`** (relative, absolute, glob and unmarked-Hermes shell calls naming another checkout's excluded file never spool; a broken foreign marker and too many foreign markers spool metadata-only; public, own-file and few-marker controls spool with content), **`hook.rs` `globs_searches_and_unreadable_targets_answer_to_another_checkout`** (sibling and parent-folder `*`, brace, bracket, `**` and separator-spanning-brace shell globs, a Grep path, a Glob pattern, a parent-folder Grep filter, a Gemini `search_file_content` directory, a Codex `apply_patch` header and a target-less Read never spool content; public-glob, own-glob, own-`**`, own-search, own-Glob-`**`, public-search and own-patch controls spool with content), `transcript_capture.rs` `globs_and_searches_reaching_another_checkout_honor_its_policy`, `capture_policy.rs` `glob_walk_follows_every_segment_a_glob_could_pass_through`, `an_invalid_policy_makes_a_search_metadata_only`, `a_brace_that_builds_a_parent_step_cannot_be_walked`, `a_parent_step_after_a_globstar_is_read_both_ways`, `glob_groups_and_ansi_c_escapes_reach_the_marker_lookup`, `a_saved_output_glob_needs_its_distinctive_name_in_literal_text`, `indented_patch_headers_and_hermes_file_globs_reach_the_marker_lookup`, `a_dot_glob_directory_that_can_match_the_parent_is_read_as_it` (POSIX classes and extglob groups included), `an_oversized_brace_expansion_is_walked_unless_its_pieces_could_leave` (each attack with its control), the shell fixture's double-quoted `bash -c`/`eval` ANSI-C vectors and their controls, `marker.rs` `marker_memo_answers_like_find_marker_once_per_directory`, **`hook.rs` `a_globstar_above_the_checkout_skips_the_own_subtree`** (regression: `ls ../**/README.md` from a 300-directory checkout with no policy is not metadata-only; the sibling `cat ../**/secrets.env` drops), **`hook.rs` `marker_lookups_in_a_deep_tree_cost_one_probe_per_directory`** (regression: 300 paths in a 300-level tree cost fewer than five probes per level; out of budget inside the checkout kept, outside it metadata-only, the sibling checkout's location looked up before a long list inside the checkout, and a shallow nested marker before a deep list), **`hook.rs` `a_dotfiles_checkout_at_home_is_not_the_own_checkout`** (with `~/.git`, `cat */secrets.env` from `~/Projects` drops; a harmless glob kept), the shell fixture's dot-glob directory vectors and their controls, the shell fixture's `**`-then-`..` and `*.log` vectors and the `read_many_files_directories` `**`-then-`..` vectors, **`hook.rs` `constructed_parent_steps_answer_to_another_checkout`** (a `..` after a `**` through a shell, a Glob pattern and a Grep filter, four brace expansions that build a parent step, two zsh glob groups, hex and octal ANSI-C escapes, two dot-glob directory segments, a POSIX-class and four extglob dot-glob segments, a brace-built dot-glob, an oversized brace sequence over `.`, ANSI-C strings in a double-quoted `bash -c` and `eval`, an indented `apply_patch` header next to an unindented one and a Hermes `file_glob` never spool content; the same shapes inside the checkout spool with it, and so do four brace expansions too large to list that cannot leave it, which v2.6.3 kept), **`hook.rs` `a_monorepo_glob_inside_the_own_checkout_is_not_walked`** (in a 300-package checkout, with and without a policy of its own, `packages/*` shell globs stay kept and the sibling `../*/secrets.env` and `../a/*.env` attacks still drop), `hook.rs` `a_glob_walk_outside_the_checkout_stops_at_its_bounds` (directory bound counted while a `**` lists, time budget through an injected clock, no walk inside the checkout), the Node evidence test's `monorepo-*`, `walk-*`, `con-*`, `globstar-*`, `deep-*` and `dotfiles-*` checks, and the Node evidence test's `glob-*`, `search-*`, `patch-*` and `unreadable-target` checks with their controls and `transcript_capture.rs` `a_shell_command_naming_another_checkouts_file_honors_its_policy`, both failing with the foreign lookup disabled, and the Node evidence test's `cross-*` and `fold-unicode` checks, which fail with `captureForeignConfigs` disabled, and the shell fixture's quoted-script, git-object, ANSI-C, escaped-letter and inline-interpreter vectors with their controls (`cargo test`, `git status`/`log`, `pytest`, `python3 -m pytest`, `node build.js`, `npm run test`, a quoted commit message with braces); `router.rs` `capture_protocol_active_keep_of_unprovable_output_is_stripped`; `hook.rs` `excluded_content_cannot_reach_the_spool_through_unevaluated_tool_shapes` (directory entries and Copilot `view`/`create` never spool, readers and brace shells spool without content, public controls spool with it); `capture_policy.rs` `droid_tool_calls_honor_capture_exclusions` (`Read`/`Create`/`Edit` naming an ignored path drop and a control path keeps, `ApplyPatch` is metadata-only like Codex `apply_patch` and its headers name the lookup location, `LS`/`Grep`/`Glob` drop and their directory and glob arguments locate the call, `Execute` naming an ignored path drops; every excluded case keeps under `AgentKind::Other`, so it fails with the Droid `extract` arm or the `Create`/`ApplyPatch` mapping removed) and the `droid` `decisions` fixture vectors (#1240); `capture_policy.rs` `muse_tool_calls_honor_capture_exclusions` (`read_file`/`write_file`/`edit_file` naming an ignored path, relative or absolute, and the project-scope memory tools naming an ignored `.agents/memory` path drop while a control path keeps, personal-scope memory calls are metadata-only, `apply_patch` is metadata-only like Codex's, `search` drops, `bash`/`monitor` naming an ignored path from their `workdir` drop, `bash_input` is metadata-only; each excluded case keeps under `AgentKind::Other`, so it fails with the Muse `extract` arm removed), `muse_tool_payload_fields_carry_the_call_id` and the `muse` `decisions` fixture vectors, taken from Muse Code 1.4.7 hook payloads; `capture_policy.rs` `codebuddy_tool_calls_honor_capture_exclusions` (`Read`/`Write`/`Edit`/`Bash` naming an ignored path drop, a control path keeps, and every excluded case keeps under `AgentKind::Other`, so it fails with the CodeBuddy `extract` arm removed) and the `codebuddy` `decisions` fixture vectors; `render_shared.rs` `generated_capture_policy_v1_node_runtime_evidence` (runs the same fixture sections, including the GHSA-vh98 and Gemini `read_many_files`/`run_shell_command` vectors, plus unsupported-glob, empty-list and recursive-`**` checks, against the emitted TypeScript; `#[ignore]` locally, run with `--ignored` under Node 24 by the Linux CI test job); `hook.rs` `check_capture_refuses_partial_scope_and_excluded_content` (ignored-path and partial-scope violations refused, complete public-path control passes), `check_capture_bounds_marker_hints_and_refuses_oversized_scope` (513-byte hints refused, 512-byte control passes; native routing preserved); **`backfill.rs` `backfill_never_posts_tool_content_the_capture_policy_excludes`** (planted Claude transcript: the excluded read's call and output never reach `/hook/batch`, a malformed read posts only the metadata-only body, public read control posted) and **`run.rs` `ledger_upload_drops_tool_content_the_capture_policy_excludes`** (excluded call and output absent from the finish request, public control present, cursor still advances), both failing with the guard removed; **`recovery.rs` `finish_failed_recovery_never_posts_content_the_capture_policy_excludes`** and **`degraded_run_recovery_never_posts_content_the_capture_policy_excludes`** (a full `recover` pass over a journaled Claude transcript with exact digests and cursor, marker `ignore_paths = ["secrets/**"]`: the excluded read's path and `SENTINEL_RECOVERY_MUST_NOT_POST` output never reach `/workstream/runs/{id}/recover` or `/hook/batch`, the public read's output does; each fails when its own call site's capture is built for `/` instead of the entry's `cwd`, on the control since a foreign-scoped capture fails closed, and both fail on the sentinel when `for_checkout` loses the marker's policy); `transcript_capture.rs` `an_excluded_read_drops_its_call_and_result_by_id`, `id_less_results_take_the_strictest_call_of_their_turn`, `unrecoverable_arguments_and_orphan_results_fail_closed_under_a_policy`, `a_call_into_another_checkout_honors_its_policy`, `ledger_events_are_dropped_or_stripped_before_upload`, `without_a_policy_every_event_is_kept` (control); `capture_policy.rs` `tool_call_payload_reaches_the_live_decision_for_every_supported_agent`; **`backfill.rs` `allowlist_mode_backfills_nothing_from_an_unmarked_checkout`** (no request reaches the server; marked-checkout and denylist controls do), **`run.rs` `ledger_upload_under_allowlist_mode_carries_nothing_from_an_unmarked_checkout`** (finish carries no prompt or tool content; marked and denylist controls upload both), `transcript_capture.rs` `allowlist_mode_admits_nothing_from_an_unmarked_checkout`, all failing with the admission gate removed; **`backfill.rs` `backfill_inspects_codex_exec_command_as_the_hook_shell_call`** and **`run.rs` `ledger_upload_inspects_codex_exec_command_as_the_hook_shell_call`** (a planted Codex `exec_command` whose `workdir`-relative argument names an ignored file never posts its call or output; the same command from a public `workdir` does), `capture_policy.rs` `codex_transcript_exec_command_is_inspected_as_the_hook_bash_call` (absolute, relative and absent `workdir` and an argv `cmd` drop, public control kept, the `workdir` locates the call, another agent's `exec_command` stays unknown), all failing with `hook_tool_call` removed; **`backfill.rs` `backfill_resolves_each_call_from_its_record_cwd`** (`cat adr/x.md` recorded from `docs/` never posts; the same command from the root does) and `transcript.rs` `jsonl_events_carry_their_record_cwd` (Claude per line, Codex per turn context, a relative cwd ignored), failing with the record cwd ignored or unstamped; **`backfill.rs` `backfill_drops_reroutes_the_live_hook_would_not_deliver_here`** (under allowlist mode, reads rerouted to an unmarked git repository, to a marker selecting an unregistered profile, and to a marker selecting a registered profile while the source uses the install default are never posted; a read in a marked checkout with no server selection is the posted control), failing with either the admission check or the route comparison removed (each refused case checked on its own); `transcript_capture.rs` `a_record_cwd_answers_to_the_hook_admission_gate_there` (prompt, call and result recorded in an unmarked repository drop under allowlist; a subdirectory of the opted-in checkout is kept and its record cwd never reaches the ledger) and `claude_shell_mode_output_is_not_imported` (stdout, stderr, local-command and size-capped blocks drop; `<bash-input>`, a prompt quoting a tag, and another agent's message kept); **`backfill.rs` `backfill_posts_no_content_for_unrecognized_tools`** (a planted Codex MCP call's arguments and output never post, the call and output post as `tool unknown`; a recognized shell output is the posted control) and `transcript_capture.rs` `unrecognized_tools_keep_no_content_with_or_without_a_policy` (no policy and an active one; ledger content withheld; public read kept; a call-less result content-free), failing with the unknown-family rule removed, the backfill one also with its content-free body removed; **`backfill.rs` `backfill_keeps_reroutes_to_the_same_server_profile_only`** (a reroute into a checkout selecting the source's registered profile and project is posted; one selecting a different registered profile is not, nor one of another project on the same profile, nor a prompt recorded there), failing with the profile comparison forced either way and with the project comparison removed; `transcript_capture.rs` `a_record_cwd_in_another_project_is_dropped` and `a_reroute_into_another_project_is_dropped` (prompt, call and result recorded in, or a read reaching into, a checkout declaring another project drop; one declaring the same project is kept), failing with `routes_to_same_project` removed; `hook.rs` `subdirectories_of_one_repository_are_one_project_only_under_repo_root` (two subdirectories of an unmarked repository, and a subdirectory importing its root, are two projects; the same directory, the root importing a subdirectory and a `repo-root` marker agree), failing with the basename rule removed; **`backfill.rs` `backfill_posts_no_task_notification_or_compact_summary_as_a_prompt`** and `transcript.rs` `claude_adapter_keeps_task_notifications_and_compact_summaries_out_of_prompts` (a monitored command's notification, a background agent's report and an origin-tagged notice are excluded, also behind a byte-order mark and zero-width characters, in another case, with attributes, after a non-text block, or with an origin kind in another case; a compact summary, also flagged `"true"` or `1`, becomes a compaction event; the typed prompt, also one quoting the tag, and a look-alike tag are the controls), failing with either adapter rule removed or with the spelling rules reverted; `transcript_capture.rs` `boundary_events_answer_to_the_record_cwd_admission_gate` (compaction and annotation recorded in a refused directory drop; in the checkout kept), `a_result_whose_id_matches_no_call_is_an_orphan` (an unmatched id cannot borrow a public read's keep; the read's own result kept), `claude_shell_mode_output_is_not_imported` (a block holding a literal closing tag drops) and `unrecognized_tools_keep_no_content_with_or_without_a_policy` (ledger keeps no tool name and no invalid call id), each failing with its rule reverted; `windows_spelling_fixture_vectors` (shared `capture-policy.json` `windows` drop vectors for every spelling above, file tool and shell, with other-drive, other-share, longer-name and pipe controls, and `windows_posix_controls` proving a POSIX session keeps `/c/…`, trailing-dot and colon names; `windows_scopes` drop vectors for a `\\?\C:\`, `\\?\UNC\…`, `\\localhost\C$\…` or UNC cwd and marker directory with relative patterns, a `\\?\C:\…` absolute pattern from `C:\repo`, bare and double-quoted `\\server\share\…`/`\\?\…`/`\\.\…`/`\\localhost\c$\…` PowerShell, cmd, `run_shell_command` and argv commands, and both readings of `/a/x` from `D:\a\…`, each with public-path, other-drive and other-share keep controls; the Node runtime evidence runs the same vectors with the marker spelled in the Windows cwd), `tool_family_fixture_vectors` (shared `tool_families`, every native name per family), new `decisions` vectors (`execute_code` metadata-only, `read_file`/`patch`/`fs_read` operations drop, `write_to_file`/`browser_navigate` keep), `output_spool_work_is_linear_and_budgeted` (a 2,040-wildcard-segment path stays under a linear work bound; 32 such paths fail closed; one long or 32 short paths keep), `an_oversized_shell_command_is_unprovable` (one character over the limit is metadata-only and unlooked-up, at the limit keeps, argv summed, inactive untouched), `inline_code_tools_are_unprovable_under_a_policy`, `hook_capture::capture_section_spellings_match_toml_semantics` (shared `marker_spellings`, including a nested-array line `["docs"]` before a dotted `capture.ignore_paths` that must still drop, and a key line inside an open array, text after a closed array and a multi-line inline table that must fail closed), and the Node evidence test running all of these vectors against the generated TypeScript plus its entry-bound read count for the directory walk; each fails with its rule reverted (Windows reading off, spool memo dropped or budget failing open, length check off, inline-code rule off, a name dropped from the list, TS dotted key or inline-table rule reverted, TS walk back on `readdirSync`, Windows reading of the cwd/marker directory or of an absolute pattern off, literal-backslash reading off, the cwd-drive reading of `/a/x` off, TS array tracking or any `captureValueScan` refusal off, Rust and TS alike); new `windows_scopes` vectors (drive-relative, device-namespace and Git Bash doubled-backslash shell words and a `C:docs` `workdir` metadata-only, `FileSystem::` file paths, shell words and `workdir` dropping, a POSIX absolute pattern in a Windows marker failing closed, with `type README.md`, `dir /s /q`, `git status`, a URL, `type C:\repo\README.md` and `Get-Content -Path C:\repo\README.md` kept) and `windows_marker_rejects_posix_absolute_patterns` (the same pattern stays active in a POSIX marker) fail natively and in the Node evidence test with the unplaceable check, its device branch, the `workdir` check, the provider strip or the marker rejection removed; `inspection_sentinel_matches_cwd_flavor` (#1250: POSIX sentinel Invalid on a Windows cwd, Windows-flavored sentinel Active there and on UNC, POSIX sentinel Active on `/repo` and Git Bash `/c/repo`) is native only, since `inspection_sentinel` is server re-inspection with no TypeScript counterpart, and fails with the cwd-flavored sentinel or the marker rejection removed; removing the POSIX-reading excusal makes `type C:\repo\README.md` metadata-only, and excusing a device reading keeps the doubled-backslash device path; `capture_policy.rs` `windows_lookup_locations_keep_glob_segments_whole` (a Windows session trims trailing dots from plain segments only, so `{.,}.` still reaches `..` and the sibling checkout's marker; bites with the glob-segment exemption removed) | STRONG with listed residuals. Matching is lexical by design, so these stay open: shell variables (`$VAR`, `FILE=… sh -c 'cat $FILE'`) and the output of a command substitution, a `cd` inside the command, a script read from a file or a heredoc fed to an interpreter (read only for the words it spells out), git's repository root approximated by the marker directory, symlinks (paths are never resolved on disk), a recursive search of a parent directory (`grep -r x docs`, `rg x`) through a shell, a search tool rooted at a literal directory above another checkout (it is not walked) and a glob whose literal root lies inside the event's own checkout reaching a checkout nested there (it is not walked), a marker nested inside the own checkout below what the lookup budget reaches, a `.git` the same command creates (`touch .git; cat */x`: the hook reads the tree after the command ran, so that directory counts as the own checkout; a `.git` at or above the home directory never does), a parameter expansion next to glob syntax (`${X}/*/x`, not walked), a glob through a symlinked directory, a tool's own directory option (`git -C`), script runners and interpreters the matcher does not list (their words are still read, but expansion or inline code in them is not recognized), a value glued after the first letter of a short-flag cluster, non-ASCII percent-escapes in a `file:` URL, a bare word naming another checkout's directory (only separator-bearing arguments are looked up for another marker), harness output files outside the listed default locations, and tools the matcher does not list, which keep their current unknown-tool behavior. Transcript imports add: assistant prose quoting an excluded file is kept (as live prompt/assistant capture keeps it), harnesses whose hook schema the matcher does not read (Crush, Kimi Code) keep their tool events as live capture would, adapters that record no per-record cwd (Pi, OMP, OpenCode, Crush, Kimi Code, Command Code, Kiro, Grok) judge every event from the session cwd, a Codex ledger upload resumed from a mid-file cursor judges the events before the next turn context from the session cwd, and id-less adapters over-drop a whole turn's results when one call is excluded, and when the routing hints leave the project to the server, events from inside one repository count as the importing project even where the server has a separate project registered for a subdirectory (anywhere under `repo-root`; under `basename` only when the import runs from the repository root); a metadata-only import keeps an `event_id` (ledger) and `ingest_key` (backfill) derived from a SHA-256 of the original content plus session and record ids, left in place because those ids are the retry-dedupe keys and a content-free id would merge distinct events — it only confirms a guess of low-entropy content. Under allowlist mode a refused checkout's `ai-memory run` still records repository checkpoint metadata (HEAD, branch, a status hash and changed-path names, never file content), which the run also sends at launch. Re-splitting quoted words over-drops a quoted message naming an ignored path, and inline interpreter code is metadata-only under an active policy. Mitigation: allowlist capture mode (`install-hooks --capture-mode allowlist`) for sensitive projects. Bite checks: removing the nested re-split, the git object path or its marker-root base, Antigravity's `Cwd` key, the leading-`]` rule, either zsh-group rule, ANSI-C decoding or its numeric-escape rule, the `\o` reading, the inline-code rule, the nesting-depth rule, the nested-script scan, the line-continuation join, the Windows escape reading, the shell-option and interpreter-option value skips, the added runners and interpreters, the glued-flag value, the `file:` URL path, the `~+` resolution, the unknown-tilde rule, the parameter-default reading or case folding each fails the Rust tests, and each TypeScript counterpart fails the Node evidence test; so does reverting the `file:` URL cut, the deep-default rule, the escaped-default reading, the quoted-tilde rule, the harness-output rule or Unicode folding (the new fixture vectors fail against the previous matchers in both languages), and disabling the foreign-marker lookup fails the native, import and Node cross-checkout tests; reading every glob location as literal, skipping search/list locations, or skipping a file tool whose targets cannot be read each fails the native, import and Node glob/search/unreadable tests, removing `apply_patch` header reading fails the own-patch control, and reverting the saved-output glob rule fails the new fixture vectors in both languages; walking globs rooted inside the event's checkout fails the monorepo tests, accepting any literal text for a saved-output glob fails the `*.log` vectors, removing the time budget or counting a `**`'s directories only after it lists fails the bounds tests, and removing the `**`-then-`..` readings, the brace-expansion check, the expanded lookup words, the patch-header trim, the `file_glob` key or the dot-glob parent reading each fails the Rust tests and the Node evidence test; treating every oversized brace expansion as leaving, dropping the brace-built dot-glob check, listing the own checkout's subtree under a `**`, looking up locations in their given order (outside before inside, then shallowest first), dropping the per-directory memo, counting a checkout at home as the own one, keeping the backslash before `$` in double quotes, or dropping the POSIX-class or extglob reading each fails its Rust test and the Node evidence test; in a Windows session a shell `workdir` spelled `/c/x` is read only as Git Bash reads it, so arguments resolved from it miss a native tool's `D:\c\x` reading, the TS marker reader rejects structural errors anywhere in the marker but does not validate other values' TOML (`x = nope` invalidates the policy only natively), an administrative share reached through a loopback or host alias other than `localhost`/`127.0.0.1` (`\\127.0.0.2\c$`, `\\127.1\c$`, `\\<hostname>\c$`) or a `\\wsl$\…` path is matched as the UNC path it spells, Windows matching folds ASCII case only, and a drive-relative word counts as placed when a placeable argument's POSIX reading spells it; a `**/` matches one or more directories, never zero (documented in `marker-file.md`) || 11c | Capture hook ≤200ms budget (invariant #5) | `hooks/_lib.sh` capture path `curl --max-time 0.2` (context-fetch 1.0s and background drain 2.0s are separate, larger-budget paths) | none (shell-script timeout; hard to unit-test) — watch on any capture-path change | WATCH |