Skip to main content

eidetic/
bundle.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! `Bundle` — a typed payload that carries a list of typed memory
5//! references. The composite-engram pattern from the inherited
6//! `engram_spec.md` `TransferProfile`, narrowed to a stable Mere shape.
7//!
8//! ## Why a generic Bundle
9//!
10//! A bundle is what you reach for when an engram naturally decomposes
11//! into multiple sub-engrams that share a common envelope:
12//!
13//! - A model engram (config, weights, tokenizer)
14//! - A moot-snapshot engram (member set, accepted schemas, content corpus)
15//! - A federated `SearchIndex` contribution (segments, ranking config,
16//!   eval receipt)
17//!
18//! Rather than each domain inventing its own ad-hoc composite struct, the
19//! shared `Bundle` schema lets a recipient that knows nothing about
20//! "models" or "moots" still inspect the structure: walk the member list,
21//! verify required members exist, fetch each sub-engram. Domain semantics
22//! land in the `kind` field on each member and in the bundle's
23//! `bundle_kind`.
24//!
25//! ## Composability
26//!
27//! Bundles compose: a bundle member can itself be another bundle. The
28//! recipient's load loop is the same regardless. Per the engram_spec
29//! "Sparse is valid" rule, a consumer is free to use only the members it
30//! cares about and ignore the rest, as long as `required: true` members
31//! are present.
32
33use serde::{Deserialize, Serialize};
34
35use crate::manifest::{BlobFetcher, BlobSource, load_manifest, resolve_blob};
36use crate::schema::{
37    Hash, ManifestId, PrivacyClass, ProvenanceRecord, SchemaRef, Timestamp, TrustEnvelope,
38};
39use crate::typed::{TypedPayload, load_typed, save_typed};
40use crate::{Error, Result, Store};
41
42/// Canonical bytes of the `Bundle` schema engram payload.
43///
44/// Mere-native schema. Stable; its BLAKE3 hash is [`BUNDLE_SCHEMA_REF`].
45const BUNDLE_SCHEMA_PAYLOAD: &[u8] = br#"{"format":"mere-native","schema_id":"eidetic.Bundle/v1","body":{"version":1,"description":"A composite engram referencing other engrams by manifest id.","required":["bundle_id","bundle_kind","members"],"fields":{"bundle_id":{"type":"string"},"bundle_kind":{"type":"string"},"description":{"type":"string"},"members":{"type":"array"}}}}"#;
46
47/// Compute the well-known `Bundle` schema reference (lazy).
48pub fn bundle_schema_ref() -> SchemaRef {
49    SchemaRef::from_id(ManifestId::from_hash(Hash::of(BUNDLE_SCHEMA_PAYLOAD)))
50}
51
52/// The well-known schema reference for `Bundle` engrams.
53pub static BUNDLE_SCHEMA_REF: std::sync::LazyLock<SchemaRef> =
54    std::sync::LazyLock::new(bundle_schema_ref);
55
56/// One referenced member of a bundle.
57#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
58pub struct BundleMember {
59    /// Domain-level kind tag (e.g. `"weights"`, `"tokenizer"`,
60    /// `"ranking-policy"`). Free-form; consumers branch on it.
61    pub kind: String,
62    /// Pointer to the sub-engram's manifest.
63    pub manifest: ManifestId,
64    /// Whether the bundle is unusable without this member (per the
65    /// engram_spec "required_for_application" rule).
66    #[serde(default)]
67    pub required: bool,
68    /// Optional human-readable note.
69    #[serde(default)]
70    pub note: Option<String>,
71}
72
73/// Composite engram payload. Carries a list of typed memory references
74/// under a shared envelope.
75#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
76pub struct Bundle {
77    /// Human-readable id. Diagnostics-only; identity comes from the
78    /// engram's content hash.
79    pub bundle_id: String,
80    /// Domain category (e.g. `"model"`, `"moot-snapshot"`,
81    /// `"search-index"`). Free-form; consumers route on it.
82    pub bundle_kind: String,
83    #[serde(default)]
84    pub description: String,
85    pub members: Vec<BundleMember>,
86}
87
88impl TypedPayload for Bundle {
89    fn schema_ref() -> SchemaRef {
90        *BUNDLE_SCHEMA_REF
91    }
92}
93
94impl Bundle {
95    /// Find a single member by `kind`. Returns `None` if no member has
96    /// the requested kind; the first match if multiple.
97    pub fn member(&self, kind: &str) -> Option<&BundleMember> {
98        self.members.iter().find(|m| m.kind == kind)
99    }
100
101    /// Iterate the member references the bundle declares as required.
102    pub fn required_members(&self) -> impl Iterator<Item = &BundleMember> {
103        self.members.iter().filter(|m| m.required)
104    }
105}
106
107/// Save a bundle and return its manifest id.
108#[allow(clippy::too_many_arguments)]
109pub async fn save_bundle(
110    store: &mut dyn Store,
111    bundle: &Bundle,
112    additional_sources: Vec<BlobSource>,
113    privacy: PrivacyClass,
114    provenance: ProvenanceRecord,
115    trust: TrustEnvelope,
116    created_at: Timestamp,
117) -> Result<ManifestId> {
118    save_typed(
119        store,
120        bundle,
121        additional_sources,
122        privacy,
123        provenance,
124        trust,
125        created_at,
126    )
127    .await
128}
129
130/// Load a bundle by manifest id.
131pub async fn load_bundle(
132    store: &mut dyn Store,
133    fetcher: &mut dyn BlobFetcher,
134    id: ManifestId,
135) -> Result<Option<Bundle>> {
136    load_typed::<Bundle>(store, fetcher, id).await
137}
138
139/// Verify that every `required` member is locally resolvable. Errors
140/// listing the missing required members on first failure.
141///
142/// The check loads each required member's manifest and attempts to
143/// resolve its blob — sources are tried in order, hash-verified per the
144/// usual `resolve_blob` machinery. Non-required members that are missing
145/// are tolerated.
146pub async fn verify_required_members(
147    store: &mut dyn Store,
148    fetcher: &mut dyn BlobFetcher,
149    bundle: &Bundle,
150) -> Result<()> {
151    let mut missing: Vec<String> = Vec::new();
152    for member in bundle.required_members() {
153        let manifest = match load_manifest(store, member.manifest).await? {
154            Some(m) => m,
155            None => {
156                missing.push(format!(
157                    "{} (manifest {} not found)",
158                    member.kind, member.manifest
159                ));
160                continue;
161            }
162        };
163        if let Err(e) = resolve_blob(store, fetcher, &manifest).await {
164            missing.push(format!("{} ({})", member.kind, e));
165        }
166    }
167    if !missing.is_empty() {
168        return Err(Error::new(format!(
169            "bundle {} missing required members: {}",
170            bundle.bundle_id,
171            missing.join("; ")
172        )));
173    }
174    Ok(())
175}
176
177#[cfg(test)]
178mod tests {
179    use super::*;
180    use crate::manifest::NoFetcher;
181    use crate::schema::{
182        ModerationState, ProvenanceOrigin, ProvenanceRecord, Timestamp, TrustLevel,
183    };
184    use async_trait::async_trait;
185    use std::collections::HashMap;
186
187    // The in-memory test store is muniment's (2026-07-12): eidetic's
188    // hand-rolled one was the same map behind the same seam.
189    use muniment::MemoryBackend as InMemoryStore;
190
191    fn test_provenance() -> ProvenanceRecord {
192        ProvenanceRecord {
193            origin: ProvenanceOrigin::Generated,
194            upstream: Vec::new(),
195            tooling: Some("eidetic-bundle-test".to_string()),
196            generated_at: Timestamp(0),
197        }
198    }
199
200    fn test_trust() -> TrustEnvelope {
201        TrustEnvelope {
202            level: TrustLevel::SelfAsserted,
203            signatures: Vec::new(),
204            moderation_state: ModerationState::Unreviewed,
205        }
206    }
207
208    fn fake_member(kind: &str, blob: &[u8], required: bool) -> BundleMember {
209        BundleMember {
210            kind: kind.to_string(),
211            manifest: ManifestId::of_blob(blob),
212            required,
213            note: None,
214        }
215    }
216
217    #[test]
218    fn save_then_load_bundle_round_trips() {
219        pollster::block_on(async {
220            let mut store = InMemoryStore::default();
221            let mut fetcher = NoFetcher;
222
223            let bundle = Bundle {
224                bundle_id: "fake-model".to_string(),
225                bundle_kind: "model".to_string(),
226                description: "Just a test bundle".to_string(),
227                members: vec![
228                    fake_member("weights", b"weights-bytes", true),
229                    fake_member("tokenizer", b"tokenizer-bytes", true),
230                    fake_member("eval-receipt", b"eval-bytes", false),
231                ],
232            };
233
234            let id = save_bundle(
235                &mut store,
236                &bundle,
237                Vec::new(),
238                PrivacyClass::LocalOnly,
239                test_provenance(),
240                test_trust(),
241                Timestamp(0),
242            )
243            .await
244            .unwrap();
245
246            let loaded = load_bundle(&mut store, &mut fetcher, id)
247                .await
248                .unwrap()
249                .expect("bundle present");
250            assert_eq!(loaded, bundle);
251        });
252    }
253
254    #[test]
255    fn member_lookup_finds_kind() {
256        let bundle = Bundle {
257            bundle_id: "x".to_string(),
258            bundle_kind: "test".to_string(),
259            description: String::new(),
260            members: vec![
261                fake_member("a", b"a", false),
262                fake_member("b", b"b", true),
263                fake_member("c", b"c", false),
264            ],
265        };
266        assert_eq!(bundle.member("a").unwrap().kind, "a");
267        assert_eq!(bundle.member("b").unwrap().kind, "b");
268        assert!(bundle.member("missing").is_none());
269
270        let required: Vec<&str> = bundle.required_members().map(|m| m.kind.as_str()).collect();
271        assert_eq!(required, vec!["b"]);
272    }
273
274    #[test]
275    fn verify_required_members_passes_when_all_present() {
276        pollster::block_on(async {
277            let mut store = InMemoryStore::default();
278            let mut fetcher = NoFetcher;
279
280            // Save two opaque blobs the bundle will reference.
281            let weights_bytes = b"weights".to_vec();
282            let tokenizer_bytes = b"tokenizer".to_vec();
283            let weights_id = save_opaque(&mut store, &weights_bytes).await;
284            let tokenizer_id = save_opaque(&mut store, &tokenizer_bytes).await;
285
286            let bundle = Bundle {
287                bundle_id: "m".to_string(),
288                bundle_kind: "model".to_string(),
289                description: String::new(),
290                members: vec![
291                    BundleMember {
292                        kind: "weights".to_string(),
293                        manifest: weights_id,
294                        required: true,
295                        note: None,
296                    },
297                    BundleMember {
298                        kind: "tokenizer".to_string(),
299                        manifest: tokenizer_id,
300                        required: true,
301                        note: None,
302                    },
303                ],
304            };
305
306            verify_required_members(&mut store, &mut fetcher, &bundle)
307                .await
308                .unwrap();
309        });
310    }
311
312    #[test]
313    fn verify_required_members_errors_listing_missing() {
314        pollster::block_on(async {
315            let mut store = InMemoryStore::default();
316            let mut fetcher = NoFetcher;
317
318            // Bundle references members that were never saved.
319            let bundle = Bundle {
320                bundle_id: "m".to_string(),
321                bundle_kind: "model".to_string(),
322                description: String::new(),
323                members: vec![
324                    BundleMember {
325                        kind: "weights".to_string(),
326                        manifest: ManifestId::of_blob(b"never-saved-weights"),
327                        required: true,
328                        note: None,
329                    },
330                    BundleMember {
331                        kind: "optional-extra".to_string(),
332                        manifest: ManifestId::of_blob(b"never-saved-extra"),
333                        required: false,
334                        note: None,
335                    },
336                ],
337            };
338
339            let result = verify_required_members(&mut store, &mut fetcher, &bundle).await;
340            assert!(result.is_err());
341            let msg = format!("{}", result.unwrap_err());
342            assert!(msg.contains("weights"), "got: {msg}");
343            assert!(
344                !msg.contains("optional-extra"),
345                "non-required member shouldn't appear: {msg}"
346            );
347        });
348    }
349
350    /// Helper: save raw bytes as an opaque manifest in the store.
351    async fn save_opaque(store: &mut dyn Store, bytes: &[u8]) -> ManifestId {
352        let hash = Hash::of(bytes);
353        let id = ManifestId::from_hash(hash);
354        let local_key = format!("blob:{}", hash.to_hex());
355        store.put(&local_key, bytes).await.unwrap();
356        let manifest = crate::manifest::BlobManifest {
357            id,
358            schema: SchemaRef::from_id(ManifestId::of_blob(b"opaque")),
359            content_hash: hash,
360            byte_size: bytes.len() as u64,
361            created_at: Timestamp(0),
362            last_accessed: None,
363            sources: vec![BlobSource::Local { key: local_key }],
364            privacy: PrivacyClass::LocalOnly,
365            provenance: test_provenance(),
366            trust: test_trust(),
367            schema_metadata: serde_json::Value::Null,
368            manifest_version: crate::manifest::BlobManifest::CURRENT_VERSION,
369        };
370        crate::manifest::save_manifest(store, &manifest)
371            .await
372            .unwrap();
373        id
374    }
375
376    #[test]
377    fn schema_ref_is_stable() {
378        assert_eq!(bundle_schema_ref(), *BUNDLE_SCHEMA_REF);
379    }
380}