1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
use super::*;
impl SqliteMetadataStore {
/// Apply a lifecycle delta and return the number of rows affected.
///
/// Same semantics as `MetadataStore::update_lifecycle` but the
/// concrete rowcount is exposed so callers can fail closed when
/// the UPDATE matched zero rows (non-existent chunk_id OR
/// cross-tenant access — the WHERE filter silently drops both
/// otherwise). `memory.set_expiry` uses this to make
/// `{"updated": true}` a load-bearing claim.
pub fn update_lifecycle_counted(
&self,
tenant_id: &TenantId,
chunk_id: &ChunkId,
delta: &LifecycleDelta,
) -> Result<usize> {
let conn = self.pool.get();
// `status != 'deleted'` guard: once a row is tombstoned no
// caller should be mutating its overlay. Before this guard,
// `memory.set_expiry` could flip `expires_at_ms` on a deleted
// row (and bump the cache) even though the row was invisible
// to every retrieval surface. The guarded UPDATE matches zero
// rows for deleted chunks, so the atomic
// `update_lifecycle_if_exists` path returns `updated=false`
// end-to-end.
let rows = conn.execute(
"UPDATE chunks SET
status = COALESCE(:status, status),
tier = COALESCE(:tier, tier),
supersedes = COALESCE(:supersedes, supersedes),
superseded_by = COALESCE(:superseded_by, superseded_by),
expires_at_ms = CASE WHEN :set_expires = 1 THEN :expires_at ELSE expires_at_ms END,
review_after_ms = CASE WHEN :set_review = 1 THEN :review_at ELSE review_after_ms END,
lifecycle_updated_at_ms = COALESCE(:lifecycle_at, lifecycle_updated_at_ms)
WHERE tenant_id = :tenant
AND chunk_id = :chunk
AND status != 'deleted'",
rusqlite::named_params! {
":status": delta.status.map(|s| s.to_string()),
":tier": delta.tier.map(|t| t.to_string()),
":supersedes": delta.supersedes.as_ref().map(|c| c.to_string()),
":superseded_by": delta.superseded_by.as_ref().map(|c| c.to_string()),
":set_expires": i64::from(delta.expires_at_ms.is_some()),
":expires_at": delta.expires_at_ms.flatten(),
":set_review": i64::from(delta.review_after_ms.is_some()),
":review_at": delta.review_after_ms.flatten(),
":lifecycle_at": delta.lifecycle_updated_at_ms,
":tenant": tenant_id.as_str(),
":chunk": chunk_id.to_string(),
},
)?;
Ok(rows)
}
pub(super) fn atomic_supersede_lifecycle(
&self,
tenant_id: &TenantId,
old_id: &ChunkId,
new_id: &ChunkId,
now_ms: i64,
) -> Result<()> {
let mut conn = self.pool.get();
let tx = conn.transaction()?;
// Both UPDATEs must touch exactly one row; otherwise one side of
// the supersession edge would dangle. Returning an error here
// drops the `Transaction` without commit, which rolls the
// partial update back on SQLite's side.
//
// `superseded_by IS NULL` in the WHERE clause enforces head-only
// semantics at the SQL layer: an old chunk that already points
// to a successor won't match, rows=0 triggers the guard below,
// and the transaction rolls back. Without this, a double-
// supersede on the same old chunk would silently overwrite
// `superseded_by` and fork the graph.
let old_rows = tx.execute(
"UPDATE chunks SET status = 'superseded', superseded_by = :new,
lifecycle_updated_at_ms = :now
WHERE tenant_id = :tenant AND chunk_id = :old
AND superseded_by IS NULL",
rusqlite::named_params! {
":new": new_id.to_string(),
":now": now_ms,
":tenant": tenant_id.as_str(),
":old": old_id.to_string(),
},
)?;
if old_rows != 1 {
return Err(crate::error::MemdError::ValidationError(format!(
"atomic_supersede: old chunk {old_id} is not current head or missing in tenant {tenant_id} (rows={old_rows})"
)));
}
let new_rows = tx.execute(
"UPDATE chunks SET supersedes = :old, lifecycle_updated_at_ms = :now
WHERE tenant_id = :tenant AND chunk_id = :new",
rusqlite::named_params! {
":old": old_id.to_string(),
":now": now_ms,
":tenant": tenant_id.as_str(),
":new": new_id.to_string(),
},
)?;
if new_rows != 1 {
return Err(crate::error::MemdError::StorageError(format!(
"atomic_supersede: new chunk {new_id} not found in tenant {tenant_id} (rows={new_rows})"
)));
}
tx.commit()?;
Ok(())
}
pub(super) fn list_expired_before_lifecycle(
&self,
tenant_id: &TenantId,
now_ms: i64,
) -> Result<Vec<ChunkId>> {
let conn = self.pool.get();
// Use `<=` so this matches `VisibilityPolicy::is_visible_at`
// (which hides any row with `expires_at_ms <= now_ms`); otherwise
// a row expiring exactly at `now_ms` is hidden by retrieval but
// never materialised to status=Expired by the sweep until the
// next invocation, which breaks the sweep→promote pipeline.
let mut stmt = conn.prepare(
"SELECT chunk_id FROM chunks
WHERE tenant_id = ?1
AND expires_at_ms IS NOT NULL
AND expires_at_ms <= ?2
AND status NOT IN ('candidate', 'deleted', 'expired', 'superseded', 'error')",
)?;
let rows = stmt.query_map(rusqlite::params![tenant_id.as_str(), now_ms], |row| {
row.get::<_, String>(0)
})?;
let mut ids = Vec::new();
for row in rows {
let s = row?;
let id = ChunkId::parse(&s).map_err(|e| {
rusqlite::Error::FromSqlConversionFailure(
0,
rusqlite::types::Type::Text,
Box::new(e),
)
})?;
ids.push(id);
}
Ok(ids)
}
pub(super) fn mark_expired_if_final_lifecycle(
&self,
tenant_id: &TenantId,
chunk_id: &ChunkId,
now_ms: i64,
) -> Result<bool> {
// Guarded UPDATE: only promote rows that are *still* eligible
// right now. Two predicates together:
//
// 1. `status = 'final'` — any other status (deleted,
// superseded, expired, error) is treated as "raced out from
// under the sweep" and skipped so we never overwrite a
// newer lifecycle transition.
// 2. `expires_at_ms IS NOT NULL AND expires_at_ms <= :now_ms` —
// re-checks the retention predicate at UPDATE time so a
// concurrent writer that cleared `expires_at_ms` or pushed
// it forward (while leaving status=final) does not get its
// row reclassified as Expired by a sweep that selected the
// row before that write landed.
let conn = self.pool.get();
let rows = conn.execute(
"UPDATE chunks
SET status = 'expired',
lifecycle_updated_at_ms = ?3
WHERE tenant_id = ?1
AND chunk_id = ?2
AND status = 'final'
AND expires_at_ms IS NOT NULL
AND expires_at_ms <= ?3",
rusqlite::params![tenant_id.as_str(), chunk_id.to_string(), now_ms],
)?;
Ok(rows == 1)
}
pub(super) fn promote_to_history_if_stale_lifecycle(
&self,
tenant_id: &TenantId,
chunk_id: &ChunkId,
older_than_ms: i64,
now_ms: i64,
) -> Result<bool> {
// Guarded UPDATE: re-check status, tier, and the overlay-idle
// clock at UPDATE time so a concurrent writer that refreshed
// lifecycle_updated_at_ms or flipped the row back off
// superseded/expired is not clobbered by a stale selection.
let conn = self.pool.get();
let rows = conn.execute(
"UPDATE chunks
SET tier = 'history',
lifecycle_updated_at_ms = ?4
WHERE tenant_id = ?1
AND chunk_id = ?2
AND status IN ('superseded', 'expired')
AND tier != 'history'
AND lifecycle_updated_at_ms < ?3",
rusqlite::params![
tenant_id.as_str(),
chunk_id.to_string(),
older_than_ms,
now_ms
],
)?;
Ok(rows == 1)
}
pub(super) fn list_stale_superseded_lifecycle(
&self,
tenant_id: &TenantId,
older_than_ms: i64,
) -> Result<Vec<ChunkId>> {
let conn = self.pool.get();
let mut stmt = conn.prepare(
"SELECT chunk_id FROM chunks
WHERE tenant_id = ?1
AND status IN ('superseded', 'expired')
AND tier != 'history'
AND lifecycle_updated_at_ms < ?2",
)?;
let rows = stmt.query_map(
rusqlite::params![tenant_id.as_str(), older_than_ms],
|row| row.get::<_, String>(0),
)?;
let mut ids = Vec::new();
for row in rows {
let s = row?;
let id = ChunkId::parse(&s).map_err(|e| {
rusqlite::Error::FromSqlConversionFailure(
0,
rusqlite::types::Type::Text,
Box::new(e),
)
})?;
ids.push(id);
}
Ok(ids)
}
pub(super) fn list_lifecycle_hidden_impl(&self, tenant_id: &TenantId) -> Result<Vec<ChunkId>> {
let conn = self.pool.get();
// Must mirror `VisibilityPolicy::is_visible` (types.rs). Any status
// or tier that `is_visible` hides regardless of the include_*
// flags — Candidate, Superseded, Expired, Error, plus
// MemoryTier::History —
// must be in this set so the HNSW rebuild excluded set matches
// retrieval-side hiding. Missing a category means the rebuilt
// HNSW carries graph weight for chunks that the handler will
// never surface.
//
// `Deleted` is intentionally NOT here: it comes from
// `get_deleted_chunk_ids` instead (tombstone path with its own
// metrics), and the runner unions the two sets before passing
// to `rebuild_hnsw_for_tenant`.
let mut stmt = conn.prepare(
"SELECT chunk_id FROM chunks
WHERE tenant_id = ?1
AND (status IN ('candidate', 'superseded', 'expired', 'error') OR tier = 'history')",
)?;
let rows = stmt.query_map(rusqlite::params![tenant_id.as_str()], |row| {
row.get::<_, String>(0)
})?;
let mut ids = Vec::new();
for row in rows {
let s = row?;
let id = ChunkId::parse(&s).map_err(|e| {
rusqlite::Error::FromSqlConversionFailure(
0,
rusqlite::types::Type::Text,
Box::new(e),
)
})?;
ids.push(id);
}
Ok(ids)
}
}