topodb 0.0.6

Embedded, local-first memory engine for AI agents: temporal property graph + scoped recall.
Documentation 
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

//! Interned on-disk record twins; public records remain string-carrying.
//!
//! Two generations live here side by side:
//! - `NodeRecordDisk`/`EdgeRecordDisk` (+ `node_to_disk`/`edge_to_disk`) are
//!   the FROZEN v2 ENCODE shape: ULID-keyed rows, `scope: Scope`, ULID
//!   `from`/`to`. Kept byte-for-byte as originally written because
//!   `migrate.rs`'s v1->v2 step calls these exact functions to produce v2
//!   rows — changing them in place would silently corrupt the v1->v2->v3
//!   chain and break `migrate.rs` without touching that file. There is no
//!   corresponding `node_from_disk`/`edge_from_disk` decode pair: nothing
//!   in the live crate reads v2 rows through this frozen shape —
//!   `migrate_v3.rs` decodes v2 rows through its OWN frozen
//!   `NodeRecordDiskV2`/`EdgeRecordDiskV2` twins instead.
//! - `NodeRecordDiskV3`/`EdgeRecordDiskV3` (+ `*_v3` functions) are the LIVE
//!   v3 record-table shape (v3 spec §3): `scope` is the interned `u32`
//!   scope-registry id, and edge endpoints are `u64` node slots. These are
//!   what `storage.rs`'s NODES/EDGES read/write paths and `migrate_v3.rs`'s
//!   v2->v3 re-keying use.
use crate::dict::{DictKind, Dicts};
use crate::error::TopoError;
use crate::ids::{EdgeId, NodeId, Scope};
use crate::props::PropValue;
use crate::scopes::ScopeRegistry;
use crate::state::{EdgeRecord, NodeRecord};
use redb::{ReadableTable, Table};
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
#[derive(Debug, Serialize, Deserialize)]
pub(crate) struct NodeRecordDisk {
    pub id: NodeId,
    pub scope: Scope,
    pub label: u32,
    pub props: BTreeMap<u32, PropValue>,
}
#[derive(Debug, Serialize, Deserialize)]
pub(crate) struct EdgeRecordDisk {
    pub id: EdgeId,
    pub scope: Scope,
    pub ty: u32,
    pub from: NodeId,
    pub to: NodeId,
    pub props: BTreeMap<u32, PropValue>,
    pub valid_from: i64,
    pub valid_to: Option<i64>,
}
pub(crate) fn node_to_disk(
    r: &NodeRecord,
    t: &mut Table<'_, &'static [u8], &'static str>,
    d: &mut Dicts,
) -> Result<NodeRecordDisk, TopoError> {
    let mut p = BTreeMap::new();
    for (k, v) in &r.props {
        p.insert(d.intern(t, DictKind::PropKey, k)?, v.clone());
    }
    Ok(NodeRecordDisk {
        id: r.id,
        scope: r.scope,
        label: d.intern(t, DictKind::Label, r.label.as_str())?,
        props: p,
    })
}
pub(crate) fn edge_to_disk(
    r: &EdgeRecord,
    t: &mut Table<'_, &'static [u8], &'static str>,
    d: &mut Dicts,
) -> Result<EdgeRecordDisk, TopoError> {
    let mut p = BTreeMap::new();
    for (k, v) in &r.props {
        p.insert(d.intern(t, DictKind::PropKey, k)?, v.clone());
    }
    Ok(EdgeRecordDisk {
        id: r.id,
        scope: r.scope,
        ty: d.intern(t, DictKind::EdgeType, r.ty.as_str())?,
        from: r.from,
        to: r.to,
        props: p,
        valid_from: r.valid_from,
        valid_to: r.valid_to,
    })
}
// ---- v3 live record-table shapes (v3 spec §3) ----

