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
//! Standalone SQLite snapshots of portable workspace records and asset bytes.
//!
//! Loading never consults source checkouts or executes authored code. Database
//! values remain untrusted until structural and content validation succeeds.
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use crate::assembly::{AssemblyError, WorkspaceSources};
use crate::configuration::PresentationDefaults;
use crate::ir::{AssetReference, Workspace};
use crate::validation::{ContentAsset, ResolvedDocument, ResolvedWorkspace};
mod canonical;
mod outputs;
mod storage;
mod validation;
pub(crate) fn sqlite_sidecar_paths(path: &Path) -> [PathBuf; 3] {
["-journal", "-wal", "-shm"].map(|suffix| {
let mut companion = path.as_os_str().to_owned();
companion.push(suffix);
PathBuf::from(companion)
})
}
/// Independent SQLite storage schema version.
pub const STORAGE_SCHEMA_VERSION: u32 = 2;
/// Canonical record encoding version, independent of database layout.
///
/// Version 1 sorts JSON object keys recursively, preserves semantic array
/// order, and hashes compact UTF-8 JSON with SHA-256. See the snapshot schema
/// contract for the record envelope and logical snapshot encoding.
pub const RECORD_ENCODING_VERSION: u32 = 1;
/// A complete portable snapshot, with immutable validated records and bytes.
#[derive(Debug)]
pub struct Snapshot {
bundle: bool,
workspace: Workspace,
presentation: PresentationDefaults,
pub(crate) package_mounts: BTreeMap<String, String>,
pub(crate) public_assets: BTreeMap<String, String>,
logo: Option<AssetReference>,
open_graph: Option<AssetReference>,
components: BTreeMap<String, crate::components::ComponentBundle>,
documents: Vec<ResolvedDocument>,
assets: BTreeMap<String, ContentAsset>,
producer: String,
executions: BTreeMap<String, outputs::StoredPage>,
validated_outputs: BTreeMap<String, crate::execution::ValidatedPage>,
}
/// Snapshot storage or validation failed without a publishable replacement.
#[derive(Debug, thiserror::Error)]
pub enum SnapshotError {
/// Input observations changed before the portable copy was made.
#[error(transparent)]
Inputs(#[from] AssemblyError),
/// Snapshot filesystem access failed.
#[error("snapshot I/O failed: {0}")]
Io(#[from] std::io::Error),
/// The database could not be read or written.
#[error("snapshot database operation failed: {0}")]
Database(#[from] rusqlite::Error),
/// A record failed typed decoding or encoding.
#[error("snapshot record encoding failed: {0}")]
Encoding(#[from] serde_json::Error),
/// The reader cannot interpret this schema or encoding.
#[error("unsupported snapshot storage, IR, or record encoding version")]
Version,
/// A required record, identity, reference, or asset is invalid.
#[error("invalid snapshot: {0}")]
Invalid(&'static str),
}
impl Snapshot {
/// Copy statically assembled and resolved records while rechecking inputs.
///
/// This operation does not execute eligible cells. Commands that authorize
/// execution must first run the workspace execution operation.
pub fn from_sources(
sources: &WorkspaceSources,
resolved: &ResolvedWorkspace,
) -> Result<Self, SnapshotError> {
Self::from_resolved(sources, resolved, false)
}
fn from_resolved(
sources: &WorkspaceSources,
resolved: &ResolvedWorkspace,
bundle: bool,
) -> Result<Self, SnapshotError> {
sources.revalidate()?;
resolved.revalidate()?;
let mut workspace = sources.workspace().clone();
workspace.diagnostics = resolved.diagnostics().clone();
let mut snapshot = Self {
bundle,
workspace,
presentation: sources.configuration().presentation.clone(),
package_mounts: sources.bundles.mounts.clone(),
public_assets: resolved.public_assets.clone(),
logo: resolved.logo().cloned(),
open_graph: resolved.open_graph().cloned(),
components: resolved.components.clone(),
documents: resolved.records().to_vec(),
assets: resolved.assets().clone(),
producer: env!("CARGO_PKG_VERSION").into(),
executions: BTreeMap::new(),
validated_outputs: BTreeMap::new(),
};
snapshot.validated_outputs = snapshot.validate()?;
Ok(snapshot)
}
pub(crate) fn from_bundle(
sources: &WorkspaceSources,
resolved: &ResolvedWorkspace,
) -> Result<Self, SnapshotError> {
Self::from_resolved(sources, resolved, true)
}
pub(crate) fn load_bundle(path: &Path) -> Result<Self, SnapshotError> {
storage::load_kind(path, true)
}
/// Portable semantic records; no runtime checkout paths are stored.
pub fn workspace(&self) -> &Workspace {
&self.workspace
}
/// Recorded site defaults, available without the original configuration.
pub fn presentation(&self) -> &PresentationDefaults {
&self.presentation
}
/// Retained browser component bundles, inert until generation enables them.
pub fn components(&self) -> &BTreeMap<String, crate::components::ComponentBundle> {
&self.components
}
/// Public files indexed by publication path, with values naming asset digests.
pub fn public_assets(&self) -> &BTreeMap<String, String> {
&self.public_assets
}
/// Portable navbar image, available without the original repository.
pub fn logo(&self) -> Option<&AssetReference> {
self.logo.as_ref()
}
/// Portable social preview image, available without the original repository.
pub fn open_graph(&self) -> Option<&AssetReference> {
self.open_graph.as_ref()
}
/// Diplodocus version that originally produced this snapshot.
pub fn producer(&self) -> &str {
&self.producer
}
/// Resolved references and authored anchor sets in semantic document order.
pub fn documents(&self) -> &[ResolvedDocument] {
&self.documents
}
/// Complete content bytes, indexed by their SHA-256 digest.
pub fn assets(&self) -> &BTreeMap<String, ContentAsset> {
&self.assets
}
/// Load and validate a standalone database using a read-only connection.
pub fn load(path: impl AsRef<Path>) -> Result<Self, SnapshotError> {
storage::load(path.as_ref())
}
/// Atomically replace a snapshot with a completed, closed database.
///
/// Errors leave an existing destination untouched. SQLite journal, WAL, or
/// shared-memory sidecars at the destination prevent replacement.
///
/// The caller must protect declared input paths before selecting the target
/// and prevent external SQLite writers from modifying it during publication.
pub fn publish(&self, path: impl AsRef<Path>) -> Result<(), SnapshotError> {
self.validate()?;
storage::publish(self, path.as_ref())
}
/// Canonical readable records and asset bytes, independent of SQLite layout.
///
/// The versioned JSON export includes per-record fingerprints and base64
/// asset bytes. It uses two-space indentation and one trailing newline.
/// Comparing exports compares all portable records, including provenance
/// and producer versions; it does not compare only rendered content.
pub fn canonical_export(&self) -> Result<String, SnapshotError> {
canonical::canonical_export(self)
}
}