#[derive(Debug, Serialize, Deserialize)]
pub(crate) struct NodeRecordDiskV3 {
    pub id: NodeId,
    pub scope: u32,
    pub label: u32,
    pub props: BTreeMap<u32, PropValue>,
}
#[derive(Debug, Serialize, Deserialize)]
pub(crate) struct EdgeRecordDiskV3 {
    pub id: EdgeId,
    pub scope: u32,
    pub ty: u32,
    pub from: u64,
    pub to: u64,
    pub props: BTreeMap<u32, PropValue>,
    pub valid_from: i64,
    pub valid_to: Option<i64>,
}
/// Encodes `r` as the live v3 row: interns `r.scope` into the scope registry
/// (writing a fresh row to `scopes_table` only the first time a given scope
/// is seen) rather than requiring the caller to have pre-interned it.
pub(crate) fn node_to_disk_v3(
    r: &NodeRecord,
    t: &mut Table<'_, &'static [u8], &'static str>,
    d: &mut Dicts,
    scopes_table: &mut Table<'_, &'static [u8], &'static [u8]>,
    scopes: &mut ScopeRegistry,
) -> Result<NodeRecordDiskV3, TopoError> {
    let mut p = BTreeMap::new();
    for (k, v) in &r.props {
        p.insert(d.intern(t, DictKind::PropKey, k)?, v.clone());
    }
    Ok(NodeRecordDiskV3 {
        id: r.id,
        scope: scopes.intern(scopes_table, r.scope)?,
        label: d.intern(t, DictKind::Label, r.label.as_str())?,
        props: p,
    })
}
pub(crate) fn node_from_disk_v3(
    r: NodeRecordDiskV3,
    d: &Dicts,
    scopes: &ScopeRegistry,
) -> Result<NodeRecord, TopoError> {
    let mut p = crate::props::Props::new();
    for (k, v) in r.props {
        p.insert(d.resolve(DictKind::PropKey, k)?.to_string(), v);
    }
    Ok(NodeRecord {
        id: r.id,
        scope: scopes.resolve(r.scope)?,
        label: d.resolve(DictKind::Label, r.label)?,
        props: p,
        embedding: None,
    })
}
/// Same scope-interning behavior as `node_to_disk_v3`, plus resolves `r.from`/
/// `r.to` to their (already-allocated) node slots via `node_slots`. The
/// endpoints were validated to exist immediately before this is called on
/// every call path, so a missing slot here is `TopoError::Encoding`
/// (corruption), never `Rejected`.
#[allow(clippy::too_many_arguments)]
pub(crate) fn edge_to_disk_v3(
    r: &EdgeRecord,
    t: &mut Table<'_, &'static [u8], &'static str>,
    d: &mut Dicts,
    scopes_table: &mut Table<'_, &'static [u8], &'static [u8]>,
    scopes: &mut ScopeRegistry,
    node_slots: &impl ReadableTable<&'static [u8], &'static [u8]>,
) -> Result<EdgeRecordDiskV3, TopoError> {
    let mut p = BTreeMap::new();
    for (k, v) in &r.props {
        p.insert(d.intern(t, DictKind::PropKey, k)?, v.clone());
    }
    let from = crate::slots::node_slot(node_slots, r.from)?
        .ok_or_else(|| TopoError::Encoding("edge_to_disk_v3: missing from slot".into()))?;
    let to = crate::slots::node_slot(node_slots, r.to)?
        .ok_or_else(|| TopoError::Encoding("edge_to_disk_v3: missing to slot".into()))?;
    Ok(EdgeRecordDiskV3 {
        id: r.id,
        scope: scopes.intern(scopes_table, r.scope)?,
        ty: d.intern(t, DictKind::EdgeType, r.ty.as_str())?,
        from,
        to,
        props: p,
        valid_from: r.valid_from,
        valid_to: r.valid_to,
    })
}
/// Resolves `r.from`/`r.to` slots back to ULIDs via `node_ids`. A miss is
/// `TopoError::Encoding` — every edge row's endpoints must have a live
/// NODE_IDS entry for as long as the edge row itself exists.
pub(crate) fn edge_from_disk_v3(
    r: EdgeRecordDiskV3,
    d: &Dicts,
    scopes: &ScopeRegistry,
    node_ids: &impl ReadableTable<&'static [u8], &'static [u8]>,
) -> Result<EdgeRecord, TopoError> {
    let mut p = crate::props::Props::new();
    for (k, v) in r.props {
        p.insert(d.resolve(DictKind::PropKey, k)?.to_string(), v);
    }
    let from = crate::slots::node_ulid(node_ids, r.from)?
        .ok_or_else(|| TopoError::Encoding("edge_from_disk_v3: missing from ulid".into()))?;
    let to = crate::slots::node_ulid(node_ids, r.to)?
        .ok_or_else(|| TopoError::Encoding("edge_from_disk_v3: missing to ulid".into()))?;
    Ok(EdgeRecord {
        id: r.id,
        scope: scopes.resolve(r.scope)?,
        ty: d.resolve(DictKind::EdgeType, r.ty)?,
        from,
        to,
        props: p,
        valid_from: r.valid_from,
        valid_to: r.valid_to,
    })
}